MCP Protocol Deep-Dive: How Tool Discovery Actually Works Under the Hood

MCP Protocol Deep-Dive: How Tool Discovery Actually Works Under the Hood Uncover the mechanics of Model Context Protocol (MCP) tool discovery—from JSON-RPC handshake to progressive injection. A technical walkthrough of capability negotiation and dynamic endpoint enumeration with real code examples and traffic flow analysis. The Handshake That Sets the Stage: JSON-RPC Initiation Tool discovery in MCP doesn't start with a simple “list tools” call. It begins with a structured JSON-RPC 2.0 handshake that negotiates protocol version, transport layer, and supported extensions. The client (e.g., an agent or IDE) sends an initialize request with its capabilities object, including fields like supportsToolDiscovery and maxToolCount . The server responds with its own capabilities, and only after this mutual agreement does the real enumeration begin. Real-world implementations—like those in the official MCP SDKs—use a ClientCapabilities struct that flags whether the client can handle dynamic tool lists, streaming updates, or batch discovery. For instance, a lightweight edge agent might set supportsToolDiscovery: false , forcing the server to pre-bundle tools into the initial handshake, while a full-featured IDE sends supportsToolDiscovery: true with a maxToolCount: 50 to throttle large tool registries. // Example initialize request (client → server) { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": { "supportsToolDiscovery": true, "maxToolCount": 50, "supportsStreaming": false } } } The server responds with its own capabilities—advertising tool discovery endpoints, supported JSON-RPC methods, and any custom extensions. This two-way handshake ensures both sides speak the same dialect before a single tool name is exchanged. Tool Enumeration: Beyond the “listTools” Metho Once handshaken, the client issues a tools/list call—but the real depth lies in pagination and chunking. A production MCP server with hundreds of too