mcpengine/infra/factory-tools/mcp-validator/specification/specification-2024-11-05.md

Model Context Protocol Specification - Test-Oriented Format

Protocol Revision: 2024-11-05

This document reorganizes the MCP specification into a format optimized for test creation. Each section contains testable requirements with MUST, SHOULD, and MAY conditions clearly highlighted.

Table of Contents

1. Base Protocol
   1. JSON-RPC Message Format
   2. Transport Mechanisms
   3. Lifecycle Management
2. Server Features
   1. Resources
   2. Prompts
   3. Tools
3. Client Features
   1. Roots
   2. Sampling
4. Utilities
   1. Ping
   2. Cancellation
   3. Progress
   4. Logging
   5. Completion
   6. Pagination

1. Base Protocol

1.1 JSON-RPC Message Format

1.1.1 Request Format

• MUST follow JSON-RPC 2.0 specification
• MUST include a string or integer ID (not null)
• MUST use unique IDs for each request within a session
• MUST include a method string
• MAY include parameters object

{
  "jsonrpc": "2.0",
  "id": "123",
  "method": "example_method",
  "params": {
    "exampleParam": "value"
  }
}

1.1.2 Response Format

• MUST include the same ID as the corresponding request
• MUST include either a result or an error (not both)
• MUST include an error code and message if returning an error

{
  "jsonrpc": "2.0",
  "id": "123",
  "result": {
    "exampleResult": "value"
  }
}

{
  "jsonrpc": "2.0",
  "id": "123",
  "error": {
    "code": -32602,
    "message": "Invalid params"
  }
}

1.1.3 Notification Format

• MUST NOT include an ID
• MUST include a method string
• MAY include parameters object

{
  "jsonrpc": "2.0",
  "method": "notifications/example",
  "params": {
    "exampleParam": "value"
  }
}

1.2 Transport Mechanisms

1.2.1 STDIO Transport

• Client MUST launch the server as a subprocess
• Server MUST read from stdin and write to stdout
• Messages MUST be delimited by newlines
• Messages MUST NOT contain embedded newlines
• Server MAY write UTF-8 strings to stderr for logging
• Server MUST NOT write anything to stdout that is not a valid MCP message
• Client MUST NOT write anything to stdin that is not a valid MCP message

1.2.2 HTTP with SSE Transport

• Server MUST provide two endpoints:
  • An SSE endpoint for clients to connect and receive messages
  • An HTTP POST endpoint for clients to send messages
• When client connects, server MUST send an endpoint event with URI for client messages
• All client messages MUST be sent as HTTP POST requests to this endpoint
• Server messages are sent as SSE message events
• Message content is encoded as JSON in the event data

1.3 Lifecycle Management

1.3.1 Initialization

• Client MUST send initialize request as first interaction
• Initialize request MUST include:
  • Protocol version supported
  • Client capabilities
  • Client implementation information
• Server MUST respond with:
  • Protocol version
  • Server capabilities
  • Server implementation information
• After successful initialization, client MUST send initialized notification
• Client SHOULD NOT send requests other than pings before server responds to initialize
• Server SHOULD NOT send requests other than pings and logging before initialized notification

// Initialize request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "sampling": {}
    },
    "clientInfo": {
      "name": "ExampleClient",
      "version": "1.0.0"
    }
  }
}

// Initialize response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "logging": {},
      "prompts": {
        "listChanged": true
      },
      "resources": {
        "subscribe": true,
        "listChanged": true
      },
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "ExampleServer",
      "version": "1.0.0"
    }
  }
}

// Initialized notification
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

1.3.2 Version Negotiation

• Client MUST send a protocol version it supports (preferably latest)
• If server supports requested version, it MUST respond with same version
• Otherwise, server MUST respond with another supported version
• If client doesn't support server's version, it SHOULD disconnect

1.3.3 Capability Negotiation

• Client and server MUST declare capabilities during initialization
• Both parties SHOULD respect negotiated capabilities
• Only capabilities declared by both parties should be used

1.3.4 Shutdown

• No specific shutdown messages defined
• For stdio: client SHOULD close input stream to server
• For HTTP: shutdown indicated by closing HTTP connections

2. Server Features

2.1 Resources

2.1.1 Capabilities

• Servers supporting resources MUST declare resources capability
• Optional features include:
  • subscribe: client can subscribe to resource changes
  • listChanged: server will notify when resource list changes

{
  "capabilities": {
    "resources": {
      "subscribe": true,
      "listChanged": true
    }
  }
}

2.1.2 Resources List

• Client sends resources/list request (supports pagination)
• Server response MUST include resources array
• Each resource MUST include uri and name
• Each resource MAY include description, mimeType

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resources": [
      {
        "uri": "file:///project/src/main.rs",
        "name": "main.rs",
        "description": "Primary application entry point",
        "mimeType": "text/x-rust"
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

2.1.3 Resource Content

• Client sends resources/read request with resource URI
• Server response MUST include contents array
• Each content item MUST include uri and either text or blob
• Each content item SHOULD include mimeType

// Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "file:///project/src/main.rs"
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "contents": [
      {
        "uri": "file:///project/src/main.rs",
        "mimeType": "text/x-rust",
        "text": "fn main() {\n    println!(\"Hello world!\");\n}"
      }
    ]
  }
}

2.1.4 Resource Templates

• Client sends resources/templates/list request
• Server response MUST include resourceTemplates array
• Each template MUST include uriTemplate
• Each template MAY include name, description, mimeType

// Request
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/templates/list"
}

// Response
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resourceTemplates": [
      {
        "uriTemplate": "file:///{path}",
        "name": "Project Files",
        "description": "Access files in the project directory",
        "mimeType": "application/octet-stream"
      }
    ]
  }
}

2.1.5 Resource Subscriptions

• Client sends resources/subscribe request with resource URI
• Server MUST send notifications/resources/updated when resource changes
• Server MUST support subscribe capability to use this feature

// Subscribe request
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/subscribe",
  "params": {
    "uri": "file:///project/src/main.rs"
  }
}

// Update notification
{
  "jsonrpc": "2.0",
  "method": "notifications/resources/updated",
  "params": {
    "uri": "file:///project/src/main.rs"
  }
}

2.1.6 List Changed Notification

• Server SHOULD send notifications/resources/list_changed when resource list changes
• Server MUST support listChanged capability to use this feature

{
  "jsonrpc": "2.0",
  "method": "notifications/resources/list_changed"
}

2.2 Prompts

2.2.1 Capabilities

• Servers supporting prompts MUST declare prompts capability
• Optional features include:
  • listChanged: server will notify when prompt list changes

{
  "capabilities": {
    "prompts": {
      "listChanged": true
    }
  }
}

2.2.2 Prompts List

• Client sends prompts/list request (supports pagination)
• Server response MUST include prompts array
• Each prompt MUST include name
• Each prompt MAY include description, arguments

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "prompts/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "prompts": [
      {
        "name": "code_review",
        "description": "Asks the LLM to analyze code quality",
        "arguments": [
          {
            "name": "code",
            "description": "The code to review",
            "required": true
          }
        ]
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

2.2.3 Get Prompt

• Client sends prompts/get request with prompt name and arguments
• Server response MUST include messages array
• Each message MUST include role and content
• Content MUST be one of: text, image, or resource

// Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "prompts/get",
  "params": {
    "name": "code_review",
    "arguments": {
      "code": "def hello():\n    print('world')"
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "description": "Code review prompt",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "Please review this Python code:\ndef hello():\n    print('world')"
        }
      }
    ]
  }
}

2.2.4 List Changed Notification

• Server SHOULD send notifications/prompts/list_changed when prompt list changes
• Server MUST support listChanged capability to use this feature

{
  "jsonrpc": "2.0",
  "method": "notifications/prompts/list_changed"
}

2.3 Tools

2.3.1 Capabilities

• Servers supporting tools MUST declare tools capability
• Optional features include:
  • listChanged: server will notify when tool list changes

{
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  }
}

2.3.2 Tools List

• Client sends tools/list request (supports pagination)
• Server response MUST include tools array
• Each tool MUST include name, description, inputSchema

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather information",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name or zip code"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

2.3.3 Tool Call

• Client sends tools/call request with tool name and arguments
• Server response MUST include content array and isError flag
• Each content item MUST be one of: text, image, or resource

// Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "New York"
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
      }
    ],
    "isError": false
  }
}

2.3.4 List Changed Notification

• Server SHOULD send notifications/tools/list_changed when tool list changes
• Server MUST support listChanged capability to use this feature

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

3. Client Features

3.1 Roots

3.1.1 Capabilities

• Clients supporting roots MUST declare roots capability
• Optional features include:
  • listChanged: client will notify when root list changes

{
  "capabilities": {
    "roots": {
      "listChanged": true
    }
  }
}

3.1.2 Roots List

• Server sends roots/list request
• Client response MUST include roots array
• Each root MUST include uri
• Each root MAY include name

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "roots/list"
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "roots": [
      {
        "uri": "file:///home/user/projects/myproject",
        "name": "My Project"
      }
    ]
  }
}

3.1.3 List Changed Notification

• Client MUST send notifications/roots/list_changed when root list changes
• Client MUST support listChanged capability to use this feature

{
  "jsonrpc": "2.0",
  "method": "notifications/roots/list_changed"
}

3.2 Sampling

3.2.1 Capabilities

• Clients supporting sampling MUST declare sampling capability

{
  "capabilities": {
    "sampling": {}
  }
}

3.2.2 Create Message

• Server sends sampling/createMessage request with messages and preferences
• Client response MUST include role, content, model, stopReason
• Content MUST be one of: text or image

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "What is the capital of France?"
        }
      }
    ],
    "modelPreferences": {
      "hints": [
        {
          "name": "claude-3-sonnet"
        }
      ],
      "intelligencePriority": 0.8,
      "speedPriority": 0.5
    },
    "systemPrompt": "You are a helpful assistant.",
    "maxTokens": 100
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "role": "assistant",
    "content": {
      "type": "text",
      "text": "The capital of France is Paris."
    },
    "model": "claude-3-sonnet-20240307",
    "stopReason": "endTurn"
  }
}

4. Utilities

4.1 Ping

4.1.1 Ping Request/Response

• Either party can send ping request with no parameters
• Receiver MUST respond promptly with empty response
• If no response is received within timeout, sender MAY terminate connection

// Request
{
  "jsonrpc": "2.0",
  "id": "123",
  "method": "ping"
}

// Response
{
  "jsonrpc": "2.0",
  "id": "123",
  "result": {}
}

4.2 Cancellation

4.2.1 Cancellation Notification

• Either party can send notifications/cancelled to cancel in-progress request
• Notification MUST include requestId of request to cancel
• Notification MAY include reason string
• Cancellation notifications MUST only reference previously issued requests
• Initialize request MUST NOT be cancelled by clients
• Receivers SHOULD stop processing cancelled request
• Receivers MAY ignore cancellation for unknown or completed requests

{
  "jsonrpc": "2.0",
  "method": "notifications/cancelled",
  "params": {
    "requestId": "123",
    "reason": "User requested cancellation"
  }
}

4.3 Progress

4.3.1 Progress Request

• To receive progress updates, request includes progressToken in _meta
• Progress tokens MUST be unique across active requests

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "some_method",
  "params": {
    "_meta": {
      "progressToken": "abc123"
    }
  }
}

4.3.2 Progress Notification

• Progress notifications MUST include progressToken and progress value
• Progress notifications MAY include total
• Progress value MUST increase with each notification
• Progress notifications MUST only reference active requests

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "abc123",
    "progress": 50,
    "total": 100
  }
}

4.4 Logging

4.4.1 Capabilities

• Servers supporting logging MUST declare logging capability

{
  "capabilities": {
    "logging": {}
  }
}

4.4.2 Set Log Level

• Client sends logging/setLevel request with minimum log level
• Log levels follow RFC 5424: debug, info, notice, warning, error, critical, alert, emergency

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "logging/setLevel",
  "params": {
    "level": "info"
  }
}

4.4.3 Log Message Notification

• Server sends notifications/message with log level, optional logger name, and data

{
  "jsonrpc": "2.0",
  "method": "notifications/message",
  "params": {
    "level": "error",
    "logger": "database",
    "data": {
      "error": "Connection failed",
      "details": {
        "host": "localhost",
        "port": 5432
      }
    }
  }
}

4.5 Completion

4.5.1 Completion Request

• Client sends completion/complete request with reference type and argument
• Reference types: ref/prompt, ref/resource
• Server response MUST include completion values
• Maximum 100 items per response

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "completion/complete",
  "params": {
    "ref": {
      "type": "ref/prompt",
      "name": "code_review"
    },
    "argument": {
      "name": "language",
      "value": "py"
    }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "completion": {
      "values": ["python", "pytorch", "pyside"],
      "total": 10,
      "hasMore": true
    }
  }
}

4.6 Pagination

4.6.1 Pagination Format

• Paginated responses MAY include nextCursor field if more results exist
• Client continues pagination by including cursor in subsequent requests
• Clients MUST treat cursors as opaque tokens
• Operations supporting pagination:
  • resources/list
  • resources/templates/list
  • prompts/list
  • tools/list

// Response with pagination
{
  "jsonrpc": "2.0",
  "id": "123",
  "result": {
    "resources": [...],
    "nextCursor": "eyJwYWdlIjogM30="
  }
}

// Request with cursor
{
  "jsonrpc": "2.0",
  "method": "resources/list",
  "params": {
    "cursor": "eyJwYWdlIjogMn0="
  }
}

Common Error Cases

Specific Error Codes

• Resource not found: -32002
• Invalid params: -32602
• Method not found: -32601
• Internal error: -32603

// Resource not found error
{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32002,
    "message": "Resource not found",
    "data": {
      "uri": "file:///nonexistent.txt"
    }
  }
}

// Invalid params error
{
  "jsonrpc": "2.0",
  "id": 6,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "details": "Missing required parameter: name"
    }
  }
}