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

1. Obtain a Bearer token

   Authenticate via POST /api/auth/login and copy the returned token value. See Authenticating Requests for details.

2. 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):

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

   Cursor (MCP server settings):

   {
     "name": "Agent Manager",
     "url": "http://your-host/mcp/sse",
     "headers": {
       "Authorization": "Bearer eyJhbGciOiJIUzI1NiJ9..."
     }
   }
   
3. 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).

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:

list_agents

A system tool that returns the list of agents registered in Agent Manager. Useful for discovery.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_agents",
    "arguments": {}
  }
}

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.

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

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "AAPL is currently trading at $189.42..."
      }
    ]
  }
}

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.

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.

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.