MCP Protocol Reference
Complete reference for the Model Context Protocol JSON-RPC 2.0 interface.
Protocol Basics
The MCP protocol uses JSON-RPC 2.0 over HTTP. All requests are sent as POST requests to the server's MCP endpoint at /mcp/{slug}.
Every request must include the following fields:
| Field | Required | Description |
|---|---|---|
| jsonrpc | Yes | Must be "2.0" |
| method | Yes | The method name (e.g., "tools/list") |
| id | No | Request identifier. Omit for notifications (no response expected). |
| params | No | Method-specific parameters object |
Authentication
All MCP protocol requests require authentication via the X-API-Key header:
curl -X POST https://api.agentdojo.dev/mcp/my-server \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}'Supported Methods
initialize
Negotiate protocol version and discover server capabilities. This should be the first method called when establishing a session.
Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"clientInfo": {
"name": "my-agent",
"version": "1.0.0"
}
}
}Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2024-11-05",
"capabilities": {
"tools": {},
"resources": {},
"prompts": {}
},
"serverInfo": {
"name": "my-server",
"version": "1.0.0"
}
}
}notifications/initialized
Notify the server that initialization is complete. This is a notification (no id field), so the server responds with 202 Accepted and no body.
Request
{
"jsonrpc": "2.0",
"method": "notifications/initialized"
}tools/list
List all available tools on the server, including their names, descriptions, and input schemas.
Request
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list"
}Response
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"tools": [
{
"name": "send-notification",
"description": "Send a push notification",
"inputSchema": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": ["message"]
}
}
]
}
}tools/call
Call a specific tool with the given arguments.
Request
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "send-notification",
"arguments": {
"message": "Hello from MCP!"
}
}
}Response
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "Notification sent successfully"
}
],
"isError": false
}
}resources/list
List all available resources on the server.
Request
{
"jsonrpc": "2.0",
"id": 4,
"method": "resources/list"
}Response
{
"jsonrpc": "2.0",
"id": 4,
"result": {
"resources": [
{
"uri": "db://users",
"name": "User Directory",
"description": "Read-only user data",
"mimeType": "application/json"
}
]
}
}resources/read
Read the contents of a specific resource by URI.
Request
{
"jsonrpc": "2.0",
"id": 5,
"method": "resources/read",
"params": {
"uri": "db://users"
}
}Response
{
"jsonrpc": "2.0",
"id": 5,
"result": {
"contents": [
{
"uri": "db://users",
"mimeType": "application/json",
"text": "[{\"id\": 1, \"name\": \"Alice\"}]"
}
]
}
}prompts/list
List all available prompt templates on the server.
Request
{
"jsonrpc": "2.0",
"id": 6,
"method": "prompts/list"
}Response
{
"jsonrpc": "2.0",
"id": 6,
"result": {
"prompts": [
{
"name": "summarize-topic",
"description": "Summarize a topic in a style",
"arguments": [
{
"name": "topic",
"description": "The topic to summarize",
"required": true
},
{
"name": "style",
"description": "The writing style",
"required": true
}
]
}
]
}
}prompts/get
Get a prompt with variables substituted.
Request
{
"jsonrpc": "2.0",
"id": 7,
"method": "prompts/get",
"params": {
"name": "summarize-topic",
"arguments": {
"topic": "quantum computing",
"style": "casual"
}
}
}Response
{
"jsonrpc": "2.0",
"id": 7,
"result": {
"description": "Summarize a topic in a style",
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "Summarize the following quantum computing in casual style."
}
}
]
}
}ping
Health check to verify the server is responsive.
Request
{
"jsonrpc": "2.0",
"id": 8,
"method": "ping"
}Response
{
"jsonrpc": "2.0",
"id": 8,
"result": {}
}Full Session Example
Here is a complete session showing the typical flow: initialize the connection, discover available tools, and call a tool.
Initialize the Session
curl -X POST https://api.agentdojo.dev/mcp/my-server \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"clientInfo": { "name": "my-agent", "version": "1.0.0" }
}
}'Discover Available Tools
curl -X POST https://api.agentdojo.dev/mcp/my-server \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list"
}'Call a Tool
curl -X POST https://api.agentdojo.dev/mcp/my-server \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "send-notification",
"arguments": {
"message": "Deployment complete!"
}
}
}'Error Codes
When a request fails, the server returns a JSON-RPC error response with one of the following error codes:
| Code | Meaning | Description |
|---|---|---|
| -32600 | Invalid Request | The JSON-RPC request is malformed or missing required fields |
| -32601 | Method Not Found | The requested method does not exist on this server |
| -32602 | Invalid Params | The parameters provided are invalid or missing required values |
| -32603 | Internal Error | An unexpected error occurred on the server |
Example error response:
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32601,
"message": "Method not found: unknown/method"
}
}Rate Limiting
MCP protocol endpoints are rate-limited to 100 requests per minute per API key. When the limit is exceeded, the server returns a 429 Too Many Requests HTTP status code.
HTTP/1.1 429 Too Many Requests
Retry-After: 30
{
"error": "Rate limit exceeded. Try again in 30 seconds."
}