python-sdk Documentation

1. Project Overview & Quickstart (modelcontextprotocol/python-sdk) Copy Chapter

File: README.md Copy Chapter

MCP Python SDK

[!NOTE]
This is v2 of the MCP Python SDK, the current stable release line. It is a major rework of the SDK, both to support the 2026-07-28 MCP specification (and every earlier revision) and to fix long-standing architectural issues. Coming from v1? See What's new in v2 for the tour of what changed and the migration guide for every breaking change.

Not ready to migrate? v1.x lives on the v1.x branch, continues to receive critical bug fixes and security patches, and is documented at https://py.sdk.modelcontextprotocol.io/v1/. Since pip install mcp now installs 2.x, keep a <2 upper bound on your requirement (for example mcp>=1.28,<2) until you've migrated.

Something rough, confusing, or broken? Open an issue or find us in #python-sdk-dev on the MCP Contributors Discord.

Documentation Copy Chapter

The documentation lives at https://py.sdk.modelcontextprotocol.io/.

It has a Get started guide, What's new in v2, the API reference, and the migration guide.

What is MCP? Copy Chapter

The Model Context Protocol lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but designed for LLM interactions. With this SDK you can:

• Build MCP servers that expose tools, resources, and prompts to any MCP host
• Build MCP clients that connect to any MCP server
• Speak every standard transport: stdio, Streamable HTTP, and SSE

Requirements Copy Chapter

Python 3.10+.

Installation Copy Chapter

uv add "mcp[cli]"      # or: pip install "mcp[cli]"

The cli extra adds the mcp command-line tool (mcp dev, mcp run, mcp install) on top of the SDK; install plain mcp if you don't need it. For one-off commands, uv run --with "mcp[cli]" mcp ... works without a project.

A server in 15 lines Copy Chapter

Create a server.py:

from mcp.server import MCPServer

mcp = MCPServer("Demo")


@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b


@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

Full example: docs_src/index/tutorial001.py

That's a complete MCP server: one tool, one templated resource. Open it in the MCP Inspector:

uv run mcp dev server.py

Call add with a=1, b=2 and you get 3 back.

Notice what you did not write: no JSON Schema (a: int, b: int is the schema), no request parsing, no validation code, no protocol handling. Two type-hinted Python functions and a docstring.

Get started takes it from here.

A client in 10 lines Copy Chapter

The same package is a full MCP client. Serve server.py over HTTP:

uv run mcp run server.py --transport streamable-http

then point a Client at it:

import asyncio

from mcp import Client


async def main() -> None:
    async with Client("http://localhost:8000/mcp") as client:
        result = await client.call_tool("add", {"a": 1, "b": 2})
        print(result.structured_content)  # {'result': 3}


asyncio.run(main())

A URL means Streamable HTTP, the transport you deploy. Client can also launch a local server as a stdio subprocess or take any custom transport; Clients has the rest.

Contributing Copy Chapter

We are passionate about supporting contributors of all levels of experience and would love to see you get involved in the project. See the contributing guide to get started.

License Copy Chapter

This project is licensed under the MIT License. See the LICENSE file for details.

File: docs/index.md Copy Chapter

MCP Python SDK

!!! info "This documents v2, the current stable release line"
New to v2, or coming from v1? What's new in v2 is the five-minute tour of what changed, and the Migration Guide covers every breaking change.
Still on v1.x? Its documentation lives at the v1.x docs.
Something rough or confusing? Tell us.

The Model Context Protocol (MCP) lets applications provide context to LLMs in a standardized way, separating the concern of providing context from the LLM interaction itself.

This is the official Python SDK for it. With it you can:

• Build MCP servers that expose tools, resources, and prompts to any MCP host.
• Build MCP clients that connect to any MCP server.
• Speak every standard transport: stdio, Streamable HTTP, and SSE.

Requirements Copy Chapter

Python 3.10+.

Installation Copy Chapter

=== "uv"

```bash
uv add "mcp[cli]"
```

=== "pip"

```bash
pip install "mcp[cli]"
```

The [cli] extra gives you the mcp command; you'll want it for development.
See Installation for what each dependency is for.

Example Copy Chapter

Create it Copy Section

Create a file server.py:

--8<-- "docs_src/index/tutorial001.py"

That's a complete MCP server.

It exposes one tool, add, and one templated resource, greeting://{name}.

Run it Copy Section

uv run mcp dev server.py

This starts your server and opens the MCP Inspector, an interactive UI for poking at it. Open the URL it prints.

!!! note
The Inspector is a Node.js app, so mcp dev needs npx on your PATH.

Try it Copy Section

In the Inspector, go to Tools and call add with a=1, b=2.

You get 3 back. ✨

The Inspector built that form (a required integer field for a, another for b) from your type hints. So will Claude, and every other MCP host.

Now go to Resources and read greeting://World:

Hello, World!

Recap Copy Section

Look again at what you did not write:

• No JSON Schema. a: int, b: int is the schema.
• No request parsing, no serialization, no validation code.
• No protocol handling at all.

You wrote two Python functions with type hints and a docstring. The SDK does the rest.

Where to go next Copy Chapter

• Get started takes you from install to a working, tested server.
• Building an application that uses MCP servers? Start with Clients.
• Already have a FastAPI or Starlette app? Add to an existing app mounts an MCP server inside it.
• Hunting an exact error message? Troubleshooting is keyed by the verbatim text.
• Wondering what changed in v2? What's new in v2 is the five-minute tour.
• Migrating from v1? Start with the Migration Guide.
• Hunting for an exact signature? The API Reference is generated from the source.
• Reading with an LLM? This documentation is also published in the llms.txt format:
  llms.txt is an index of the pages, and
  llms-full.txt contains every page in a single file.

File: examples/clients/simple-chatbot/README.MD Copy Chapter

MCP Simple Chatbot

This example demonstrates how to integrate the Model Context Protocol (MCP) into a simple CLI chatbot. The implementation showcases MCP's flexibility by supporting multiple tools through MCP servers and is compatible with any LLM provider that follows OpenAI API standards.

Requirements Copy Chapter

• Python 3.10
• python-dotenv
• requests
• mcp
• uvicorn

Installation Copy Chapter

1. Install the dependencies:

   bash Copy

   pip install -r requirements.txt

2. Set up environment variables:

   Create a .env file in the root directory and add your API key:

   plaintext Copy

   LLM_API_KEY=your_api_key_here

   Note: The current implementation is configured to use the Groq API endpoint (https://api.groq.com/openai/v1/chat/completions) with the llama-3.2-90b-vision-preview model. If you plan to use a different LLM provider, you'll need to modify the LLMClient class in main.py to use the appropriate endpoint URL and model parameters.

3. Configure servers:

   The servers_config.json follows the same structure as Claude Desktop, allowing for easy integration of multiple servers.
   Here's an example:

   json Copy

   {
     "mcpServers": {
       "sqlite": {
         "command": "uvx",
         "args": ["mcp-server-sqlite", "--db-path", "./test.db"]
       },
       "puppeteer": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
       }
     }
   }

   Environment variables are supported as well. Pass them as you would with the Claude Desktop App.

   Example:

   json Copy

   {
     "mcpServers": {
       "server_name": {
         "command": "uvx",
         "args": ["mcp-server-name", "--additional-args"],
         "env": {
           "API_KEY": "your_api_key_here"
         }
       }
     }
   }

Usage Copy Chapter

1. Run the client:

   bash Copy

   python main.py

2. Interact with the assistant:

   The assistant will automatically detect available tools and can respond to queries based on the tools provided by the configured servers.

3. Exit the session:

   Type quit or exit to end the session.

Architecture Copy Chapter

• Tool Discovery: Tools are automatically discovered from configured servers.
• System Prompt: Tools are dynamically included in the system prompt, allowing the LLM to understand available capabilities.
• Server Integration: Supports any MCP-compatible server, tested with various server implementations including Uvicorn and Node.js.

Class Structure Copy Section

• Configuration: Manages environment variables and server configurations
• Server: Handles MCP server initialization, tool discovery, and execution
• Tool: Represents individual tools with their properties and formatting
• LLMClient: Manages communication with the LLM provider
• ChatSession: Orchestrates the interaction between user, LLM, and tools

Logic Flow Copy Section

1. Tool Integration:

   • Tools are dynamically discovered from MCP servers
   • Tool descriptions are automatically included in system prompt
   • Tool execution is handled through standardized MCP protocol

2. Runtime Flow:

   • User input is received
   • Input is sent to LLM with context of available tools
   • LLM response is parsed:
     • If it's a tool call → execute tool and return result
     • If it's a direct response → return to user
   • Tool results are sent back to LLM for interpretation
   • Final response is presented to user

File: examples/clients/simple-auth-client/README.md Copy Chapter

Simple Auth Client Example

A demonstration of how to use the MCP Python SDK with OAuth authentication over streamable HTTP or SSE transport.

Features Copy Chapter

• OAuth 2.0 authentication with PKCE
• Support for both StreamableHTTP and SSE transports
• Interactive command-line interface

Installation Copy Chapter

cd examples/clients/simple-auth-client
uv sync --reinstall

Usage Copy Chapter

1. Start an MCP server with OAuth support Copy Section

The simple-auth server example provides three server configurations. See examples/servers/simple-auth/README.md for full details.

Option A: New Architecture (Recommended)

Separate Authorization Server and Resource Server:

# Terminal 1: Start Authorization Server on port 9000
cd examples/servers/simple-auth
uv run mcp-simple-auth-as --port=9000

# Terminal 2: Start Resource Server on port 8001
cd examples/servers/simple-auth
uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000 --transport=streamable-http

Option B: Legacy Server (Backwards Compatibility)

# Single server that acts as both AS and RS (port 8000)
cd examples/servers/simple-auth
uv run mcp-simple-auth-legacy --port=8000 --transport=streamable-http

2. Run the client Copy Section

# Connect to Resource Server (new architecture, default port 8001)
MCP_SERVER_PORT=8001 uv run mcp-simple-auth-client

# Connect to Legacy Server (port 8000)
uv run mcp-simple-auth-client

# Use SSE transport
MCP_SERVER_PORT=8001 MCP_TRANSPORT_TYPE=sse uv run mcp-simple-auth-client

3. Complete OAuth flow Copy Section

The client will open your browser for authentication. After completing OAuth, you can use commands:

• list - List available tools
• call <tool_name> [args] - Call a tool with optional JSON arguments
• quit - Exit

Example Copy Chapter

🚀 Simple MCP Auth Client
Connecting to: http://localhost:8001/mcp
Transport type: streamable-http

🔗 Attempting to connect to http://localhost:8001/mcp...
📡 Opening StreamableHTTP transport connection with auth...
Opening browser for authorization: http://localhost:9000/authorize?...

✅ Connected to MCP server at http://localhost:8001/mcp

mcp> list
📋 Available tools:
1. get_time
mcp> call get_time
🔧 Tool 'get_time' result:
{"current_time": "2024-01-15T10:30:00", "timezone": "UTC", ...}

mcp> quit

Configuration Copy Chapter

File: examples/servers/simple-tool/README.md Copy Chapter

A simple MCP server that exposes a website fetching tool.

Usage Copy Chapter

Start the server using either stdio (default) or Streamable HTTP transport:

# Using stdio transport (default)
uv run mcp-simple-tool

# Using Streamable HTTP transport on custom port
uv run mcp-simple-tool --transport streamable-http --port 8000

The server exposes a tool named "fetch" that accepts one required argument:

• url: The URL of the website to fetch

Example Copy Chapter

Using the MCP client, you can use the tool like this using the STDIO transport:

import asyncio
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client


async def main():
    async with stdio_client(
        StdioServerParameters(command="uv", args=["run", "mcp-simple-tool"])
    ) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools = await session.list_tools()
            print(tools)

            # Call the fetch tool
            result = await session.call_tool("fetch", {"url": "https://example.com"})
            print(result)


asyncio.run(main())

File: examples/servers/simple-streamablehttp-stateless/README.md Copy Chapter

MCP Simple StreamableHttp Stateless Server Example

A stateless MCP server example demonstrating the StreamableHttp transport without maintaining session state. This example is ideal for understanding how to deploy MCP servers in multi-node environments where requests can be routed to any instance.

Features Copy Chapter

• Uses the StreamableHTTP transport in stateless mode (mcp_session_id=None)
• Each request creates a new ephemeral connection
• No session state maintained between requests
• Suitable for deployment in multi-node environments

Usage Copy Chapter

Start the server:

# Using default port 3000
uv run mcp-simple-streamablehttp-stateless

# Using custom port
uv run mcp-simple-streamablehttp-stateless --port 3000

# Custom logging level
uv run mcp-simple-streamablehttp-stateless --log-level DEBUG

# Enable JSON responses instead of SSE streams
uv run mcp-simple-streamablehttp-stateless --json-response

The server exposes a tool named "start-notification-stream" that accepts three arguments:

• interval: Time between notifications in seconds (e.g., 1.0)
• count: Number of notifications to send (e.g., 5)
• caller: Identifier string for the caller

Client Copy Chapter

You can connect to this server using an HTTP client. For now, only the TypeScript SDK has streamable HTTP client examples, or you can use Inspector for testing.

File: examples/servers/simple-streamablehttp/README.md Copy Chapter

MCP Simple StreamableHttp Server Example

A simple MCP server example demonstrating the StreamableHttp transport, which enables HTTP-based communication with MCP servers using streaming.

Features Copy Chapter

• Uses the StreamableHTTP transport for server-client communication
• Supports REST API operations (POST, GET, DELETE) for /mcp endpoint
• Ability to send multiple notifications over time to the client
• Resumability support via InMemoryEventStore

Usage Copy Chapter

Start the server on the default or custom port:

# Using custom port
uv run mcp-simple-streamablehttp --port 3000

# Custom logging level
uv run mcp-simple-streamablehttp --log-level DEBUG

# Enable JSON responses instead of SSE streams
uv run mcp-simple-streamablehttp --json-response

The server exposes a tool named "start-notification-stream" that accepts three arguments:

• interval: Time between notifications in seconds (e.g., 1.0)
• count: Number of notifications to send (e.g., 5)
• caller: Identifier string for the caller

Resumability Support Copy Chapter

This server includes resumability support through the InMemoryEventStore. This enables clients to:

• Reconnect to the server after a disconnection
• Resume event streaming from where they left off using the Last-Event-ID header

The server will:

• Generate unique event IDs for each SSE message
• Store events in memory for later replay
• Replay missed events when a client reconnects with a Last-Event-ID header

Note: The InMemoryEventStore is designed for demonstration purposes only. For production use, consider implementing a persistent storage solution.

Client Copy Chapter

You can connect to this server using an HTTP client, for now only Typescript SDK has streamable HTTP client examples or you can use Inspector

File: examples/servers/simple-resource/README.md Copy Chapter

MCP Simple Resource

A simple MCP server that exposes sample text files as resources.

Usage Copy Chapter

Start the server using either stdio (default) or Streamable HTTP transport:

# Using stdio transport (default)
uv run mcp-simple-resource

# Using Streamable HTTP transport on custom port
uv run mcp-simple-resource --transport streamable-http --port 8000

The server exposes some basic text file resources that can be read by clients.

Example Copy Chapter

Using the MCP client, you can retrieve resources like this using the STDIO transport:

import asyncio
from pydantic import AnyUrl
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client


async def main():
    async with stdio_client(
        StdioServerParameters(command="uv", args=["run", "mcp-simple-resource"])
    ) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available resources
            resources = await session.list_resources()
            print(resources)

            # Get a specific resource
            resource = await session.read_resource(AnyUrl("file:///greeting.txt"))
            print(resource)


asyncio.run(main())

File: examples/servers/simple-prompt/README.md Copy Chapter

MCP Simple Prompt

A simple MCP server that exposes a customizable prompt template with optional context and topic parameters.

Usage Copy Chapter

Start the server using either stdio (default) or Streamable HTTP transport:

# Using stdio transport (default)
uv run mcp-simple-prompt

# Using Streamable HTTP transport on custom port
uv run mcp-simple-prompt --transport streamable-http --port 8000

The server exposes a prompt named "simple" that accepts two optional arguments:

• context: Additional context to consider
• topic: Specific topic to focus on

Example Copy Chapter

Using the MCP client, you can retrieve the prompt like this using the STDIO transport:

import asyncio
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client


async def main():
    async with stdio_client(
        StdioServerParameters(command="uv", args=["run", "mcp-simple-prompt"])
    ) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available prompts
            prompts = await session.list_prompts()
            print(prompts)

            # Get the prompt with arguments
            prompt = await session.get_prompt(
                "simple",
                {
                    "context": "User is a software developer",
                    "topic": "Python async programming",
                },
            )
            print(prompt)


asyncio.run(main())

2. Official Technical Reference & Guides (modelcontextprotocol/docs) Copy Chapter

File: README.md Copy Chapter

Model Context Protocol documentation

This documentation has moved to modelcontextprotocol/modelcontextprotocol.

Please file issues and pull requests for documentation changes there.

File: docs/tools/debugging.mdx Copy Chapter

title: Debugging Copy Chapter

Effective debugging is essential when developing MCP servers or integrating them with applications. This guide covers the debugging tools and approaches available in the MCP ecosystem.

This guide is for macOS. Guides for other platforms are coming soon.

Debugging tools overview Copy Chapter

MCP provides several tools for debugging at different levels:

1. MCP Inspector

   • Interactive debugging interface
   • Direct server testing
   • See the Inspector guide for details

2. Claude Desktop Developer Tools

   • Integration testing
   • Log collection
   • Chrome DevTools integration

3. Server Logging

   • Custom logging implementations
   • Error tracking
   • Performance monitoring

Debugging in Claude Desktop Copy Chapter

Checking server status Copy Section

The Claude.app interface provides basic server status information:

1. Click the icon to view:

   • Connected servers
   • Available prompts and resources

2. Click the icon to view:

   • Tools made available to the model

Viewing logs Copy Section

Review detailed MCP logs from Claude Desktop:

# Follow logs in real-time
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

The logs capture:

• Server connection events
• Configuration issues
• Runtime errors
• Message exchanges

Using Chrome DevTools Copy Section

Access Chrome's developer tools inside Claude Desktop to investigate client-side errors:

1. Create a developer_settings.json file with allowDevTools set to true:

echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json

2. Open DevTools: Command-Option-Shift-i

Note: You'll see two DevTools windows:

• Main content window
• App title bar window

Use the Console panel to inspect client-side errors.

Use the Network panel to inspect:

• Message payloads
• Connection timing

Common issues Copy Chapter

Working directory Copy Section

When using MCP servers with Claude Desktop:

• The working directory for servers launched via claude_desktop_config.json may be undefined (like / on macOS) since Claude Desktop could be started from anywhere
• Always use absolute paths in your configuration and .env files to ensure reliable operation
• For testing servers directly via command line, the working directory will be where you run the command

For example in claude_desktop_config.json, use:

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}

Instead of relative paths like ./data

Environment variables Copy Section

MCP servers inherit only a subset of environment variables automatically, like USER, HOME, and PATH.

To override the default variables or provide your own, you can specify an env key in claude_desktop_config.json:

{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key",
    }
  }
}

Server initialization Copy Section

Common initialization problems:

1. Path Issues

   • Incorrect server executable path
   • Missing required files
   • Permission problems
   • Try using an absolute path for command

2. Configuration Errors

   • Invalid JSON syntax
   • Missing required fields
   • Type mismatches

3. Environment Problems

   • Missing environment variables
   • Incorrect variable values
   • Permission restrictions

Connection problems Copy Section

When servers fail to connect:

1. Check Claude Desktop logs
2. Verify server process is running
3. Test standalone with Inspector
4. Verify protocol compatibility

Implementing logging Copy Chapter

Server-side logging Copy Section

When building a server that uses the local stdio transport, all messages logged to stderr (standard error) will be captured by the host application (e.g., Claude Desktop) automatically.

For all transports, you can also provide logging to the client by sending a log message notification:

Important events to log:

• Initialization steps
• Resource access
• Tool execution
• Error conditions
• Performance metrics

Client-side logging Copy Section

In client applications:

1. Enable debug logging
2. Monitor network traffic
3. Track message exchanges
4. Record error states

Debugging workflow Copy Chapter

Development cycle Copy Section

1. Initial Development

   • Use Inspector for basic testing
   • Implement core functionality
   • Add logging points

2. Integration Testing

   • Test in Claude Desktop
   • Monitor logs
   • Check error handling

Testing changes Copy Section

To test changes efficiently:

• Configuration changes: Restart Claude Desktop
• Server code changes: Use Command-R to reload
• Quick iteration: Use Inspector during development

Best practices Copy Chapter

Logging strategy Copy Section

1. Structured Logging

   • Use consistent formats
   • Include context
   • Add timestamps
   • Track request IDs

2. Error Handling

   • Log stack traces
   • Include error context
   • Track error patterns
   • Monitor recovery

3. Performance Tracking

   • Log operation timing
   • Monitor resource usage
   • Track message sizes
   • Measure latency

Security considerations Copy Section

When debugging:

1. Sensitive Data

   • Sanitize logs
   • Protect credentials
   • Mask personal information

2. Access Control

   • Verify permissions
   • Check authentication
   • Monitor access patterns

Getting help Copy Chapter

When encountering issues:

1. First Steps

   • Check server logs
   • Test with Inspector
   • Review configuration
   • Verify environment

2. Support Channels

   • GitHub issues
   • GitHub discussions

3. Providing Information

   • Log excerpts
   • Configuration files
   • Steps to reproduce
   • Environment details

Next steps Copy Chapter

File: docs/tools/inspector.mdx Copy Chapter

title: Inspector Copy Chapter

The MCP Inspector is an interactive developer tool for testing and debugging MCP servers. While the Debugging Guide covers the Inspector as part of the overall debugging toolkit, this document provides a detailed exploration of the Inspector's features and capabilities.

Getting started Copy Chapter

Installation and basic usage Copy Section

The Inspector runs directly through npx without requiring installation:

npx @modelcontextprotocol/inspector <command>

npx @modelcontextprotocol/inspector <command> <arg1> <arg2>

Inspecting servers from NPM or PyPi

A common way to start server packages from NPM or PyPi.

Inspecting locally developed servers

To inspect servers locally developed or downloaded as a repository, the most common
way is:

Please carefully read any attached README for the most accurate instructions.

Feature overview Copy Chapter

The Inspector provides several features for interacting with your MCP server:

Server connection pane Copy Section

• Allows selecting the transport for connecting to the server
• For local servers, supports customizing the command-line arguments and environment

Resources tab Copy Section

• Lists all available resources
• Shows resource metadata (MIME types, descriptions)
• Allows resource content inspection
• Supports subscription testing

Prompts tab Copy Section

• Displays available prompt templates
• Shows prompt arguments and descriptions
• Enables prompt testing with custom arguments
• Previews generated messages

Tools tab Copy Section

• Lists available tools
• Shows tool schemas and descriptions
• Enables tool testing with custom inputs
• Displays tool execution results

Notifications pane Copy Section

• Presents all logs recorded from the server
• Shows notifications received from the server

Best practices Copy Chapter

Development workflow Copy Section

1. Start Development

   • Launch Inspector with your server
   • Verify basic connectivity
   • Check capability negotiation

2. Iterative testing

   • Make server changes
   • Rebuild the server
   • Reconnect the Inspector
   • Test affected features
   • Monitor messages

3. Test edge cases

   • Invalid inputs
   • Missing prompt arguments
   • Concurrent operations
   • Verify error handling and error responses

Next steps Copy Chapter

<Card
    title="Debugging Guide"
    icon="bug"
    href="/docs/tools/debugging"
>
    Learn about broader debugging strategies
</Card>

File: docs/concepts/architecture.mdx Copy Chapter

title: "Core architecture" Copy Chapter

The Model Context Protocol (MCP) is built on a flexible, extensible architecture that enables seamless communication between LLM applications and integrations. This document covers the core architectural components and concepts.

Overview Copy Chapter

MCP follows a client-server architecture where:

• Hosts are LLM applications (like Claude Desktop or IDEs) that initiate connections
• Clients maintain 1:1 connections with servers, inside the host application
• Servers provide context, tools, and prompts to clients

flowchart LR
    subgraph "Host"
        client1[MCP Client]
        client2[MCP Client]
    end
    subgraph "Server Process"
        server1[MCP Server]
    end
    subgraph "Server Process"
        server2[MCP Server]
    end

    client1 <-->|Transport Layer| server1
    client2 <-->|Transport Layer| server2

Core components Copy Chapter

Protocol layer Copy Section

The protocol layer handles message framing, request/response linking, and high-level communication patterns.

// Handle incoming notifications
    setNotificationHandler<T>(schema: T, handler: (notification: T) => Promise<void>): void

    // Send requests and await responses
    request<T>(request: Request, schema: T, options?: RequestOptions): Promise<T>

    // Send one-way notifications
    notification(notification: Notification): Promise<void>
}
```

async def send_notification(
        self,
        notification: NotificationT
    ) -> None:
        """Send one-way notification that doesn't expect response."""
        # Notification handling implementation

    async def _received_request(
        self,
        responder: RequestResponder[ReceiveRequestT, ResultT]
    ) -> None:
        """Handle incoming request from other side."""
        # Request handling implementation

    async def _received_notification(
        self,
        notification: ReceiveNotificationT
    ) -> None:
        """Handle incoming notification from other side."""
        # Notification handling implementation
```

Key classes include:

• Protocol
• Client
• Server

Transport layer Copy Section

The transport layer handles the actual communication between clients and servers. MCP supports multiple transport mechanisms:

1. Stdio transport

   • Uses standard input/output for communication
   • Ideal for local processes

2. HTTP with SSE transport

   • Uses Server-Sent Events for server-to-client messages
   • HTTP POST for client-to-server messages

All transports use JSON-RPC 2.0 to exchange messages. See the specification for detailed information about the Model Context Protocol message format.

Message types Copy Section

MCP has these main types of messages:

1. Requests expect a response from the other side:

   typescript Copy

   interface Request {
     method: string;
     params?: { ... };
   }

2. Results are successful responses to requests:

   typescript Copy

   interface Result {
     [key: string]: unknown;
   }

3. Errors indicate that a request failed:

   typescript Copy

   interface Error {
     code: number;
     message: string;
     data?: unknown;
   }

4. Notifications are one-way messages that don't expect a response:

   typescript Copy

   interface Notification {
     method: string;
     params?: { ... };
   }

Connection lifecycle Copy Chapter

1. Initialization Copy Section

sequenceDiagram
    participant Client
    participant Server

    Client->>Server: initialize request
    Server->>Client: initialize response
    Client->>Server: initialized notification

    Note over Client,Server: Connection ready for use

1. Client sends initialize request with protocol version and capabilities
2. Server responds with its protocol version and capabilities
3. Client sends initialized notification as acknowledgment
4. Normal message exchange begins

2. Message exchange Copy Section

After initialization, the following patterns are supported:

• Request-Response: Client or server sends requests, the other responds
• Notifications: Either party sends one-way messages

3. Termination Copy Section

Either party can terminate the connection:

• Clean shutdown via close()
• Transport disconnection
• Error conditions

Error handling Copy Chapter

MCP defines these standard error codes:

enum ErrorCode {
  // Standard JSON-RPC error codes
  ParseError = -32700,
  InvalidRequest = -32600,
  MethodNotFound = -32601,
  InvalidParams = -32602,
  InternalError = -32603
}

SDKs and applications can define their own error codes above -32000.

Errors are propagated through:

• Error responses to requests
• Error events on transports
• Protocol-level error handlers

Implementation example Copy Chapter

Here's a basic example of implementing an MCP server:

const server = new Server({
  name: "example-server",
  version: "1.0.0"
}, {
  capabilities: {
    resources: {}
  }
});

// Handle requests
server.setRequestHandler(ListResourcesRequestSchema, async () => {
  return {
    resources: [
      {
        uri: "example://resource",
        name: "Example Resource"
      }
    ]
  };
});

// Connect transport
const transport = new StdioServerTransport();
await server.connect(transport);
```

app = Server("example-server")

@app.list_resources()
async def list_resources() -> list[types.Resource]:
    return [
        types.Resource(
            uri="example://resource",
            name="Example Resource"
        )
    ]

async def main():
    async with stdio_server() as streams:
        await app.run(
            streams[0],
            streams[1],
            app.create_initialization_options()
        )

if __name__ == "__main__":
    asyncio.run(main())
```

Best practices Copy Chapter

Transport selection Copy Section

1. Local communication

   • Use stdio transport for local processes
   • Efficient for same-machine communication
   • Simple process management

2. Remote communication

   • Use SSE for scenarios requiring HTTP compatibility
   • Consider security implications including authentication and authorization

Message handling Copy Section

1. Request processing

   • Validate inputs thoroughly
   • Use type-safe schemas
   • Handle errors gracefully
   • Implement timeouts

2. Progress reporting

   • Use progress tokens for long operations
   • Report progress incrementally
   • Include total progress when known

3. Error management

   • Use appropriate error codes
   • Include helpful error messages
   • Clean up resources on errors

Security considerations Copy Chapter

1. Transport security

   • Use TLS for remote connections
   • Validate connection origins
   • Implement authentication when needed

2. Message validation

   • Validate all incoming messages
   • Sanitize inputs
   • Check message size limits
   • Verify JSON-RPC format

3. Resource protection

   • Implement access controls
   • Validate resource paths
   • Monitor resource usage
   • Rate limit requests

4. Error handling

   • Don't leak sensitive information
   • Log security-relevant errors
   • Implement proper cleanup
   • Handle DoS scenarios

Debugging and monitoring Copy Chapter

1. Logging

   • Log protocol events
   • Track message flow
   • Monitor performance
   • Record errors

2. Diagnostics

   • Implement health checks
   • Monitor connection state
   • Track resource usage
   • Profile performance

3. Testing

   • Test different transports
   • Verify error handling
   • Check edge cases
   • Load test servers

File: docs/concepts/prompts.mdx Copy Chapter

title: "Prompts" Copy Chapter

Prompts enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs. They provide a powerful way to standardize and share common LLM interactions.

Overview Copy Chapter

Prompts in MCP are predefined templates that can:

• Accept dynamic arguments
• Include context from resources
• Chain multiple interactions
• Guide specific workflows
• Surface as UI elements (like slash commands)

Prompt structure Copy Chapter

Each prompt is defined with:

{
  name: string;              // Unique identifier for the prompt
  description?: string;      // Human-readable description
  arguments?: [              // Optional list of arguments
    {
      name: string;          // Argument identifier
      description?: string;  // Argument description
      required?: boolean;    // Whether argument is required
    }
  ]
}

Discovering prompts Copy Chapter

Clients can discover available prompts through the prompts/list endpoint:

// Request
{
  method: "prompts/list"
}

// Response
{
  prompts: [
    {
      name: "analyze-code",
      arguments: [
        {
          name: "language",
          required: true
        }
      ]
    }
  ]
}

Using prompts Copy Chapter

To use a prompt, clients make a prompts/get request:

// Request
{
  method: "prompts/get",
  params: {
    name: "analyze-code",
    arguments: {
      language: "python"
    }
  }
}

// Response
{
  messages: [
    {
      role: "user",
      content: {
        type: "text",
        text: "Please analyze the following Python code for potential improvements:\n\n```python\ndef calculate_sum(numbers):\n    total = 0\n    for num in numbers:\n        total = total + num\n    return total\n\nresult = calculate_sum([1, 2, 3, 4, 5])\nprint(result)\n```"
      }
    }
  ]
}

Dynamic prompts Copy Chapter

Prompts can be dynamic and include:

Embedded resource context Copy Section

{
  "name": "analyze-project",
  "description": "Analyze project logs and code",
  "arguments": [
    {
      "name": "timeframe",
      "description": "Time period to analyze logs",
      "required": true
    },
    {
      "name": "fileUri",
      "description": "URI of code file to review",
      "required": true
    }
  ]
}

When handling the prompts/get request:

{
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "Analyze these system logs and the code file for any issues:"
      }
    },
    {
      "role": "user",
      "content": {
        "type": "resource",
        "resource": {
          "uri": "logs://recent?timeframe=1h",
          "text": "[2024-03-14 15:32:11] ERROR: Connection timeout in network.py:127\n[2024-03-14 15:32:15] WARN: Retrying connection (attempt 2/3)\n[2024-03-14 15:32:20] ERROR: Max retries exceeded",
          "mimeType": "text/plain"
        }
      }
    },
    {
      "role": "user",
      "content": {
        "type": "resource",
        "resource": {
          "uri": "file:///path/to/code.py",
          "text": "def connect_to_service(timeout=30):\n    retries = 3\n    for attempt in range(retries):\n        try:\n            return establish_connection(timeout)\n        except TimeoutError:\n            if attempt == retries - 1:\n                raise\n            time.sleep(5)\n\ndef establish_connection(timeout):\n    # Connection implementation\n    pass",
          "mimeType": "text/x-python"
        }
      }
    }
  ]
}

Multi-step workflows Copy Section

const debugWorkflow = {
  name: "debug-error",
  async getMessages(error: string) {
    return [
      {
        role: "user",
        content: {
          type: "text",
          text: `Here's an error I'm seeing: ${error}`
        }
      },
      {
        role: "assistant",
        content: {
          type: "text",
          text: "I'll help analyze this error. What have you tried so far?"
        }
      },
      {
        role: "user",
        content: {
          type: "text",
          text: "I've tried restarting the service, but the error persists."
        }
      }
    ];
  }
};

Example implementation Copy Chapter

Here's a complete example of implementing prompts in an MCP server:

Best practices Copy Chapter

When implementing prompts:

1. Use clear, descriptive prompt names
2. Provide detailed descriptions for prompts and arguments
3. Validate all required arguments
4. Handle missing arguments gracefully
5. Consider versioning for prompt templates
6. Cache dynamic content when appropriate
7. Implement error handling
8. Document expected argument formats
9. Consider prompt composability
10. Test prompts with various inputs

UI integration Copy Chapter

Prompts can be surfaced in client UIs as:

• Slash commands
• Quick actions
• Context menu items
• Command palette entries
• Guided workflows
• Interactive forms

Updates and changes Copy Chapter

Servers can notify clients about prompt changes:

1. Server capability: prompts.listChanged
2. Notification: notifications/prompts/list_changed
3. Client re-fetches prompt list

Security considerations Copy Chapter

When implementing prompts:

• Validate all arguments
• Sanitize user input
• Consider rate limiting
• Implement access controls
• Audit prompt usage
• Handle sensitive data appropriately
• Validate generated content
• Implement timeouts
• Consider prompt injection risks
• Document security requirements

File: docs/concepts/resources.mdx Copy Chapter

title: "Resources" Copy Chapter

Resources are a core primitive in the Model Context Protocol (MCP) that allow servers to expose data and content that can be read by clients and used as context for LLM interactions.

[protocol]://[host]/[path]

{
  uri: string;           // Unique identifier for the resource
  name: string;          // Human-readable name
  description?: string;  // Optional description
  mimeType?: string;     // Optional MIME type
}

{
  uriTemplate: string;   // URI template following RFC 6570
  name: string;          // Human-readable name for this type
  description?: string;  // Optional description
  mimeType?: string;     // Optional MIME type for all matching resources
}

{
  contents: [
    {
      uri: string;        // The URI of the resource
      mimeType?: string;  // Optional MIME type

      // One of:
      text?: string;      // For text resources
      blob?: string;      // For binary resources (base64 encoded)
    }
  ]
}

// List available resources
server.setRequestHandler(ListResourcesRequestSchema, async () => {
  return {
    resources: [
      {
        uri: "file:///logs/app.log",
        name: "Application Logs",
        mimeType: "text/plain"
      }
    ]
  };
});

// Read resource contents
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  const uri = request.params.uri;

  if (uri === "file:///logs/app.log") {
    const logContents = await readLogFile();
    return {
      contents: [
        {
          uri,
          mimeType: "text/plain",
          text: logContents
        }
      ]
    };
  }

  throw new Error("Resource not found");
});
```

@app.list_resources()
async def list_resources() -> list[types.Resource]:
    return [
        types.Resource(
            uri="file:///logs/app.log",
            name="Application Logs",
            mimeType="text/plain"
        )
    ]

@app.read_resource()
async def read_resource(uri: AnyUrl) -> str:
    if str(uri) == "file:///logs/app.log":
        log_contents = await read_log_file()
        return log_contents

    raise ValueError("Resource not found")

# Start server
async with stdio_server() as streams:
    await app.run(
        streams[0],
        streams[1],
        app.create_initialization_options()
    )
```

file:///home/user/projects/myapp
https://api.example.com/v1

{
  "roots": [
    {
      "uri": "file:///home/user/projects/frontend",
      "name": "Frontend Repository"
    },
    {
      "uri": "https://api.example.com/v1",
      "name": "API Endpoint"
    }
  ]
}

{
  messages: [
    {
      role: "user" | "assistant",
      content: {
        type: "text" | "image",

        // For text:
        text?: string,

        // For images:
        data?: string,             // base64 encoded
        mimeType?: string
      }
    }
  ],
  modelPreferences?: {
    hints?: [{
      name?: string                // Suggested model name/family
    }],
    costPriority?: number,         // 0-1, importance of minimizing cost
    speedPriority?: number,        // 0-1, importance of low latency
    intelligencePriority?: number  // 0-1, importance of capabilities
  },
  systemPrompt?: string,
  includeContext?: "none" | "thisServer" | "allServers",
  temperature?: number,
  maxTokens: number,
  stopSequences?: string[],
  metadata?: Record<string, unknown>
}

{
  model: string,  // Name of the model used
  stopReason?: "endTurn" | "stopSequence" | "maxTokens" | string,
  role: "user" | "assistant",
  content: {
    type: "text" | "image",
    text?: string,
    data?: string,
    mimeType?: string
  }
}

{
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "What files are in the current directory?"
        }
      }
    ],
    "systemPrompt": "You are a helpful file system assistant.",
    "includeContext": "thisServer",
    "maxTokens": 100
  }
}

{
  name: string;          // Unique identifier for the tool
  description?: string;  // Human-readable description
  inputSchema: {         // JSON Schema for the tool's parameters
    type: "object",
    properties: { ... }  // Tool-specific parameters
  }
}

// Define available tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: "calculate_sum",
      inputSchema: {
        type: "object",
        properties: {
          a: { type: "number" },
          b: { type: "number" }
        },
        required: ["a", "b"]
      }
    }]
  };
});

// Handle tool execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "calculate_sum") {
    const { a, b } = request.params.arguments;
    return {
      content: [
        {
          type: "text",
          text: String(a + b)
        }
      ]
    };
  }
  throw new Error("Tool not found");
});
```

@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="calculate_sum",
            description="Add two numbers together",
            inputSchema={
                "type": "object",
                "properties": {
                    "a": {"type": "number"},
                    "b": {"type": "number"}
                },
                "required": ["a", "b"]
            }
        )
    ]

@app.call_tool()
async def call_tool(
    name: str,
    arguments: dict
) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
    if name == "calculate_sum":
        a = arguments["a"]
        b = arguments["b"]
        result = a + b
        return [types.TextContent(type="text", text=str(result))]
    raise ValueError(f"Tool not found: {name}")
```

{
  name: "execute_command",
  inputSchema: {
    type: "object",
    properties: {
      command: { type: "string" },
      args: { type: "array", items: { type: "string" } }
    }
  }
}

{
  name: "github_create_issue",
  inputSchema: {
    type: "object",
    properties: {
      title: { type: "string" },
      body: { type: "string" },
      labels: { type: "array", items: { type: "string" } }
    }
  }
}

{
  name: "analyze_csv",
  inputSchema: {
    type: "object",
    properties: {
      filepath: { type: "string" },
      operations: {
        type: "array",
        items: {
          enum: ["sum", "average", "count"]
        }
      }
    }
  }
}

{
  jsonrpc: "2.0",
  id: number | string,
  method: string,
  params?: object
}

{
  jsonrpc: "2.0",
  id: number | string,
  result?: object,
  error?: {
    code: number,
    message: string,
    data?: unknown
  }
}

{
  jsonrpc: "2.0",
  method: string,
  params?: object
}

const transport = new StdioServerTransport();
await server.connect(transport);
```

const transport = new StdioClientTransport({
  command: "./server",
  args: ["--option", "value"]
});
await client.connect(transport);
```

async with stdio_server() as streams:
    await app.run(
        streams[0],
        streams[1],
        app.create_initialization_options()
    )
```

async with stdio_client(params) as streams:
    async with ClientSession(streams[0], streams[1]) as session:
        await session.initialize()
```

const app = express();

const server = new Server({
  name: "example-server",
  version: "1.0.0"
}, {
  capabilities: {}
});

let transport: SSEServerTransport | null = null;

app.get("/sse", (req, res) => {
  transport = new SSEServerTransport("/messages", res);
  server.connect(transport);
});

app.post("/messages", (req, res) => {
  if (transport) {
    transport.handlePostMessage(req, res);
  }
});

app.listen(3000);
```

const transport = new SSEClientTransport(
  new URL("http://localhost:3000/sse")
);
await client.connect(transport);
```

app = Server("example-server")
sse = SseServerTransport("/messages")

async def handle_sse(scope, receive, send):
    async with sse.connect_sse(scope, receive, send) as streams:
        await app.run(streams[0], streams[1], app.create_initialization_options())

async def handle_messages(scope, receive, send):
    await sse.handle_post_message(scope, receive, send)

starlette_app = Starlette(
    routes=[
        Route("/sse", endpoint=handle_sse),
        Route("/messages", endpoint=handle_messages, methods=["POST"]),
    ]
)
```

// Send a JSON-RPC message
  send(message: JSONRPCMessage): Promise<void>;

  // Close the connection
  close(): Promise<void>;

  // Callbacks
  onclose?: () => void;
  onerror?: (error: Error) => void;
  onmessage?: (message: JSONRPCMessage) => void;
}
```

Args:
        read_stream: Stream to read incoming messages from
        write_stream: Stream to write outgoing messages to
    """
    async with anyio.create_task_group() as tg:
        try:
            # Start processing messages
            tg.start_soon(lambda: process_messages(read_stream))

            # Send messages
            async with write_stream:
                yield write_stream

        except Exception as exc:
            # Handle errors
            raise exc
        finally:
            # Clean up
            tg.cancel_scope.cancel()
            await write_stream.aclose()
            await read_stream.aclose()
```

async send(message: JSONRPCMessage) {
    try {
      // Sending logic
    } catch (error) {
      this.onerror?.(new Error(`Failed to send message: ${error}`));
      throw error;
    }
  }
}
```

async def message_handler():
            try:
                async with read_stream_writer:
                    # Message handling logic
                    pass
            except Exception as exc:
                logger.error(f"Failed to handle message: {exc}")
                raise exc

        async with anyio.create_task_group() as tg:
            tg.start_soon(message_handler)
            try:
                # Yield streams for communication
                yield read_stream, write_stream
            except Exception as exc:
                logger.error(f"Transport error: {exc}")
                raise exc
            finally:
                tg.cancel_scope.cancel()
                await write_stream.aclose()
                await read_stream.aclose()
    except Exception as exc:
        logger.error(f"Failed to initialize transport: {exc}")
        raise exc
```