MCP Server

Connect coding assistants and MCP-compatible tools to your PromptRails workspace.

Best for

Engineers building against the API, SDKs, CLI, MCP, or local tooling

MCP Server

The MCP server lets external AI tools work with your PromptRails workspace. Instead of copying API calls by hand, a coding assistant can inspect agents, prompts, executions, traces, and other resources through a controlled local server.

This page is mainly for engineers setting up Claude Desktop, Cursor, Windsurf, or another MCP-compatible client.

PromptRails includes a built-in MCP (Model Context Protocol) server that exposes workspace operations as tools for AI-powered IDEs. This enables you to manage prompts, run agents, review traces, and more directly from Claude Desktop, Cursor, Windsurf, or any MCP-compatible client.

What is the MCP Server?

The MCP server translates PromptRails API operations into MCP tools that AI assistants can invoke. When connected, your IDE’s AI assistant can:

Create and manage agents, prompts, and data sources
Execute agents and view results
Browse execution traces and costs
Manage credentials, guardrails, and memories
Find executions paused for human approval
Send chat messages

Technical detailsClient connection snippets

Connection Configuration

Claude Desktop

Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "promptrails": {
      "command": "promptrails",
      "args": ["mcp", "serve"],
      "env": {
        "PROMPTRAILS_API_KEY": "your-api-key",
        "PROMPTRAILS_WORKSPACE_ID": "your-workspace-id",
        "PROMPTRAILS_API_URL": "https://api.promptrails.ai"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json in your project root):

{
  "mcpServers": {
    "promptrails": {
      "command": "promptrails",
      "args": ["mcp", "serve"],
      "env": {
        "PROMPTRAILS_API_KEY": "your-api-key",
        "PROMPTRAILS_WORKSPACE_ID": "your-workspace-id",
        "PROMPTRAILS_API_URL": "https://api.promptrails.ai"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "promptrails": {
      "command": "promptrails",
      "args": ["mcp", "serve"],
      "env": {
        "PROMPTRAILS_API_KEY": "your-api-key",
        "PROMPTRAILS_WORKSPACE_ID": "your-workspace-id",
        "PROMPTRAILS_API_URL": "https://api.promptrails.ai"
      }
    }
  }
}

Technical detailsAvailable MCP tool reference

Available Tools

The MCP server exposes tools across all major PromptRails resource categories:

Agents

Tool	Description
`list_agents`	List all agents in the workspace
`get_agent`	Get agent details by ID
`create_agent`	Create a new agent
`update_agent`	Update agent properties
`delete_agent`	Delete an agent
`execute_agent`	Execute an agent with input
`list_agent_versions`	List versions of an agent
`create_agent_version`	Create a new agent version

Prompts

Tool	Description
`list_prompts`	List all prompts
`get_prompt`	Get prompt details
`create_prompt`	Create a new prompt
`update_prompt`	Update prompt properties
`delete_prompt`	Delete a prompt
`list_prompt_versions`	List prompt versions
`create_prompt_version`	Create a prompt version

Data Sources

Tool	Description
`list_data_sources`	List data sources
`get_data_source`	Get data source details
`create_data_source`	Create a data source
`update_data_source`	Update a data source
`delete_data_source`	Delete a data source
`query_data_source`	Execute a data source query

Chat

Tool	Description
`list_chat_sessions`	List chat sessions
`get_chat_session`	Get a chat session
`create_chat_session`	Create a chat session
`delete_chat_session`	Delete a chat session
`list_chat_messages`	List session messages
`send_chat_message`	Send a chat message

Credentials

Tool	Description
`list_credentials`	List credentials (masked)
`get_credential`	Get credential metadata
`create_credential`	Create a credential
`update_credential`	Update a credential
`delete_credential`	Delete a credential

MCP Templates

Tool	Description
`list_mcp_templates`	Browse integration templates
`get_mcp_template`	Get a template by ID
`get_mcp_template_by_slug`	Get a template by slug
`install_mcp_template`	Install a configured workspace tool

MCP Tools

Tool	Description
`list_mcp_tools`	List MCP tools
`get_mcp_tool`	Get MCP tool details
`create_mcp_tool`	Create an MCP tool
`update_mcp_tool`	Update an MCP tool
`delete_mcp_tool`	Delete an MCP tool

Guardrails

Tool	Description
`list_guardrails`	List guardrails for an agent
`create_guardrail`	Add a guardrail to an agent
`update_guardrail`	Update guardrail config
`delete_guardrail`	Remove a guardrail

Executions

Tool	Description
`list_executions`	List executions
`get_execution`	Get execution details

Traces

Tool	Description
`list_traces`	List trace spans
`get_trace`	Get span details
`get_trace_summary`	Summarize a trace

Scores

Tool	Description
`list_scores`	List scores
`get_score`	Get score details
`create_score`	Create a score
`delete_score`	Delete a score
`get_score_aggregates`	Get aggregate score metrics
`list_score_configs`	List score configurations
`create_score_config`	Create a score configuration
`delete_score_config`	Delete a score configuration

Approval-gated runs appear through list_executions with status waiting_approval. Decisions are made through the execution approval surface in PromptRails or the execution approve/deny API; the MCP server does not expose legacy approval-request tools.

API Key Authentication

The MCP server authenticates using the same API keys used by the SDKs. The key’s scopes determine which tools are available:

An API key with agents:read scope enables list_agents and get_agent
An API key with * scope enables all tools

Example Usage

Once connected, you can interact with PromptRails naturally through your IDE’s AI assistant:

Technical detailsExample MCP assistant interaction

User: "List my agents"
Assistant: [calls list_agents] You have 5 agents:
1. Customer Support Bot (agent, active)
2. Data Pipeline (workflow, active)
...

User: "Execute the Customer Support Bot with message 'What are your hours?'"
Assistant: [calls execute_agent] The agent responded:
"Our support hours are Monday-Friday, 9am-5pm EST..."
Cost: $0.002, Duration: 1.2s

User: "Show me the trace for that execution"
Assistant: [calls list_traces] The execution trace shows:
1. [agent] Customer Support Bot (1200ms)
   - [guardrail] prompt_injection scan (15ms) - OK
   - [prompt] Render main prompt (2ms)
   - [llm] gpt-4o call (1150ms, 340 tokens, $0.002)
   - [guardrail] pii output scan (8ms) - OK

CLI — CLI installation (required for the MCP server)
MCP Tools — Using MCP tools within agents
API Keys and Scopes — Authentication

MCP Server

MCP Server

What is the MCP Server?

Connection Configuration

Claude Desktop

Cursor

Windsurf

Available Tools

Agents

Prompts

Data Sources

Chat

Credentials

MCP Templates

MCP Tools

Guardrails

Executions

Traces

Scores

API Key Authentication

Example Usage

Related Topics