icon to view:
* Connected servers
* Available prompts and resources
2. Click the 
icon to view:
* Tools made available to the model
### Viewing logs
Review detailed MCP logs from Claude Desktop:
```bash
# 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
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:
```bash
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
### Working directory
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:
```json
{
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}
```
Instead of relative paths like `./data`
### Environment variables
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`:
```json
{
"myserver": {
"command": "mcp-server-myapp",
"env": {
"MYAPP_API_KEY": "some_key",
}
}
}
```
### Server initialization
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
When servers fail to connect:
1. Check Claude Desktop logs
2. Verify server process is running
3. Test standalone with [Inspector](/docs/tools/inspector)
4. Verify protocol compatibility
## Implementing logging
### Server-side logging
When building a server that uses the local stdio [transport](/docs/concepts/transports), all messages logged to stderr (standard error) will be captured by the host application (e.g., Claude Desktop) automatically.
The Inspector provides several features for interacting with your MCP server:
### Server connection pane
* Allows selecting the [transport](/docs/concepts/transports) for connecting to the server
* For local servers, supports customizing the command-line arguments and environment
### Resources tab
* Lists all available resources
* Shows resource metadata (MIME types, descriptions)
* Allows resource content inspection
* Supports subscription testing
### Prompts tab
* Displays available prompt templates
* Shows prompt arguments and descriptions
* Enables prompt testing with custom arguments
* Previews generated messages
### Tools tab
* Lists available tools
* Shows tool schemas and descriptions
* Enables tool testing with custom inputs
* Displays tool execution results
### Notifications pane
* Presents all logs recorded from the server
* Shows notifications received from the server
## Best practices
### Development workflow
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
MCP creates a bridge between your AI applications and your data through a straightforward system:
* **MCP servers** connect to your data sources and tools (like Google Drive or Slack)
* **MCP clients** are run by AI applications (like Claude Desktop) to connect them to these servers
* When you give permission, your AI application discovers available MCP servers
* The AI model can then use these connections to read information and take actions
This modular system means new capabilities can be added without changing AI applications themselves—just like adding new accessories to your computer without upgrading your entire system.
## Who creates and maintains MCP servers?
MCP servers are developed and maintained by:
* Developers at Anthropic who build servers for common tools and data sources
* Open source contributors who create servers for tools they use
* Enterprise development teams building servers for their internal systems
* Software providers making their applications AI-ready
Once an open source MCP server is created for a data source, it can be used by any MCP-compatible AI application, creating a growing ecosystem of connections. See our [list of example servers](http://139.144.217.136/examples), or [get started building your own server](http://139.144.217.136/quickstart/server).
# Introduction
Source: http://139.144.217.136/introduction
Get started with the Model Context Protocol (MCP)
## How It Works
When you submit a query:
1. The client gets the list of available tools from the server
2. Your query is sent to Claude along with tool descriptions
3. Claude decides which tools (if any) to use
4. The client executes any requested tool calls through the server
5. Results are sent back to Claude
6. Claude provides a natural language response
7. The response is displayed to you
## Best practices
1. **Error Handling**
* Always wrap tool calls in try-catch blocks
* Provide meaningful error messages
* Gracefully handle connection issues
2. **Resource Management**
* Use `AsyncExitStack` for proper cleanup
* Close connections when done
* Handle server disconnections
3. **Security**
* Store API keys securely in `.env`
* Validate server responses
* Be cautious with tool permissions
## Troubleshooting
### Server Path Issues
* Double-check the path to your server script is correct
* Use the absolute path if the relative path isn't working
* For Windows users, make sure to use forward slashes (/) or escaped backslashes (\\) in the path
* Verify the server file has the correct extension (.py for Python or .js for Node.js)
Example of correct path usage:
```bash
# Relative path
uv run client.py ./server/weather.py
# Absolute path
uv run client.py /Users/username/projects/mcp-server/weather.py
# Windows path (either format works)
uv run client.py C:/projects/mcp-server/weather.py
uv run client.py C:\\projects\\mcp-server\\weather.py
```
### Response Timing
* The first response might take up to 30 seconds to return
* This is normal and happens while:
* The server initializes
* Claude processes the query
* Tools are being executed
* Subsequent responses are typically faster
* Don't interrupt the process during this initial waiting period
### Common Error Messages
If you see:
* `FileNotFoundError`: Check your server path
* `Connection refused`: Ensure the server is running and the path is correct
* `Tool execution failed`: Verify the tool's required environment variables are set
* `Timeout error`: Consider increasing the timeout in your client configuration
icon:
After clicking on the hammer icon, you should see two tools listed:
If your server isn't being picked up by Claude for Desktop, proceed to the [Troubleshooting](#troubleshooting) section for debugging tips.
If the hammer icon has shown up, you can now test your server by running the following commands in Claude for Desktop:
* What's the weather in Sacramento?
* What are the active weather alerts in Texas?
Don't worry — it will ask you for your permission before executing these actions!
## 1. Download Claude for Desktop
Start by downloading [Claude for Desktop](https://claude.ai/download), choosing either macOS or Windows. (Linux is not yet supported for Claude for Desktop.)
Follow the installation instructions.
If you already have Claude for Desktop, make sure it's on the latest version by clicking on the Claude menu on your computer and selecting "Check for Updates..."
Click on "Developer" in the left-hand bar of the Settings pane, and then click on "Edit Config":
This will create a configuration file at:
* macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
* Windows: `%APPDATA%\Claude\claude_desktop_config.json`
if you don't already have one, and will display the file in your file system.
Open up the configuration file in any text editor. Replace the file contents with this:
icon in the bottom right corner of the input box:
After clicking on the hammer icon, you should see the tools that come with the Filesystem MCP Server:
If your server isn't being picked up by Claude for Desktop, proceed to the [Troubleshooting](#troubleshooting) section for debugging tips.
## 4. Try it out!
You can now talk to Claude and ask it about your filesystem. It should know when to call the relevant tools.
Things you might try asking Claude:
* Can you write a poem and save it to my desktop?
* What are some work-related files in my downloads folder?
* Can you take all the images on my desktop and move them to a new folder called "Images"?
As needed, Claude will call the relevant tools and seek your approval before taking an action:
## Troubleshooting
- Bidirectional communication through stdin/stdout
- Process-based integration support
- Simple setup and configuration
- Lightweight implementation
Creates WebFlux-based SSE server transport.
Requires the mcp-spring-webflux dependency.
Implements the MCP HTTP with SSE transport specification, providing:
- Reactive HTTP streaming with WebFlux
- Concurrent client connections through SSE endpoints
- Message routing and session management
- Graceful shutdown capabilities
Creates WebMvc-based SSE server transport.
Requires the mcp-spring-webmvc dependency.
Implements the MCP HTTP with SSE transport specification, providing:
- Server-side event streaming
- Integration with Spring WebMVC
- Support for traditional web applications
- Synchronous operation handling
Creates a Servlet-based SSE server transport. It is included in the core mcp module.
The HttpServletSseServerTransport can be used with any Servlet container.
To use it with a Spring Web application, you can register it as a Servlet bean:
Implements the MCP HTTP with SSE transport specification using the traditional Servlet API, providing:
- Asynchronous message handling using Servlet 6.0 async support
- Session management for multiple client connections
-
Two types of endpoints:
- SSE endpoint (
/sse) for server-to-client events - Message endpoint (configurable) for client-to-server requests
- SSE endpoint (
- Error handling and response formatting
- Graceful shutdown support
Files & Git] S2[Server 2
Database] R1[("Local
Resource A")] R2[("Local
Resource B")] C1 --> S1 C2 --> S2 S1 <--> R1 S2 <--> R2 end subgraph "Internet" S3[Server 3
External APIs] R3[("Remote
Resource C")] C3 --> S3 S3 <--> R3 end ``` ### Host The host process acts as the container and coordinator: * Creates and manages multiple client instances * Controls client connection permissions and lifecycle * Enforces security policies and consent requirements * Handles user authorization decisions * Coordinates AI/LLM integration and sampling * Manages context aggregation across clients ### Clients Each client is created by the host and maintains an isolated server connection: * Establishes one stateful session per server * Handles protocol negotiation and capability exchange * Routes protocol messages bidirectionally * Manages subscriptions and notifications * Maintains security boundaries between servers A host application creates and manages multiple clients, with each client having a 1:1 relationship with a particular server. ### Servers Servers provide specialized context and capabilities: * Expose resources, tools and prompts via MCP primitives * Operate independently with focused responsibilities * Request sampling through client interfaces * Must respect security constraints * Can be local processes or remote services ## Design Principles MCP is built on several key design principles that inform its architecture and implementation: 1. **Servers should be extremely easy to build** * Host applications handle complex orchestration responsibilities * Servers focus on specific, well-defined capabilities * Simple interfaces minimize implementation overhead * Clear separation enables maintainable code 2. **Servers should be highly composable** * Each server provides focused functionality in isolation * Multiple servers can be combined seamlessly * Shared protocol enables interoperability * Modular design supports extensibility 3. **Servers should not be able to read the whole conversation, nor "see into" other servers** * Servers receive only necessary contextual information * Full conversation history stays with the host * Each server connection maintains isolation * Cross-server interactions are controlled by the host * Host process enforces security boundaries 4. **Features can be added to servers and clients progressively** * Core protocol provides minimal required functionality * Additional capabilities can be negotiated as needed * Servers and clients evolve independently * Protocol designed for future extensibility * Backwards compatibility is maintained ## Message Types MCP defines three core message types based on [JSON-RPC 2.0](https://www.jsonrpc.org/specification): * **Requests**: Bidirectional messages with method and parameters expecting a response * **Responses**: Successful results or errors matching specific request IDs * **Notifications**: One-way messages requiring no response Each message type follows the JSON-RPC 2.0 specification for structure and delivery semantics. ## Capability Negotiation The Model Context Protocol uses a capability-based negotiation system where clients and servers explicitly declare their supported features during initialization. Capabilities determine which protocol features and primitives are available during a session. * Servers declare capabilities like resource subscriptions, tool support, and prompt templates * Clients declare capabilities like sampling support and notification handling * Both parties must respect declared capabilities throughout the session * Additional capabilities can be negotiated through extensions to the protocol ```mermaid sequenceDiagram participant Host participant Client participant Server Host->>+Client: Initialize client Client->>+Server: Initialize session with capabilities Server-->>Client: Respond with supported capabilities Note over Host,Server: Active Session with Negotiated Features loop Client Requests Host->>Client: User- or model-initiated action Client->>Server: Request (tools/resources) Server-->>Client: Response Client-->>Host: Update UI or respond to model end loop Server Requests Server->>Client: Request (sampling) Client->>Host: Forward to AI Host-->>Client: AI response Client-->>Server: Response end loop Notifications Server--)Client: Resource updates Client--)Server: Status changes end Host->>Client: Terminate Client->>-Server: End session deactivate Server ``` Each capability unlocks specific protocol features for use during the session. For example: * Implemented [server features](/specification/2024-11-05/server) must be advertised in the server's capabilities * Emitting resource subscription notifications requires the server to declare subscription support * Tool invocation requires the server to declare tool capabilities * [Sampling](/specification/2024-11-05/client) requires the client to declare support in its capabilities This capability negotiation ensures clients and servers have a clear understanding of supported functionality while maintaining protocol extensibility. # Overview Source: http://139.144.217.136/specification/2024-11-05/basic/index
completed before
cancellation arrives else If not completed Note over Server: Stop processing end ``` ## Implementation Notes * Both parties **SHOULD** log cancellation reasons for debugging * Application UIs **SHOULD** indicate when cancellation is requested ## Error Handling Invalid cancellation notifications **SHOULD** be ignored: * Unknown request IDs * Already completed requests * Malformed notifications This maintains the "fire and forget" nature of notifications while allowing for race conditions in asynchronous communication. # Ping Source: http://139.144.217.136/specification/2024-11-05/basic/utilities/ping
and above ``` ## Error Handling Servers **SHOULD** return standard JSON-RPC errors for common failure cases: * Invalid log level: `-32602` (Invalid params) * Configuration errors: `-32603` (Internal error) ## Implementation Considerations 1. Servers **SHOULD**: * Rate limit log messages * Include relevant context in data field * Use consistent logger names * Remove sensitive information 2. Clients **MAY**: * Present log messages in the UI * Implement log filtering/search * Display severity visually * Persist log messages ## Security 1. Log messages **MUST NOT** contain: * Credentials or secrets * Personal identifying information * Internal system details that could aid attacks 2. Implementations **SHOULD**: * Rate limit messages * Validate all data fields * Control log access * Monitor for sensitive content # Pagination Source: http://139.144.217.136/specification/2024-11-05/server/utilities/pagination
Files & Git] S2[Server 2
Database] R1[("Local
Resource A")] R2[("Local
Resource B")] C1 --> S1 C2 --> S2 S1 <--> R1 S2 <--> R2 end subgraph "Internet" S3[Server 3
External APIs] R3[("Remote
Resource C")] C3 --> S3 S3 <--> R3 end ``` ### Host The host process acts as the container and coordinator: * Creates and manages multiple client instances * Controls client connection permissions and lifecycle * Enforces security policies and consent requirements * Handles user authorization decisions * Coordinates AI/LLM integration and sampling * Manages context aggregation across clients ### Clients Each client is created by the host and maintains an isolated server connection: * Establishes one stateful session per server * Handles protocol negotiation and capability exchange * Routes protocol messages bidirectionally * Manages subscriptions and notifications * Maintains security boundaries between servers A host application creates and manages multiple clients, with each client having a 1:1 relationship with a particular server. ### Servers Servers provide specialized context and capabilities: * Expose resources, tools and prompts via MCP primitives * Operate independently with focused responsibilities * Request sampling through client interfaces * Must respect security constraints * Can be local processes or remote services ## Design Principles MCP is built on several key design principles that inform its architecture and implementation: 1. **Servers should be extremely easy to build** * Host applications handle complex orchestration responsibilities * Servers focus on specific, well-defined capabilities * Simple interfaces minimize implementation overhead * Clear separation enables maintainable code 2. **Servers should be highly composable** * Each server provides focused functionality in isolation * Multiple servers can be combined seamlessly * Shared protocol enables interoperability * Modular design supports extensibility 3. **Servers should not be able to read the whole conversation, nor "see into" other servers** * Servers receive only necessary contextual information * Full conversation history stays with the host * Each server connection maintains isolation * Cross-server interactions are controlled by the host * Host process enforces security boundaries 4. **Features can be added to servers and clients progressively** * Core protocol provides minimal required functionality * Additional capabilities can be negotiated as needed * Servers and clients evolve independently * Protocol designed for future extensibility * Backwards compatibility is maintained ## Capability Negotiation The Model Context Protocol uses a capability-based negotiation system where clients and servers explicitly declare their supported features during initialization. Capabilities determine which protocol features and primitives are available during a session. * Servers declare capabilities like resource subscriptions, tool support, and prompt templates * Clients declare capabilities like sampling support and notification handling * Both parties must respect declared capabilities throughout the session * Additional capabilities can be negotiated through extensions to the protocol ```mermaid sequenceDiagram participant Host participant Client participant Server Host->>+Client: Initialize client Client->>+Server: Initialize session with capabilities Server-->>Client: Respond with supported capabilities Note over Host,Server: Active Session with Negotiated Features loop Client Requests Host->>Client: User- or model-initiated action Client->>Server: Request (tools/resources) Server-->>Client: Response Client-->>Host: Update UI or respond to model end loop Server Requests Server->>Client: Request (sampling) Client->>Host: Forward to AI Host-->>Client: AI response Client-->>Server: Response end loop Notifications Server--)Client: Resource updates Client--)Server: Status changes end Host->>Client: Terminate Client->>-Server: End session deactivate Server ``` Each capability unlocks specific protocol features for use during the session. For example: * Implemented [server features](/specification/2025-03-26/server) must be advertised in the server's capabilities * Emitting resource subscription notifications requires the server to declare subscription support * Tool invocation requires the server to declare tool capabilities * [Sampling](/specification/2025-03-26/client) requires the client to declare support in its capabilities This capability negotiation ensures clients and servers have a clear understanding of supported functionality while maintaining protocol extensibility. # Authorization Source: http://139.144.217.136/specification/2025-03-26/basic/authorization
Mcp-Session-Id: 1868a90c... Client->>+Server: POST InitializedNotification
Mcp-Session-Id: 1868a90c... Server->>-Client: 202 Accepted note over Client, Server: client requests Client->>+Server: POST ... request ...
Mcp-Session-Id: 1868a90c... alt single HTTP response Server->>Client: ... response ... else server opens SSE stream loop while connection remains open Server-)Client: ... SSE messages from server ... end Server-)Client: SSE event: ... response ... end deactivate Server note over Client, Server: client notifications/responses Client->>+Server: POST ... notification/response ...
Mcp-Session-Id: 1868a90c... Server->>-Client: 202 Accepted note over Client, Server: server requests Client->>+Server: GET
Mcp-Session-Id: 1868a90c... loop while connection remains open Server-)Client: ... SSE messages from server ... end deactivate Server ``` ### Backwards Compatibility Clients and servers can maintain backwards compatibility with the deprecated [HTTP+SSE transport](/specification/2024-11-05/basic/transports#http-with-sse) (from protocol version 2024-11-05) as follows: **Servers** wanting to support older clients should: * Continue to host both the SSE and POST endpoints of the old transport, alongside the new "MCP endpoint" defined for the Streamable HTTP transport. * It is also possible to combine the old POST endpoint and the new MCP endpoint, but this may introduce unneeded complexity. **Clients** wanting to support older servers should: 1. Accept an MCP server URL from the user, which may point to either a server using the old transport or the new transport. 2. Attempt to POST an `InitializeRequest` to the server URL, with an `Accept` header as defined above: * If it succeeds, the client can assume this is a server supporting the new Streamable HTTP transport. * If it fails with an HTTP 4xx status code (e.g., 405 Method Not Allowed or 404 Not Found): * Issue a GET request to the server URL, expecting that this will open an SSE stream and return an `endpoint` event as the first event. * When the `endpoint` event arrives, the client can assume this is a server running the old HTTP+SSE transport, and should use that transport for all subsequent communication. ## Custom Transports Clients and servers **MAY** implement additional custom transport mechanisms to suit their specific needs. The protocol is transport-agnostic and can be implemented over any communication channel that supports bidirectional message exchange. Implementers who choose to support custom transports **MUST** ensure they preserve the JSON-RPC message format and lifecycle requirements defined by MCP. Custom transports **SHOULD** document their specific connection establishment and message exchange patterns to aid interoperability. # Cancellation Source: http://139.144.217.136/specification/2025-03-26/basic/utilities/cancellation
completed before
cancellation arrives else If not completed Note over Server: Stop processing end ``` ## Implementation Notes * Both parties **SHOULD** log cancellation reasons for debugging * Application UIs **SHOULD** indicate when cancellation is requested ## Error Handling Invalid cancellation notifications **SHOULD** be ignored: * Unknown request IDs * Already completed requests * Malformed notifications This maintains the "fire and forget" nature of notifications while allowing for race conditions in asynchronous communication. # Ping Source: http://139.144.217.136/specification/2025-03-26/basic/utilities/ping
and above ``` ## Error Handling Servers **SHOULD** return standard JSON-RPC errors for common failure cases: * Invalid log level: `-32602` (Invalid params) * Configuration errors: `-32603` (Internal error) ## Implementation Considerations 1. Servers **SHOULD**: * Rate limit log messages * Include relevant context in data field * Use consistent logger names * Remove sensitive information 2. Clients **MAY**: * Present log messages in the UI * Implement log filtering/search * Display severity visually * Persist log messages ## Security 1. Log messages **MUST NOT** contain: * Credentials or secrets * Personal identifying information * Internal system details that could aid attacks 2. Implementations **SHOULD**: * Rate limit messages * Validate all data fields * Control log access * Monitor for sensitive content # Pagination Source: http://139.144.217.136/specification/2025-03-26/server/utilities/pagination
Files & Git] S2[Server 2
Database] R1[("Local
Resource A")] R2[("Local
Resource B")] C1 --> S1 C2 --> S2 S1 <--> R1 S2 <--> R2 end subgraph "Internet" S3[Server 3
External APIs] R3[("Remote
Resource C")] C3 --> S3 S3 <--> R3 end ``` ### Host The host process acts as the container and coordinator: * Creates and manages multiple client instances * Controls client connection permissions and lifecycle * Enforces security policies and consent requirements * Handles user authorization decisions * Coordinates AI/LLM integration and sampling * Manages context aggregation across clients ### Clients Each client is created by the host and maintains an isolated server connection: * Establishes one stateful session per server * Handles protocol negotiation and capability exchange * Routes protocol messages bidirectionally * Manages subscriptions and notifications * Maintains security boundaries between servers A host application creates and manages multiple clients, with each client having a 1:1 relationship with a particular server. ### Servers Servers provide specialized context and capabilities: * Expose resources, tools and prompts via MCP primitives * Operate independently with focused responsibilities * Request sampling through client interfaces * Must respect security constraints * Can be local processes or remote services ## Design Principles MCP is built on several key design principles that inform its architecture and implementation: 1. **Servers should be extremely easy to build** * Host applications handle complex orchestration responsibilities * Servers focus on specific, well-defined capabilities * Simple interfaces minimize implementation overhead * Clear separation enables maintainable code 2. **Servers should be highly composable** * Each server provides focused functionality in isolation * Multiple servers can be combined seamlessly * Shared protocol enables interoperability * Modular design supports extensibility 3. **Servers should not be able to read the whole conversation, nor "see into" other servers** * Servers receive only necessary contextual information * Full conversation history stays with the host * Each server connection maintains isolation * Cross-server interactions are controlled by the host * Host process enforces security boundaries 4. **Features can be added to servers and clients progressively** * Core protocol provides minimal required functionality * Additional capabilities can be negotiated as needed * Servers and clients evolve independently * Protocol designed for future extensibility * Backwards compatibility is maintained ## Capability Negotiation The Model Context Protocol uses a capability-based negotiation system where clients and servers explicitly declare their supported features during initialization. Capabilities determine which protocol features and primitives are available during a session. * Servers declare capabilities like resource subscriptions, tool support, and prompt templates * Clients declare capabilities like sampling support and notification handling * Both parties must respect declared capabilities throughout the session * Additional capabilities can be negotiated through extensions to the protocol ```mermaid sequenceDiagram participant Host participant Client participant Server Host->>+Client: Initialize client Client->>+Server: Initialize session with capabilities Server-->>Client: Respond with supported capabilities Note over Host,Server: Active Session with Negotiated Features loop Client Requests Host->>Client: User- or model-initiated action Client->>Server: Request (tools/resources) Server-->>Client: Response Client-->>Host: Update UI or respond to model end loop Server Requests Server->>Client: Request (sampling) Client->>Host: Forward to AI Host-->>Client: AI response Client-->>Server: Response end loop Notifications Server--)Client: Resource updates Client--)Server: Status changes end Host->>Client: Terminate Client->>-Server: End session deactivate Server ``` Each capability unlocks specific protocol features for use during the session. For example: * Implemented [server features](/specification/draft/server) must be advertised in the server's capabilities * Emitting resource subscription notifications requires the server to declare subscription support * Tool invocation requires the server to declare tool capabilities * [Sampling](/specification/draft/client) requires the client to declare support in its capabilities This capability negotiation ensures clients and servers have a clear understanding of supported functionality while maintaining protocol extensibility. # Authorization Source: http://139.144.217.136/specification/draft/basic/authorization
Mcp-Session-Id: 1868a90c... Client->>+Server: POST InitializedNotification
Mcp-Session-Id: 1868a90c... Server->>-Client: 202 Accepted note over Client, Server: client requests Client->>+Server: POST ... request ...
Mcp-Session-Id: 1868a90c... alt single HTTP response Server->>Client: ... response ... else server opens SSE stream loop while connection remains open Server-)Client: ... SSE messages from server ... end Server-)Client: SSE event: ... response ... end deactivate Server note over Client, Server: client notifications/responses Client->>+Server: POST ... notification/response ...
Mcp-Session-Id: 1868a90c... Server->>-Client: 202 Accepted note over Client, Server: server requests Client->>+Server: GET
Mcp-Session-Id: 1868a90c... loop while connection remains open Server-)Client: ... SSE messages from server ... end deactivate Server ``` ### Backwards Compatibility Clients and servers can maintain backwards compatibility with the deprecated [HTTP+SSE transport](/specification/2024-11-05/basic/transports#http-with-sse) (from protocol version 2024-11-05) as follows: **Servers** wanting to support older clients should: * Continue to host both the SSE and POST endpoints of the old transport, alongside the new "MCP endpoint" defined for the Streamable HTTP transport. * It is also possible to combine the old POST endpoint and the new MCP endpoint, but this may introduce unneeded complexity. **Clients** wanting to support older servers should: 1. Accept an MCP server URL from the user, which may point to either a server using the old transport or the new transport. 2. Attempt to POST an `InitializeRequest` to the server URL, with an `Accept` header as defined above: * If it succeeds, the client can assume this is a server supporting the new Streamable HTTP transport. * If it fails with an HTTP 4xx status code (e.g., 405 Method Not Allowed or 404 Not Found): * Issue a GET request to the server URL, expecting that this will open an SSE stream and return an `endpoint` event as the first event. * When the `endpoint` event arrives, the client can assume this is a server running the old HTTP+SSE transport, and should use that transport for all subsequent communication. ## Custom Transports Clients and servers **MAY** implement additional custom transport mechanisms to suit their specific needs. The protocol is transport-agnostic and can be implemented over any communication channel that supports bidirectional message exchange. Implementers who choose to support custom transports **MUST** ensure they preserve the JSON-RPC message format and lifecycle requirements defined by MCP. Custom transports **SHOULD** document their specific connection establishment and message exchange patterns to aid interoperability. # Cancellation Source: http://139.144.217.136/specification/draft/basic/utilities/cancellation
completed before
cancellation arrives else If not completed Note over Server: Stop processing end ``` ## Implementation Notes * Both parties **SHOULD** log cancellation reasons for debugging * Application UIs **SHOULD** indicate when cancellation is requested ## Error Handling Invalid cancellation notifications **SHOULD** be ignored: * Unknown request IDs * Already completed requests * Malformed notifications This maintains the "fire and forget" nature of notifications while allowing for race conditions in asynchronous communication. # Ping Source: http://139.144.217.136/specification/draft/basic/utilities/ping
and above ``` ## Error Handling Servers **SHOULD** return standard JSON-RPC errors for common failure cases: * Invalid log level: `-32602` (Invalid params) * Configuration errors: `-32603` (Internal error) ## Implementation Considerations 1. Servers **SHOULD**: * Rate limit log messages * Include relevant context in data field * Use consistent logger names * Remove sensitive information 2. Clients **MAY**: * Present log messages in the UI * Implement log filtering/search * Display severity visually * Persist log messages ## Security 1. Log messages **MUST NOT** contain: * Credentials or secrets * Personal identifying information * Internal system details that could aid attacks 2. Implementations **SHOULD**: * Rate limit messages * Validate all data fields * Control log access * Monitor for sensitive content # Pagination Source: http://139.144.217.136/specification/draft/server/utilities/pagination