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.
