# MCP Server Integration

PromptShuttle can connect to external [Model Context Protocol](https://modelcontextprotocol.io) (MCP) servers, discover their tools, and make them available to your flows. This lets you integrate with any MCP-compatible tool server without writing custom HTTP integrations.

## Workflow

```
1. Register an MCP server (URL + auth headers)
2. Discover available tools from the server
3. Import selected tools into your PromptShuttle tool library
4. Assign imported tools to flow templates
```

## Register an MCP server

```bash
curl -X POST https://app.promptshuttle.com/api/v1/mcp-servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Tool Server",
    "url": "https://mcp.example.com/sse",
    "headers": {
      "Authorization": "Bearer server_token_here"
    }
  }'
```

| Field     | Type   | Required | Description                                       |
| --------- | ------ | -------- | ------------------------------------------------- |
| `name`    | string | yes      | Display name for the server                       |
| `url`     | string | yes      | MCP server HTTP endpoint                          |
| `headers` | object | no       | Custom HTTP headers (auth tokens, API keys, etc.) |

## Discover tools

After registering a server, discover what tools it offers:

```bash
POST /api/v1/mcp-servers/{serverId}/discover
```

Returns a list of discovered tools:

```json
[
  {
    "name": "get_weather",
    "description": "Get current weather for a location",
    "inputSchema": {
      "type": "object",
      "properties": {
        "location": { "type": "string", "description": "City name" }
      },
      "required": ["location"]
    },
    "alreadyImported": false
  },
  {
    "name": "search_docs",
    "description": "Search documentation by keyword",
    "inputSchema": { "..." },
    "alreadyImported": true
  }
]
```

The `alreadyImported` flag indicates whether you've already imported this tool.

## Import tools

Select which discovered tools to import into your tool library:

```bash
curl -X POST https://app.promptshuttle.com/api/v1/mcp-servers/{serverId}/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolNames": ["get_weather", "search_docs"]
  }'
```

Imported tools appear in your tool library with:

* `type: Mcp`
* `mcpServerId` linking back to the registered server
* `rawInputSchema` preserving the original MCP schema
* Parameters converted to PromptShuttle's format for display

## Using imported MCP tools

Once imported, MCP tools work like any other tool:

1. Assign the tool to a template via `toolIds`
2. When the LLM calls the tool, PromptShuttle routes the call to the MCP server
3. The server's response is returned to the LLM as the tool result

## Managing MCP servers

| Method   | Endpoint                            | Description                 |
| -------- | ----------------------------------- | --------------------------- |
| `GET`    | `/api/v1/mcp-servers`               | List all registered servers |
| `GET`    | `/api/v1/mcp-servers/{id}`          | Get server details          |
| `POST`   | `/api/v1/mcp-servers`               | Register a new server       |
| `PUT`    | `/api/v1/mcp-servers/{id}`          | Update server config        |
| `DELETE` | `/api/v1/mcp-servers/{id}`          | Remove a server             |
| `POST`   | `/api/v1/mcp-servers/{id}/discover` | Discover tools from server  |
| `POST`   | `/api/v1/mcp-servers/{id}/import`   | Import selected tools       |

## Server status

Each registered server tracks:

| Field                 | Description                            |
| --------------------- | -------------------------------------- |
| `discoveredToolCount` | Number of tools found on last connect  |
| `lastConnectedAt`     | Timestamp of last successful discovery |