> ## Documentation Index
> Fetch the complete documentation index at: https://operativusai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol (MCP) Integration

> How to connect MCP-compatible clients like Claude Desktop and Cursor to Agent Manager, authenticate over SSE, and invoke your agents as MCP tools.

Agent Manager implements the [Model Context Protocol](https://modelcontextprotocol.io) (MCP) as a server. This means every agent you've registered in Agent Manager is automatically exposed as an MCP tool, accessible from any MCP-compatible client — including Claude Desktop, Cursor, and other AI-enabled IDEs.

## How it works

When an MCP client connects to Agent Manager, it receives a list of available tools. Each registered agent appears as a callable tool named `run_{agentId}`. Clients invoke agents using standard JSON-RPC 2.0 calls over an SSE connection.

```
MCP Client (e.g., Claude Desktop)
         │
         │  GET /mcp/sse         ← handshake + capability negotiation
         │  POST /mcp/messages   ← JSON-RPC tool calls
         ▼
  Agent Manager MCP Server
         │
         ▼
  Your registered agents
```

## Connecting an MCP client

<Steps>
  <Step title="Obtain a Bearer token">
    Authenticate via `POST /api/auth/login` and copy the returned `token` value. See [Authenticating Requests](/security/authentication) for details.
  </Step>

  <Step title="Configure your MCP client">
    Point your client at the Agent Manager SSE endpoint and include your token in the headers.

    **Claude Desktop** (`claude_desktop_config.json`):

    ```json theme={null}
    {
      "mcpServers": {
        "agent-manager": {
          "url": "http://your-host/mcp/sse",
          "headers": {
            "Authorization": "Bearer eyJhbGciOiJIUzI1NiJ9..."
          }
        }
      }
    }
    ```

    **Cursor** (MCP server settings):

    ```json theme={null}
    {
      "name": "Agent Manager",
      "url": "http://your-host/mcp/sse",
      "headers": {
        "Authorization": "Bearer eyJhbGciOiJIUzI1NiJ9..."
      }
    }
    ```
  </Step>

  <Step title="Verify the connection">
    After saving the configuration, your MCP client should show Agent Manager in its server list. You'll see tools like `list_agents` and `run_finance_agent` (one `run_` tool per registered agent).
  </Step>
</Steps>

## MCP endpoints

| Method | Endpoint        | Description                                                             |
| ------ | --------------- | ----------------------------------------------------------------------- |
| `GET`  | `/mcp/sse`      | MCP handshake — opens an SSE connection and returns server capabilities |
| `POST` | `/mcp/messages` | JSON-RPC 2.0 message handler — receives tool calls and returns results  |

### Handshake

When a client connects to `GET /mcp/sse`, Agent Manager sends an `endpoint` event containing the session-scoped message URL:

```
event: endpoint
data: /mcp/messages?sessionId=<session-uuid>
```

The client then uses this URL for all subsequent `POST /mcp/messages` calls within the session.

### JSON-RPC methods

Agent Manager handles the following MCP JSON-RPC methods:

| Method       | Description                                                            |
| ------------ | ---------------------------------------------------------------------- |
| `initialize` | Capability negotiation. Returns protocol version and server info.      |
| `tools/list` | Returns all available tools (system tools + one per registered agent). |
| `tools/call` | Executes a tool (agent run or `list_agents`).                          |

## Available tools

Once connected, your client sees two categories of tools:

<AccordionGroup>
  <Accordion title="list_agents">
    A system tool that returns the list of agents registered in Agent Manager. Useful for discovery.

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tools/call",
      "params": {
        "name": "list_agents",
        "arguments": {}
      }
    }
    ```
  </Accordion>

  <Accordion title="run_{agentId}">
    One tool per registered agent. Each tool accepts a `message` parameter — the prompt to send to the agent — and returns the agent's response as text.

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 2,
      "method": "tools/call",
      "params": {
        "name": "run_finance_agent",
        "arguments": {
          "message": "What is the current price of AAPL?"
        }
      }
    }
    ```

    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 2,
      "result": {
        "content": [
          {
            "type": "text",
            "text": "AAPL is currently trading at $189.42..."
          }
        ]
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Authentication for MCP

MCP connections follow the same authentication model as the REST API. Include your `Authorization: Bearer {token}` header in the MCP client's header configuration. Connections without a valid token are rejected.

<Warning>
  MCP client tokens have the same expiry as regular JWTs. If your client starts receiving authentication errors after extended use, re-authenticate via `POST /api/auth/login` and update the token in your client's MCP server configuration.
</Warning>

## Protocol version

Agent Manager implements MCP protocol version `0.1.0`. It declares `tools` as its capability set — each registered agent is exposed as a tool that any compliant client can discover and invoke.