API Reference

Welcome to the Model Context Protocol (MCP) API Reference. This section provides detailed documentation for all MCP methods, message formats, and implementation details.

Overview

The Model Context Protocol defines a standardized way for AI models to communicate with external systems. This API reference covers all the methods, parameters, and response formats you need to implement MCP in your applications.

Core Concepts

Message Structure

All MCP messages follow a consistent JSON-RPC 2.0 based structure:

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "method-name",
  "params": {
    // method-specific parameters
  }
}

Connection Lifecycle

1. Initialization: Establish connection and exchange capabilities
2. Authentication: Verify identity and permissions (if required)
3. Operation: Execute MCP methods and handle responses
4. Termination: Clean shutdown and resource cleanup

API Methods

Connection Methods

initialize

Initializes an MCP connection and exchanges capability information.

Parameters:

• protocolVersion (string): MCP protocol version
• capabilities (object): Client capabilities
• clientInfo (object): Information about the client

Response:

• protocolVersion (string): Server protocol version
• capabilities (object): Server capabilities
• serverInfo (object): Information about the server

ping

Tests connection health and measures round-trip time.

Parameters: None

Response:

• timestamp (number): Server timestamp

Resource Methods

resources/list

Lists available resources that can be accessed through MCP.

Parameters:

• cursor (string, optional): Pagination cursor

Response:

• resources (array): List of available resources
• nextCursor (string, optional): Next pagination cursor

resources/read

Reads content from a specific resource.

Parameters:

• uri (string): Resource URI to read

Response:

• contents (array): Resource contents

Tool Methods

tools/list

Lists available tools that can be called through MCP.

Parameters: None

Response:

• tools (array): List of available tools

tools/call

Calls a specific tool with provided arguments.

Parameters:

• name (string): Tool name to call
• arguments (object): Tool arguments

Response:

• content (array): Tool execution results
• isError (boolean, optional): Whether the call resulted in an error

Error Handling

MCP uses standard JSON-RPC 2.0 error format:

{
  "jsonrpc": "2.0",
  "id": "request-id",
  "error": {
    "code": -32000,
    "message": "Error description",
    "data": {
      // Additional error information
    }
  }
}

Error Codes

• -32700: Parse error
• -32600: Invalid request
• -32601: Method not found
• -32602: Invalid params
• -32603: Internal error
• -32000 to -32099: Server error range

Security Considerations

• Always validate input parameters
• Implement proper authentication when required
• Use secure transport (TLS) for sensitive data
• Apply rate limiting to prevent abuse
• Sanitize resource URIs and tool arguments

Examples

Basic Connection Example

// Initialize connection
const initRequest = {
  jsonrpc: "2.0",
  id: "init-1",
  method: "initialize",
  params: {
    protocolVersion: "2024-11-05",
    capabilities: {
      resources: { subscribe: true },
      tools: { listChanged: true }
    },
    clientInfo: {
      name: "MyMCPClient",
      version: "1.0.0"
    }
  }
};

Resource Access Example

// List resources
const listRequest = {
  jsonrpc: "2.0",
  id: "list-1",
  method: "resources/list",
  params: {}
};

// Read specific resource
const readRequest = {
  jsonrpc: "2.0",
  id: "read-1",
  method: "resources/read",
  params: {
    uri: "file:///example.txt"
  }
};

Tool Calling Example

// List available tools
const toolsRequest = {
  jsonrpc: "2.0",
  id: "tools-1",
  method: "tools/list",
  params: {}
};

// Call a tool
const callRequest = {
  jsonrpc: "2.0",
  id: "call-1",
  method: "tools/call",
  params: {
    name: "calculator",
    arguments: {
      operation: "add",
      a: 5,
      b: 3
    }
  }
};

Implementation Notes

• All timestamps should be in ISO 8601 format
• URIs should follow RFC 3986 specification
• Tool names should be unique within a server
• Resource URIs should be stable and consistent
• Implement proper timeout handling for long-running operations

Support

For questions about the API or implementation help:

• Check the Guide for implementation tutorials
• Review practical examples at Gosset
• Report issues or contribute improvements to the specification