MCP Basics

What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how AI applications connect to external data sources and tools. Think of it like USB-C for AI - a universal connector that lets any AI application (Claude, Cursor, Codex, etc.) work with any MCP server.

Key concept: MCP servers are plugins for AI applications. Just as your browser uses extensions to add capabilities, AI applications use MCP servers to access specialized tools, data, and services.

Core Architecture

MCP uses a client-server architecture:

Communication: Clients and servers communicate using JSON-RPC 2.0 over HTTP. The server exposes capabilities through three core primitives:

The Three Primitives

Tools

Tools are executable functions that AI models can call to perform actions or retrieve information.

Control: Model-controlled - the AI decides when to call a tool based on the conversation.

Example use cases:

• Searching a database
• Fetching weather data
• Creating a GitHub issue
• Sending an email

Definition structure:

{
  "name": "search_weather",
  "description": "Get current weather for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or coordinates"
      }
    },
    "required": ["location"]
  }
}

When called, tools return content:

{
  "content": [
    { "type": "text", "text": "Weather in San Francisco: 68°F, partly cloudy" }
  ]
}

Resources

Resources are structured data or content that provides additional context to the AI model.

Control: Application-controlled - the client application decides which resources to attach to the conversation.

Example use cases:

• File contents from the current project
• Git commit history
• Documentation pages
• Database schemas

Resources have URIs:

resource://project/file/src/main.rs
resource://github/repo/commits
resource://docs/api/endpoints

Key difference from tools: Resources are passive data that the client includes as context. Tools are active functions the AI calls on demand.

Prompts

Prompts are pre-defined templates or instructions that guide AI interactions.

Control: User-controlled - the user explicitly invokes a prompt (via slash commands, menu options, etc.).

Example use cases:

• Code review template
• Bug report template
• Documentation generation prompt
• Commit message formatter

Prompts can include:

• Fixed instructions
• Dynamic placeholders filled from arguments
• Embedded resources

When invoked, prompts return messages:

{
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "Please review this code: [code snippet]"
      }
    }
  ]
}

How Communication Works

MCP uses JSON-RPC 2.0 for all communication between clients and servers.

Message Types

Session Lifecycle

1. Client initiates connection - Sends HTTP POST to server endpoint
2. Initialization handshake - Client and server exchange capabilities

   {
     "method": "initialize",
     "params": {
       "protocolVersion": "2025-11-25",
       "capabilities": {...},
       "clientInfo": {...}
     }
   }

3. Server responds with capabilities

   {
     "result": {
       "protocolVersion": "2025-11-25",
       "capabilities": {...},
       "serverInfo": {...},
       "instructions": "Optional guidance for the AI"
     }
   }

4. Session established - Client can now call methods
5. Ongoing communication - JSON-RPC requests/responses for tools, resources, prompts
6. Session termination - Client sends HTTP DELETE (optional)

Transport Layer

MCP servers on mctx use HTTP with JSON-RPC:

• POST requests - Client sends JSON-RPC messages to the server
• SSE (Server-Sent Events) - Optional for server-initiated messages
• Session IDs - Maintained via MCP-Session-Id header

What mctx Handles for You

When you build an MCP server for mctx, the platform handles many protocol details automatically:

Your server only needs to implement:

• tools/list - Return available tools
• tools/call - Execute tool logic
• resources/list - Return available resources (if applicable)
• resources/read - Return resource content (if applicable)
• prompts/list - Return available prompts (if applicable)
• prompts/get - Return prompt messages (if applicable)

MCP Protocol Version

mctx supports MCP Protocol Version 2025-11-25.

All responses from your server should include the header:

MCP-Protocol-Version: 2025-11-25

Next Steps

• Server Requirements - What mctx expects from your server
• Tools & Resources - Links to MCP SDK, examples, debugging tools

See something wrong? Report it or suggest an improvement — your feedback helps make these docs better.