# MCP Server

> Connect your IDE to PromptRails with the built-in MCP server for Claude Desktop, Cursor, Windsurf, and other MCP-compatible tools.

Source: https://0.0.0.0:8080/docs/mcp-server

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

## Connection Configuration

### Claude Desktop

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

```json
{
  "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):

```json
{
  "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:

```json
{
  "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"
      }
    }
  }
}
```

## 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:

```
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
```

## Related Topics

- [CLI](/docs/cli) -- CLI installation (required for the MCP server)
- [MCP Tools](/docs/mcp-tools) -- Using MCP tools within agents
- [API Keys and Scopes](/docs/api-keys-and-scopes) -- Authentication