MCP Protocol (Model Context Protocol Spec)

MCP Spec in a Nutshell:

The Model Context Protocol (MCP) specification is a formal document that describes exactly how AI applications (clients) talk to external tools (servers). It defines message formats, transport layers, capability negotiation, and lifecycle management. Think of it as the rulebook that ensures any MCP client can work with any MCP server, no matter who built them.

It is like HTTP specification - HTTP defines how browsers talk to web servers. MCP defines how AI apps talk to tool servers. Without this standard, every AI app would invent its own way to connect to tools, creating chaos.

Real-World Analogy - Railway Gauge Standard:

India had a problem - different railways used different track widths (broad gauge, meter gauge, narrow gauge). Trains could not travel across networks. The solution? Standardize to one gauge. Now trains run smoothly across the entire country.

MCP is that standard gauge for AI tools. Before MCP, every AI app had its own way of connecting to tools. MCP says: "Everyone follow these exact rules, and everything will just work together."

Key Components of the MCP Spec:

• Protocol Layer: JSON-RPC 2.0 message format for requests, responses, and notifications
• Transport Layer: How messages travel - stdio (local) or HTTP+SSE (remote)
• Capability Negotiation: Client and server agree on what features they support during initialization
• Primitive Types: Tools, Resources, and Prompts - the three things servers can expose
• Lifecycle Management: How connections start, stay alive, and end gracefully

Why JSON-RPC 2.0?

MCP is built on JSON-RPC 2.0 - a lightweight remote procedure call protocol. Why? Because it is simple, well-established, and language-agnostic. Any programming language that can read JSON can implement MCP.

JSON-RPC defines three types of messages:

• Request: "Hey server, please do this thing" (has an ID, expects a response)
• Response: "Here is the result" (matches the request ID)
• Notification: "FYI, this happened" (no ID, no response expected)

MCP Message Flow Example:

// Client sends a request to call a tool
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_users",
    "arguments": { "query": "John" }
  }
}

// Server responds with the result
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "Found 3 users: John Doe, John Smith, Johnny B"
    }]
  }
}

Core Protocol Methods:

Two Official Transports:

The MCP spec defines two ways for messages to travel. Think of transport as the road and JSON-RPC as the vehicles on that road. Same vehicles, different roads.

1. Stdio Transport (Local):

The client launches the MCP server as a child process. Messages flow through standard input/output pipes (stdin/stdout). This is like two people in the same room talking face-to-face.

• Best for: Local development tools, desktop apps
• Pros: Simple, fast, no network setup, secure (runs on same machine)
• Cons: Cannot be shared across machines, client must manage server process
• Used by: Claude Desktop, Claude Code, Cursor IDE

2. HTTP + SSE Transport (Remote / Streamable):

The server runs as an HTTP service. Client sends requests via HTTP POST. Server streams responses back using Server-Sent Events (SSE). This is like talking on a phone call - works across distances.

• Best for: Cloud-hosted servers, shared team tools, SaaS integrations
• Pros: Remote access, scalable, can be behind auth/load balancers
• Cons: More setup, needs network, latency
• The newer "Streamable HTTP" transport supersedes the older SSE-only transport

Transport Comparison:

The Initialize Handshake:

When an MCP client first connects to a server, they perform an initialization handshake. This is like two diplomats meeting - they exchange credentials and agree on what topics (capabilities) they can discuss.

// Step 1: Client sends initialize request
Client: "Hi! I am Claude Desktop v1.2.
         I support tools, resources, and prompts.
         Protocol version: 2025-03-26"

// Step 2: Server responds with its capabilities
Server: "Hello! I am GitHub MCP Server v3.0.
         I offer: tools (yes), resources (yes), prompts (no).
         Protocol version: 2025-03-26 - compatible!"

// Step 3: Client confirms with initialized notification
Client: "Great, we are connected!"

Capabilities Explained:

Not every server supports everything. Capability negotiation ensures the client only tries to use features the server actually offers:

• tools: Can the server execute tools? Most servers say yes.
• resources: Does the server expose readable data? Optional.
• prompts: Does the server provide prompt templates? Optional.
• logging: Can the server send log messages? Useful for debugging.
• sampling: Can the server request the LLM to generate text? Advanced feature.

Connection Lifecycle:

1. INITIALIZE  -> Client sends version + capabilities
2. INITIALIZED -> Server confirms, connection active
3. OPERATING   -> Normal tool/resource operations
4. SHUTDOWN    -> Graceful disconnect (or crash recovery)

During OPERATING:
- Client can call tools/list, tools/call, resources/read, etc.
- Server can send notifications (progress updates, log messages)
- Either side can send cancellation requests
- Ping/pong for health checks

Pitfall 1: Ignoring Protocol Version Mismatches

The client and server MUST agree on a protocol version during initialization. If versions are incompatible, the connection should fail gracefully - not silently proceed with broken behavior. Always check the version field in the initialize response.

Pitfall 2: Not Handling Notifications vs Requests

Requests have an id field and expect a response. Notifications do NOT have an id and must NOT be responded to. Mixing these up causes protocol errors. A common mistake: treating a progress notification like a request and trying to respond to it.

Pitfall 3: Blocking the Transport

In stdio transport, if the server writes to stderr excessively or blocks on stdout, the entire communication channel freezes. Keep your server output clean. Use logging capabilities instead of printing debug info to stdout.

Pitfall 4: Missing Error Handling

The spec defines specific error codes (like -32600 for invalid request, -32601 for method not found). Return proper JSON-RPC error objects instead of crashing. The client needs structured errors to recover gracefully.

Pitfall 5: Large Payloads Without Pagination

If a resources/list returns 10,000 items, you will choke the transport. The spec supports cursor-based pagination for list operations. Always implement pagination for potentially large result sets.

Q: What is MCP and why was it created?

Q: Explain the MCP initialization handshake.

Q: What are the two transport layers in MCP and when would you use each?

Q: How does MCP differ from OpenAI function calling?

Q: What role does capability negotiation play in MCP?