MCP integration guide

MCP is a client/server protocol where the server declares a catalogue of tools, each with a name, a description, and a JSON schema for inputs and outputs. The client (called a host in MCP language) connects to one or more servers and surfaces their tools to a language model. When the model decides to call a tool, the host routes the call over the same connection, receives the structured response, and feeds it back into the model's context.

The most important consequence of this shape: tool descriptions matter enormously. The model decides whether to call a tool based almost entirely on the description text. Vague descriptions cause false negatives (the tool is skipped) and false positives (it is called when something else was intended).

MCP supports two primary transports: stdio and HTTP Server-Sent Events. stdio is used when the host spawns the server as a child process and communicates over pipes — common for local filesystem servers, database connectors, and anything that runs on the same machine as the host.

SSE is used when the server is a remote HTTP endpoint, which is the right choice for AGNT. The host opens a persistent GET request to /mcp/sse, the server streams events as they happen, and the client posts tool invocations back through a companion POST endpoint. It works through any HTTP/1.1-capable network stack and is friendly to firewalls.

AGNT's MCP server is authenticated with a bearer token — the same agnt_live_ key you use for REST calls. Set it on the initial SSE upgrade request:

GET https://api.agntdot.com/mcp/sse HTTP/1.1
Authorization: Bearer agnt_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Accept: text/event-stream

All subsequent tool-call POST requests on the companion endpoint carry the same header. The key is validated once on connect and re-validated on every tool call so a revoked key is cut off immediately, not at the next handshake.

The production tool catalogue (as of the last verification date on this guide) contains: search_venues, list_venues, read_user_memory, query_knowledge_graph, and write_user_memory. The last is gated on the memory.write scope on your key.

Each tool has a strict JSON input schema, so the model cannot pass invalid payloads. Every response is a structured JSON object with a stable shape — no model-side parsing of natural-language responses.

The canonical invocation shape is the tools/call message. A call to search_venues looks like:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "search_venues",
    "arguments": { "query": "sunset Canggu", "limit": 5 }
  }
}

AGNT responds with a tools/call result whose content field carries the JSON payload. Claude Code, Cursor, Zed, and custom hosts built on the official MCP SDKs (TypeScript, Python) all use this same shape — the protocol is the same everywhere.

The three most common failure modes and their fixes:

• 401 Unauthorized on connect: your bearer token is missing, wrong, or revoked. Regenerate and re-export the env var.

• 403 Forbidden on a specific tool call: your key is valid but missing a scope the tool requires. Add memory.write or venues.read in the developer dashboard.

• SSE connection drops every 30 seconds: a proxy or load balancer is closing the idle connection. MCP hosts usually auto-reconnect, but you can force a keepalive by setting MCP_SSE_KEEPALIVE_MS in the host env.