MCP Basics

Recommended: Use the @mctx-ai/app framework to build your server. It handles all protocol details automatically so you can focus on your tools and data. The guide below covers the raw protocol for reference.

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.

Terminology note: This guide uses "MCP server" throughout — the technical term for the underlying protocol implementation. On mctx, these are called Apps. An App is an MCP server hosted and monetized on the mctx platform.

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"]
  }
}

Tools can also carry annotation hints -- optional boolean fields (readOnlyHint, destructiveHint, openWorldHint, idempotentHint) that tell AI clients how safe and consequential the tool is. Clients use these to decide whether to prompt the user for permission before calling the tool. See Tool annotations for details and examples.

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 Streamable HTTP as defined in MCP spec 2025-11-25:

• POST requests - Client sends JSON-RPC messages to the server
• Session IDs - Maintained via MCP-Session-Id header
• GET requests with Accept: text/event-stream - Opens an SSE channel for server-initiated messages (per MCP spec §6.2)

Both Streamable HTTP (POST) and SSE (GET) transports are supported. The SSE channel is handled at the mctx dispatch layer, which sends keepalive pings to maintain the connection. Client-initiated requests use POST; the GET+SSE channel is for server-pushed notifications.

What mctx Handles for You

When you build an App 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.

Next Steps

• Build Your First App — Create an App (MCP server) in 5 minutes, or start from the example template
• App Requirements - What mctx expects from your App
• Tools, Resources, and Prompts - Links to MCP SDK, examples, debugging tools

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