Skip to content

MCP Protocol

Understanding the Model Context Protocol.

What is MCP?

The Model Context Protocol (MCP) is an open standard created by Anthropic that enables AI assistants to interact with external tools and data. It provides a standardized way for AI models to:

  • Call tools - Execute functions with parameters
  • Access resources - Read external data
  • Use prompts - Follow predefined templates

Protocol Architecture

┌─────────────────────┐      JSON-RPC       ┌─────────────────────┐
│                     │ ←────────────────→  │                     │
│    AI Assistant     │                     │    MCP Server       │
│  (Claude, Cursor)   │                     │  (GitHub to MCP)    │
│                     │                     │                     │
└─────────────────────┘                     └─────────────────────┘
        │                                           │
        │  1. List available tools                  │
        │  2. Call tool with params                 │
        │  3. Receive results                       │
        │                                           │

Communication

MCP uses JSON-RPC 2.0 over various transports:

Stdio Transport

Process-based communication via stdin/stdout:

AI Client → stdin → MCP Server
AI Client ← stdout ← MCP Server

Used by Claude Desktop, Cursor, and other desktop applications.

HTTP Transport

Network-based communication:

AI Client → HTTP POST → MCP Server
AI Client ← HTTP Response ← MCP Server

Used by web applications and networked deployments.

Core Messages

tools/list

List all available tools:

Request: 

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

Response: 

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "read_file",
        "description": "Read the contents of a file",
        "inputSchema": {
          "type": "object",
          "properties": {
            "path": { "type": "string" }
          },
          "required": ["path"]
        }
      }
    ]
  }
}

tools/call

Execute a tool:

Request: 

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "src/index.ts"
    }
  },
  "id": 2
}

Response: 

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "export function main() { ... }"
      }
    ]
  }
}

Tool Definition

Tools are defined with JSON Schema:

interface Tool {
  /** Unique tool name */
  name: string;

  /** Human-readable description */
  description?: string;

  /** JSON Schema for input parameters */
  inputSchema: {
    type: "object";
    properties?: Record<string, JSONSchema>;
    required?: string[];
  };
}

Example Tool

{
  "name": "search_code",
  "description": "Search for code patterns in the repository",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      },
      "path": {
        "type": "string",
        "description": "Limit search to this path"
      },
      "caseSensitive": {
        "type": "boolean",
        "description": "Case-sensitive search",
        "default": false
      }
    },
    "required": ["query"]
  }
}

Tool Results

Tool results can contain multiple content types:

Text Content

{
  "content": [
    {
      "type": "text",
      "text": "File contents here..."
    }
  ]
}

Image Content

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

Resource Content

{
  "content": [
    {
      "type": "resource",
      "resource": {
        "uri": "file:///path/to/file",
        "text": "Content..."
      }
    }
  ]
}

Server Capabilities

MCP servers declare their capabilities:

{
  "capabilities": {
    "tools": {},
    "resources": {},
    "prompts": {}
  }
}

Tools Capability

Indicates the server provides callable tools.

Resources Capability

Indicates the server provides readable resources (not used by GitHub to MCP).

Prompts Capability

Indicates the server provides prompt templates (not used by GitHub to MCP).

Client Integration

Claude Desktop

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/server.mjs"]
    }
  }
}

Programmatic Client

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const client = new Client({
  name: 'my-client',
  version: '1.0.0',
});

const transport = new StdioClientTransport({
  command: 'node',
  args: ['/path/to/server.mjs'],
});

await client.connect(transport);

// List tools
const tools = await client.listTools();

// Call a tool
const result = await client.callTool('read_file', {
  path: 'README.md'
});

Error Handling

MCP uses standard JSON-RPC error codes:

Code Message Description
-32700 Parse error Invalid JSON
-32600 Invalid Request Invalid JSON-RPC
-32601 Method not found Unknown method
-32602 Invalid params Invalid parameters
-32603 Internal error Server error

Tool-Specific Errors

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "details": "Required parameter 'path' is missing"
    }
  }
}

Security Considerations

Input Validation

Always validate tool inputs:

async function executeReadFile({ path }) {
  // Prevent directory traversal
  if (path.includes('..')) {
    throw new Error('Invalid path');
  }

  // Limit to allowed directories
  if (!path.startsWith('src/')) {
    throw new Error('Access denied');
  }

  return fs.readFile(path, 'utf-8');
}

Rate Limiting

Consider implementing rate limits for expensive operations.

Authentication

For sensitive tools, implement authentication checks.

Resources

See Also