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

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 the full platform API as tools for AI-powered IDEs. This enables you to manage agents, execute prompts, 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
Handle approval requests
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
`promote_agent_version`	Promote a version to current

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
`execute_prompt`	Execute a prompt
`list_prompt_versions`	List prompt versions
`create_prompt_version`	Create a prompt version
`promote_prompt_version`	Promote 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
`execute_data_source`	Execute a data source query

Chat

Tool	Description
`list_sessions`	List chat sessions
`create_session`	Create a chat session
`send_message`	Send a chat message

Credentials

Tool	Description
`list_credentials`	List credentials (masked)
`create_credential`	Create a credential
`validate_credential`	Test a credential

MCP Tools

Tool	Description
`list_mcp_tools`	List MCP tools
`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

Memories

Tool	Description
`list_memories`	List agent memories
`create_memory`	Create a memory
`search_memories`	Semantic memory search
`delete_memory`	Delete a memory

Approvals

Tool	Description
`list_approvals`	List approval requests
`decide_approval`	Approve or reject

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

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 (simple, active)
2. Data Pipeline (chain, 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