MCP integration
Agent Handler exposes its tools over MCP. Most agent runtimes - Claude Desktop, Cursor, Windsurf, VS Code, ChatGPT - speak MCP natively, so connecting them is a matter of pasting a URL into a config file. If you’re building your own agent runtime, this page also covers the wire protocol.
Prerequisites
You need three things, all from your dashboard.
- Tool Pack ID. From the Tool Packs page; copy from the URL of the pack you want to expose.
- Registered User ID. From the Registered Users page; use a test user for development.
- Access Key. Production key for production users, test key for test users - they don’t mix. See Access Keys.
The MCP URL
Every MCP connection points at this URL pattern:
The URL identifies what tools (the Tool Pack) and whose credentials (the Registered User). The Access Key in the Authorization header authorizes the call. All three values are needed on every connection.
For the Context layer for employees setup, there’s a simplified URL that handles Tool Pack and user resolution through SSO instead.
Connect an MCP client
Claude Desktop
Cursor
Windsurf
VS Code
Other clients
Open Settings → Developer → Edit Config and paste:
Restart Claude Desktop. The first launch downloads mcp-remote (Node 20+ required).
Build a custom MCP client (SDK)
Use the official MCP SDK when your agent is a custom runtime. Anthropic ships an SDK in both Python and TypeScript - both handle the JSON-RPC framing, session ID generation, and streaming response handling.
Python
TypeScript
For custom transport behavior or a runtime that has no SDK, build directly against the wire protocol below.
Build a custom MCP client (raw protocol)
MCP is JSON-RPC 2.0 over HTTP. Three core methods cover the agent surface.
Python
TypeScript
The session ID rotates on Agent Handler’s side - read it back from the response header and use the new value for subsequent requests.
For streaming responses (large tool outputs), set Accept: text/event-stream and parse the response as Server-Sent Events. The SDKs handle this automatically; the raw clients above don’t.
Custom headers
Any header you send with an X- prefix is captured as metadata on the tool call and shown in the Tool Call Logs. Useful for tracing - set X-Chat-Id to your session ID and you can filter logs to one conversation. See Custom headers for MCP.
Common issues
- Tools not appearing in the client. Restart the client after editing config. Some clients cache aggressively; a hard restart usually fixes it. Check the client’s MCP log for connection errors.
401on every call. Double-check theAuthorizationheader format (Beareris required and case-sensitive) and that the API key matches the Registered User’s environment.- Session ID mismatch errors. Capture and re-use the session ID from response headers. Don’t generate a new one per request.
For a full troubleshooting catalog, see Troubleshooting.
Next
For command-line tool search and execution, use the Merge CLI.