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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.promptshuttle.com/tools/mcp-servers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.