Model Context Protocol (MCP) - Implementor's Guide
Core Concepts
MCP is a JSON-RPC 2.0 based protocol facilitating communication between model clients and servers. The protocol has three message types:

Requests - Require ID and method name, initiate operations
Responses - Must include same ID as request, return results or errors
Notifications - One-way, no ID, expect no reply

Protocol Architecture
MCP consists of five key components:

Base Protocol: Core message types and transport
Lifecycle Management: Connection setup, capability negotiation
Server Features: Resources, prompts, tools
Client Features: Sampling, root directory access
Utilities: Logging, ping, cancellation, progress tracking

Only base protocol and lifecycle management are mandatory; other components are optional based on negotiated capabilities.
Transport Options
MCP supports two standard transports:

stdio: Client launches server as subprocess; JSON-RPC via stdin/stdout with newline delimiters
HTTP with SSE: Server provides SSE endpoint for messages to client and HTTP POST endpoint for messages from client

Custom transports are permitted if they preserve the JSON-RPC message format and lifecycle.
Connection Lifecycle
1. Initialization

Client sends initialize request with:

Protocol version (e.g., "2024-11-05")
Client capabilities
Client info (name, version)


Server responds with:

Protocol version it supports
Server capabilities
Server info


Client sends initialized notification:
jsonCopy{"jsonrpc": "2.0", "method": "notifications/initialized"}


2. Operation
During this phase, normal protocol operations occur based on negotiated capabilities.
3. Shutdown

No specific shutdown messages
For stdio: Client closes input stream, server exits
For HTTP: Connection is closed

Message Formats
Request
jsonCopy{
  "jsonrpc": "2.0",
  "id": "unique_id",
  "method": "method_name",
  "params": {
    "key": "value"
  }
}
Success Response
jsonCopy{
  "jsonrpc": "2.0",
  "id": "unique_id",
  "result": {
    "key": "value"
  }
}
Error Response
jsonCopy{
  "jsonrpc": "2.0",
  "id": "unique_id",
  "error": {
    "code": -32000,
    "message": "Error description",
    "data": {"additional": "info"}
  }
}
Notification
jsonCopy{
  "jsonrpc": "2.0",
  "method": "notification_name",
  "params": {
    "key": "value"
  }
}
Capability Negotiation
Capabilities are exchanged during initialization to determine available features:
Client Capabilities

roots: Client can provide filesystem access
sampling: Client can handle LLM sampling requests

Server Capabilities

prompts: Server offers prompt templates
resources: Server provides readable resources
tools: Server exposes callable tools
logging: Server emits structured logs

Each capability may have sub-capabilities:

listChanged: Notifies when lists change
subscribe: Allows subscribing to individual resource changes

Utility Features
Ping
Either party can send a ping to verify connection:
jsonCopy{"jsonrpc": "2.0", "id": "ping_id", "method": "ping"}
Expected response:
jsonCopy{"jsonrpc": "2.0", "id": "ping_id", "result": {}}
Cancellation
To cancel an in-progress request:
jsonCopy{
  "jsonrpc": "2.0",
  "method": "notifications/cancelled",
  "params": {
    "requestId": "request_id_to_cancel",
    "reason": "Optional reason"
  }
}
Progress Tracking

Include progressToken in request:

jsonCopy{
  "jsonrpc": "2.0",
  "id": "request_id",
  "method": "method_name",
  "params": {
    "_meta": {
      "progressToken": "progress_token"
    }
  }
}

Send progress notifications:

jsonCopy{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "progress_token",
    "progress": 50,
    "total": 100
  }
}
Implementation Checklist
Required

 JSON-RPC 2.0 message formatting
 Initialize request/response handling
 Initialized notification processing
 Protocol version negotiation
 Capability exchange
 Transport implementation (stdio or HTTP/SSE)

Optional (Based on Capabilities)

 Resource handling
 Prompt template processing
 Tool execution
 Logging implementation
 Sampling support
 Root directory listing
 Ping mechanism
 Cancellation handling
 Progress tracking

Best Practices

Error Handling

Implement timeouts for all requests
Handle connection failures gracefully
Use appropriate error codes


Message Processing

Validate all incoming messages
Ensure unique request IDs
Respect negotiated capabilities


Performance

Rate-limit notifications
Implement efficient message serialization
Use appropriate buffer sizes for transport


Security

Consider adding custom authentication
Validate all inputs
Limit resource access appropriately



Version Compatibility

Current protocol version: 2024-11-05
Clients should support the latest version they know
Servers should negotiate down to a compatible version
Disconnect if no compatible version exists

This guide covers the essential elements needed for a functional MCP implementation. For complete details, refer to the full specification