Message Types Reference¶

Complete specification of all MCP message types, request/response formats, and protocol semantics.

Message Categories¶

The Model Context Protocol defines messages in several categories:

🔄 Lifecycle Messages

Connection management, initialization, and shutdown procedures

initialize
initialized
shutdown
exit

🔧 Tool Messages

Tool discovery, execution, and management operations

tools/list
tools/call
tools/list-changed

📁 Resource Messages

Data access, subscription, and resource management

resources/list
resources/read
resources/subscribe
resources/unsubscribe
resources/updated

💬 Prompt Messages

Template management and prompt operations

prompts/list
prompts/get
prompts/list-changed

Base Message Format¶

All MCP messages follow JSON-RPC 2.0 specification:

Request Format¶

{
  "jsonrpc": "2.0",
  "id": "unique-request-identifier",
  "method": "namespace/operation",
  "params": {
    // Method-specific parameters
  }
}

Response Format¶

{
  "jsonrpc": "2.0", 
  "id": "unique-request-identifier",
  "result": {
    // Method-specific result
  }
}

Error Format¶

{
  "jsonrpc": "2.0",
  "id": "unique-request-identifier", 
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      // Additional error information
    }
  }
}

Notification Format¶

{
  "jsonrpc": "2.0",
  "method": "namespace/notification",
  "params": {
    // Notification parameters
  }
}

Lifecycle Messages¶

Initialize Request¶

Establishes connection and negotiates capabilities:

{
  "method": "initialize",
  "params": {
    "protocolVersion": "1.0.0",
    "capabilities": {
      "tools": true,
      "resources": {
        "subscribe": true,
        "listChanged": true
      },
      "prompts": {
        "listChanged": true
      },
      "experimental": {
        "sampling": true
      }
    },
    "clientInfo": {
      "name": "My AI Assistant",
      "version": "2.1.0"
    }
  }
}

Initialize Response¶

{
  "result": {
    "protocolVersion": "1.0.0",
    "capabilities": {
      "tools": {
        "listChanged": true
      },
      "resources": {
        "subscribe": true,
        "listChanged": true
      },
      "experimental": {}
    },
    "serverInfo": {
      "name": "Database MCP Server",
      "version": "1.5.2"
    }
  }
}

Initialized Notification¶

Confirms initialization complete:

{
  "method": "initialized",
  "params": {}
}

Shutdown Request¶

Initiates graceful shutdown:

{
  "method": "shutdown",
  "params": {}
}

Exit Notification¶

Forces immediate termination:

{
  "method": "exit",
  "params": {}
}

Tool Messages¶

Tools List Request¶

Discovers available tools:

{
  "method": "tools/list",
  "params": {
    "cursor": "optional-pagination-cursor"
  }
}

Tools List Response¶

{
  "result": {
    "tools": [
      {
        "name": "query_database",
        "description": "Execute SQL queries against the database",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "SQL query to execute",
              "maxLength": 10000
            },
            "database": {
              "type": "string",
              "enum": ["production", "staging", "analytics"],
              "description": "Target database"
            },
            "parameters": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Query parameters for prepared statements"
            }
          },
          "required": ["query"],
          "additionalProperties": false
        }
      }
    ],
    "nextCursor": "optional-next-page-cursor"
  }
}

Tool Call Request¶

Executes a specific tool:

{
  "method": "tools/call",
  "params": {
    "name": "query_database",
    "arguments": {
      "query": "SELECT * FROM users WHERE created_at > ?",
      "database": "production", 
      "parameters": ["2024-01-01"]
    }
  }
}

Tool Call Response¶

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Query executed successfully. Found 1,234 users created after 2024-01-01."
      },
      {
        "type": "resource",
        "resource": {
          "uri": "memory://query-results/abc123",
          "name": "Query Results",
          "mimeType": "application/json"
        }
      }
    ],
    "isError": false
  }
}

Tool List Changed Notification¶

Notifies when available tools change:

{
  "method": "tools/list-changed",
  "params": {}
}

Resource Messages¶

Resources List Request¶

Discovers available resources:

{
  "method": "resources/list",
  "params": {
    "cursor": "optional-pagination-cursor"
  }
}

Resources List Response¶

{
  "result": {
    "resources": [
      {
        "uri": "file:///var/log/app.log",
        "name": "Application Log",
        "description": "Real-time application log file",
        "mimeType": "text/plain"
      },
      {
        "uri": "database://users/table",
        "name": "Users Table",
        "description": "User account information",
        "mimeType": "application/json"
      }
    ],
    "nextCursor": "optional-next-page-cursor"
  }
}

Resource Read Request¶

Accesses resource content:

{
  "method": "resources/read",
  "params": {
    "uri": "file:///var/log/app.log"
  }
}

Resource Read Response¶

{
  "result": {
    "contents": [
      {
        "uri": "file:///var/log/app.log",
        "mimeType": "text/plain",
        "text": "2024-06-24 10:30:15 INFO Application started\n2024-06-24 10:30:16 INFO Database connection established"
      }
    ]
  }
}

Subscribes to resource changes:

{
  "method": "resources/subscribe",
  "params": {
    "uri": "file:///var/log/app.log"
  }
}

Resource Updated Notification¶

Notifies of resource changes:

{
  "method": "resources/updated", 
  "params": {
    "uri": "file:///var/log/app.log"
  }
}

Prompt Messages¶

Prompts List Request¶

Discovers available prompts:

{
  "method": "prompts/list",
  "params": {
    "cursor": "optional-pagination-cursor"
  }
}

Prompts List Response¶

{
  "result": {
    "prompts": [
      {
        "name": "analyze_data",
        "description": "Analyze dataset and provide insights",
        "arguments": [
          {
            "name": "dataset",
            "description": "Dataset to analyze",
            "required": true
          },
          {
            "name": "metrics",
            "description": "Specific metrics to focus on",
            "required": false
          }
        ]
      }
    ],
    "nextCursor": "optional-next-page-cursor"
  }
}

Prompt Get Request¶

Retrieves a specific prompt:

{
  "method": "prompts/get",
  "params": {
    "name": "analyze_data",
    "arguments": {
      "dataset": "sales_data_2024",
      "metrics": "revenue,growth,churn"
    }
  }
}

Prompt Get Response¶

{
  "result": {
    "description": "Analysis prompt for sales data",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "Please analyze the sales_data_2024 dataset focusing on revenue, growth, and churn metrics. Provide insights and recommendations."
        }
      }
    ]
  }
}

Error Codes¶

Standard JSON-RPC 2.0 error codes plus MCP-specific extensions:

Code	Name	Description
-32700	Parse Error	Invalid JSON received
-32600	Invalid Request	JSON-RPC format error
-32601	Method Not Found	Method doesn't exist
-32602	Invalid Params	Invalid parameters
-32603	Internal Error	Server internal error
-32000	Tool Not Found	Requested tool doesn't exist
-32001	Tool Execution Error	Tool failed to execute
-32002	Resource Not Found	Requested resource doesn't exist
-32003	Resource Access Denied	Insufficient permissions
-32004	Prompt Not Found	Requested prompt doesn't exist
-32005	Rate Limited	Too many requests

Content Types¶

MCP supports multiple content types in responses:

Text Content¶

{
  "type": "text",
  "text": "Plain text response"
}

Image Content¶

{
  "type": "image",
  "data": "base64-encoded-image-data",
  "mimeType": "image/png"
}

Resource Reference¶

{
  "type": "resource",
  "resource": {
    "uri": "file:///path/to/file.json",
    "name": "Data File",
    "mimeType": "application/json"
  }
}

Capability Negotiation¶

Capabilities are negotiated during initialization:

Client Capabilities¶

{
  "capabilities": {
    "tools": true,
    "resources": {
      "subscribe": true,
      "listChanged": true
    },
    "prompts": true,
    "sampling": true,
    "experimental": {
      "streaming": true
    }
  }
}

Server Capabilities¶

{
  "capabilities": {
    "tools": {
      "listChanged": true
    },
    "resources": {
      "subscribe": true,
      "listChanged": true
    },
    "prompts": {
      "listChanged": true
    },
    "experimental": {}
  }
}

Pagination¶

For large result sets, MCP supports cursor-based pagination:

Request with Cursor¶

{
  "method": "tools/list",
  "params": {
    "cursor": "eyJvZmZzZXQiOjEwMCwibGltaXQiOjUwfQ=="
  }
}

Response with Next Cursor¶

{
  "result": {
    "tools": [...],
    "nextCursor": "eyJvZmZzZXQiOjE1MCwibGltaXQiOjUwfQ=="
  }
}

Validation Requirements¶

All MCP implementations must:

JSON-RPC 2.0 Compliance - Strict adherence to specification
Schema Validation - Validate all parameters against schemas
Error Handling - Return appropriate error codes
Capability Respect - Only use negotiated capabilities
ID Matching - Match response IDs to request IDs
Timeout Handling - Implement reasonable timeouts

Ready to implement? Check our Conformance Tests →