MCP protocol reference

The JSON-RPC 2.0 messages an MCP client and server exchange. Method names and shapes follow the MCP specification; the servers behind the examples are generic.

Initialize

Every session starts with a handshake and capability exchange.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "my-client", "version": "1.0" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": { "listChanged": false },
      "resources": { "subscribe": false, "listChanged": false },
      "prompts": { "listChanged": false }
    },
    "serverInfo": { "name": "example-server", "version": "1.0.0" }
  }
}

Tool call

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "secrets_list",
    "arguments": { "vault_id": "550e8400-e29b-41d4-a716-446655440000" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{
      "type": "text",
      "text": "[{\"name\": \"DATABASE_URL\", \"category\": \"Environment\"}]"
    }]
  }
}

Tool results come back as content blocks; text is the common type. A tool that fails returns a tool-level error inside result — only transport and protocol problems use JSON-RPC error codes.

Error codes

Code	Meaning
-32700	Parse error
-32600	Invalid request
-32601	Method not found
-32602	Invalid params
-32603	Internal error