Kintone MCP Server

MIT License
Overview InspectNew Schema Related Servers Reviews Score
kintone-mcp-server
docs
mcp-specification
└── docs
    └── specification
        └── 2024-11-05
            ├── _index.md
            ├── architecture
                └── _index.md
            ├── basic
                ├── _index.md
                ├── lifecycle.md
                ├── messages.md
                ├── transports.md
                └── utilities
                │   ├── _index.md
                │   ├── cancellation.md
                │   ├── ping.md
                │   └── progress.md
            ├── client
                ├── _index.md
                ├── roots.md
                └── sampling.md
            └── server
                ├── _index.md
                ├── prompts.md
                ├── resource-picker.png
                ├── resources.md
                ├── slash-command.png
                ├── tools.md
                └── utilities
                    ├── _index.md
                    ├── completion.md
                    ├── logging.md
                    └── pagination.md


/docs/specification/2024-11-05/_index.md:
--------------------------------------------------------------------------------
| ---
| linkTitle: 2024-11-05 (Final)
| title: Model Context Protocol specification
| cascade:
|   type: docs
| breadcrumbs: false
| weight: 2
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that
| enables seamless integration between LLM applications and external data sources and
| tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating
| custom AI workflows, MCP provides a standardized way to connect LLMs with the context
| they need.
| 
| This specification defines the authoritative protocol requirements, based on the
| TypeScript schema in
| [schema.ts](https://github.com/modelcontextprotocol/specification/blob/main/schema/2024-11-05/schema.ts).
| 
| For implementation guides and examples, visit
| [modelcontextprotocol.io](https://modelcontextprotocol.io).
| 
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD
| NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
| interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14)
| [[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119)]
| [[RFC8174](https://datatracker.ietf.org/doc/html/rfc8174)] when, and only when, they
| appear in all capitals, as shown here.
| 
| ## Overview
| 
| MCP provides a standardized way for applications to:
| 
| - Share contextual information with language models
| - Expose tools and capabilities to AI systems
| - Build composable integrations and workflows
| 
| The protocol uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 messages to establish
| communication between:
| 
| - **Hosts**: LLM applications that initiate connections
| - **Clients**: Connectors within the host application
| - **Servers**: Services that provide context and capabilities
| 
| MCP takes some inspiration from the
| [Language Server Protocol](https://microsoft.github.io/language-server-protocol/), which
| standardizes how to add support for programming languages across a whole ecosystem of
| development tools. In a similar way, MCP standardizes how to integrate additional context
| and tools into the ecosystem of AI applications.
| 
| ## Key Details
| 
| ### Base Protocol
| 
| - [JSON-RPC](https://www.jsonrpc.org/) message format
| - Stateful connections
| - Server and client capability negotiation
| 
| ### Features
| 
| Servers offer any of the following features to clients:
| 
| - **Resources**: Context and data, for the user or the AI model to use
| - **Prompts**: Templated messages and workflows for users
| - **Tools**: Functions for the AI model to execute
| 
| Clients may offer the following feature to servers:
| 
| - **Sampling**: Server-initiated agentic behaviors and recursive LLM interactions
| 
| ### Additional Utilities
| 
| - Configuration
| - Progress tracking
| - Cancellation
| - Error reporting
| - Logging
| 
| ## Security and Trust & Safety
| 
| The Model Context Protocol enables powerful capabilities through arbitrary data access
| and code execution paths. With this power comes important security and trust
| considerations that all implementors must carefully address.
| 
| ### Key Principles
| 
| 1. **User Consent and Control**
| 
|    - Users must explicitly consent to and understand all data access and operations
|    - Users must retain control over what data is shared and what actions are taken
|    - Implementors should provide clear UIs for reviewing and authorizing activities
| 
| 2. **Data Privacy**
| 
|    - Hosts must obtain explicit user consent before exposing user data to servers
|    - Hosts must not transmit resource data elsewhere without user consent
|    - User data should be protected with appropriate access controls
| 
| 3. **Tool Safety**
| 
|    - Tools represent arbitrary code execution and must be treated with appropriate
|      caution
|    - Hosts must obtain explicit user consent before invoking any tool
|    - Users should understand what each tool does before authorizing its use
| 
| 4. **LLM Sampling Controls**
|    - Users must explicitly approve any LLM sampling requests
|    - Users should control:
|      - Whether sampling occurs at all
|      - The actual prompt that will be sent
|      - What results the server can see
|    - The protocol intentionally limits server visibility into prompts
| 
| ### Implementation Guidelines
| 
| While MCP itself cannot enforce these security principles at the protocol level,
| implementors **SHOULD**:
| 
| 1. Build robust consent and authorization flows into their applications
| 2. Provide clear documentation of security implications
| 3. Implement appropriate access controls and data protections
| 4. Follow security best practices in their integrations
| 5. Consider privacy implications in their feature designs
| 
| ## Learn More
| 
| Explore the detailed specification for each protocol component:
| 
| {{< cards >}} {{< card link="architecture" title="Architecture" icon="template" >}}
| {{< card link="basic" title="Base Protocol" icon="code" >}}
| {{< card link="server" title="Server Features" icon="server" >}}
| {{< card link="client" title="Client Features" icon="user" >}}
| {{< card link="contributing" title="Contributing" icon="pencil" >}} {{< /cards >}}
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/architecture/_index.md:
--------------------------------------------------------------------------------
| ---
| title: Architecture
| cascade:
|   type: docs
| weight: 1
| ---
| 
| The Model Context Protocol (MCP) follows a client-host-server architecture where each
| host can run multiple client instances. This architecture enables users to integrate AI
| capabilities across applications while maintaining clear security boundaries and
| isolating concerns. Built on JSON-RPC, MCP provides a stateful session protocol focused
| on context exchange and sampling coordination between clients and servers.
| 
| ## Core Components
| 
| ```mermaid
| graph LR
|     subgraph "Application Host Process"
|         H[Host]
|         C1[Client 1]
|         C2[Client 2]
|         C3[Client 3]
|         H --> C1
|         H --> C2
|         H --> C3
|     end
| 
|     subgraph "Local machine"
|         S1[Server 1<br>Files & Git]
|         S2[Server 2<br>Database]
|         R1[("Local<br>Resource A")]
|         R2[("Local<br>Resource B")]
| 
|         C1 --> S1
|         C2 --> S2
|         S1 <--> R1
|         S2 <--> R2
|     end
| 
|     subgraph "Internet"
|         S3[Server 3<br>External APIs]
|         R3[("Remote<br>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]({{< ref "/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]({{< ref "/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.
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/basic/_index.md:
--------------------------------------------------------------------------------
| ---
| title: Base Protocol
| cascade:
|   type: docs
| weight: 2
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| All messages between MCP clients and servers **MUST** follow the
| [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines
| three fundamental types of messages:
| 
| | Type            | Description                            | Requirements                           |
| | --------------- | -------------------------------------- | -------------------------------------- |
| | `Requests`      | Messages sent to initiate an operation | Must include unique ID and method name |
| | `Responses`     | Messages sent in reply to requests     | Must include same ID as request        |
| | `Notifications` | One-way messages with no reply         | Must not include an ID                 |
| 
| **Responses** are further sub-categorized as either **successful results** or **errors**.
| Results can follow any JSON object structure, while errors must include an error code and
| message at minimum.
| 
| ## Protocol Layers
| 
| The Model Context Protocol consists of several key components that work together:
| 
| - **Base Protocol**: Core JSON-RPC message types
| - **Lifecycle Management**: Connection initialization, capability negotiation, and
|   session control
| - **Server Features**: Resources, prompts, and tools exposed by servers
| - **Client Features**: Sampling and root directory lists provided by clients
| - **Utilities**: Cross-cutting concerns like logging and argument completion
| 
| All implementations **MUST** support the base protocol and lifecycle management
| components. Other components **MAY** be implemented based on the specific needs of the
| application.
| 
| These protocol layers establish clear separation of concerns while enabling rich
| interactions between clients and servers. The modular design allows implementations to
| support exactly the features they need.
| 
| See the following pages for more details on the different components:
| 
| {{< cards >}}
| {{< card link="/specification/2024-11-05/basic/lifecycle" title="Lifecycle" icon="refresh" >}}
| {{< card link="/specification/2024-11-05/server/resources" title="Resources" icon="document" >}}
| {{< card link="/specification/2024-11-05/server/prompts" title="Prompts" icon="chat-alt-2" >}}
| {{< card link="/specification/2024-11-05/server/tools" title="Tools" icon="adjustments" >}}
| {{< card link="/specification/2024-11-05/server/utilities/logging" title="Logging" icon="annotation" >}}
| {{< card link="/specification/2024-11-05/client/sampling" title="Sampling" icon="code" >}}
| {{< /cards >}}
| 
| ## Auth
| 
| Authentication and authorization are not currently part of the core MCP specification,
| but we are considering ways to introduce them in future. Join us in
| [GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions)
| to help shape the future of the protocol!
| 
| Clients and servers **MAY** negotiate their own custom authentication and authorization
| strategies.
| 
| ## Schema
| 
| The full specification of the protocol is defined as a
| [TypeScript schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/2024-11-05/schema.ts).
| This is the source of truth for all protocol messages and structures.
| 
| There is also a
| [JSON Schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/2024-11-05/schema.json),
| which is automatically generated from the TypeScript source of truth, for use with
| various automated tooling.
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/basic/lifecycle.md:
--------------------------------------------------------------------------------
| ---
| title: Lifecycle
| type: docs
| weight: 30
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| The Model Context Protocol (MCP) defines a rigorous lifecycle for client-server
| connections that ensures proper capability negotiation and state management.
| 
| 1. **Initialization**: Capability negotiation and protocol version agreement
| 2. **Operation**: Normal protocol communication
| 3. **Shutdown**: Graceful termination of the connection
| 
| ```mermaid
| sequenceDiagram
|     participant Client
|     participant Server
| 
|     Note over Client,Server: Initialization Phase
|     activate Client
|     Client->>+Server: initialize request
|     Server-->>Client: initialize response
|     Client--)Server: initialized notification
| 
|     Note over Client,Server: Operation Phase
|     rect rgb(200, 220, 250)
|         note over Client,Server: Normal protocol operations
|     end
| 
|     Note over Client,Server: Shutdown
|     Client--)-Server: Disconnect
|     deactivate Server
|     Note over Client,Server: Connection closed
| ```
| 
| ## Lifecycle Phases
| 
| ### Initialization
| 
| The initialization phase **MUST** be the first interaction between client and server.
| During this phase, the client and server:
| 
| - Establish protocol version compatibility
| - Exchange and negotiate capabilities
| - Share implementation details
| 
| The client **MUST** initiate this phase by sending an `initialize` request containing:
| 
| - Protocol version supported
| - Client capabilities
| - Client implementation information
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "method": "initialize",
|   "params": {
|     "protocolVersion": "2024-11-05",
|     "capabilities": {
|       "roots": {
|         "listChanged": true
|       },
|       "sampling": {}
|     },
|     "clientInfo": {
|       "name": "ExampleClient",
|       "version": "1.0.0"
|     }
|   }
| }
| ```
| 
| The server **MUST** respond with its own capabilities and information:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "result": {
|     "protocolVersion": "2024-11-05",
|     "capabilities": {
|       "logging": {},
|       "prompts": {
|         "listChanged": true
|       },
|       "resources": {
|         "subscribe": true,
|         "listChanged": true
|       },
|       "tools": {
|         "listChanged": true
|       }
|     },
|     "serverInfo": {
|       "name": "ExampleServer",
|       "version": "1.0.0"
|     }
|   }
| }
| ```
| 
| After successful initialization, the client **MUST** send an `initialized` notification
| to indicate it is ready to begin normal operations:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "method": "notifications/initialized"
| }
| ```
| 
| - The client **SHOULD NOT** send requests other than
|   [pings]({{< ref "/specification/2024-11-05/basic/utilities/ping" >}}) before the server
|   has responded to the `initialize` request.
| - The server **SHOULD NOT** send requests other than
|   [pings]({{< ref "/specification/2024-11-05/basic/utilities/ping" >}}) and
|   [logging]({{< ref "/specification/2024-11-05/server/utilities/logging" >}}) before
|   receiving the `initialized` notification.
| 
| #### Version Negotiation
| 
| In the `initialize` request, the client **MUST** send a protocol version it supports.
| This **SHOULD** be the _latest_ version supported by the client.
| 
| If the server supports the requested protocol version, it **MUST** respond with the same
| version. Otherwise, the server **MUST** respond with another protocol version it
| supports. This **SHOULD** be the _latest_ version supported by the server.
| 
| If the client does not support the version in the server's response, it **SHOULD**
| disconnect.
| 
| #### Capability Negotiation
| 
| Client and server capabilities establish which optional protocol features will be
| available during the session.
| 
| Key capabilities include:
| 
| | Category | Capability     | Description                                                                                       |
| | -------- | -------------- | ------------------------------------------------------------------------------------------------- |
| | Client   | `roots`        | Ability to provide filesystem [roots]({{< ref "/specification/2024-11-05/client/roots" >}})       |
| | Client   | `sampling`     | Support for LLM [sampling]({{< ref "/specification/2024-11-05/client/sampling" >}}) requests      |
| | Client   | `experimental` | Describes support for non-standard experimental features                                          |
| | Server   | `prompts`      | Offers [prompt templates]({{< ref "/specification/2024-11-05/server/prompts" >}})                 |
| | Server   | `resources`    | Provides readable [resources]({{< ref "/specification/2024-11-05/server/resources" >}})           |
| | Server   | `tools`        | Exposes callable [tools]({{< ref "/specification/2024-11-05/server/tools" >}})                    |
| | Server   | `logging`      | Emits structured [log messages]({{< ref "/specification/2024-11-05/server/utilities/logging" >}}) |
| | Server   | `experimental` | Describes support for non-standard experimental features                                          |
| 
| Capability objects can describe sub-capabilities like:
| 
| - `listChanged`: Support for list change notifications (for prompts, resources, and
|   tools)
| - `subscribe`: Support for subscribing to individual items' changes (resources only)
| 
| ### Operation
| 
| During the operation phase, the client and server exchange messages according to the
| negotiated capabilities.
| 
| Both parties **SHOULD**:
| 
| - Respect the negotiated protocol version
| - Only use capabilities that were successfully negotiated
| 
| ### Shutdown
| 
| During the shutdown phase, one side (usually the client) cleanly terminates the protocol
| connection. No specific shutdown messages are defined—instead, the underlying transport
| mechanism should be used to signal connection termination:
| 
| #### stdio
| 
| For the stdio [transport]({{< ref "/specification/2024-11-05/basic/transports" >}}), the
| client **SHOULD** initiate shutdown by:
| 
| 1. First, closing the input stream to the child process (the server)
| 2. Waiting for the server to exit, or sending `SIGTERM` if the server does not exit
|    within a reasonable time
| 3. Sending `SIGKILL` if the server does not exit within a reasonable time after `SIGTERM`
| 
| The server **MAY** initiate shutdown by closing its output stream to the client and
| exiting.
| 
| #### HTTP
| 
| For HTTP [transports]({{< ref "/specification/2024-11-05/basic/transports" >}}), shutdown
| is indicated by closing the associated HTTP connection(s).
| 
| ## Error Handling
| 
| Implementations **SHOULD** be prepared to handle these error cases:
| 
| - Protocol version mismatch
| - Failure to negotiate required capabilities
| - Initialize request timeout
| - Shutdown timeout
| 
| Implementations **SHOULD** implement appropriate timeouts for all requests, to prevent
| hung connections and resource exhaustion.
| 
| Example initialization error:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "error": {
|     "code": -32602,
|     "message": "Unsupported protocol version",
|     "data": {
|       "supported": ["2024-11-05"],
|       "requested": "1.0.0"
|     }
|   }
| }
| ```
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/basic/messages.md:
--------------------------------------------------------------------------------
| ---
| title: Messages
| type: docs
| weight: 20
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| All messages in MCP **MUST** follow the
| [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines
| three types of messages:
| 
| ## Requests
| 
| Requests are sent from the client to the server or vice versa.
| 
| ```typescript
| {
|   jsonrpc: "2.0";
|   id: string | number;
|   method: string;
|   params?: {
|     [key: string]: unknown;
|   };
| }
| ```
| 
| - Requests **MUST** include a string or integer ID.
| - Unlike base JSON-RPC, the ID **MUST NOT** be `null`.
| - The request ID **MUST NOT** have been previously used by the requestor within the same
|   session.
| 
| ## Responses
| 
| Responses are sent in reply to requests.
| 
| ```typescript
| {
|   jsonrpc: "2.0";
|   id: string | number;
|   result?: {
|     [key: string]: unknown;
|   }
|   error?: {
|     code: number;
|     message: string;
|     data?: unknown;
|   }
| }
| ```
| 
| - Responses **MUST** include the same ID as the request they correspond to.
| - Either a `result` or an `error` **MUST** be set. A response **MUST NOT** set both.
| - Error codes **MUST** be integers.
| 
| ## Notifications
| 
| Notifications are sent from the client to the server or vice versa. They do not expect a
| response.
| 
| ```typescript
| {
|   jsonrpc: "2.0";
|   method: string;
|   params?: {
|     [key: string]: unknown;
|   };
| }
| ```
| 
| - Notifications **MUST NOT** include an ID.
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/basic/transports.md:
--------------------------------------------------------------------------------
| ---
| title: Transports
| type: docs
| weight: 40
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| MCP currently defines two standard transport mechanisms for client-server communication:
| 
| 1. [stdio](#stdio), communication over standard in and standard out
| 2. [HTTP with Server-Sent Events](#http-with-sse) (SSE)
| 
| Clients **SHOULD** support stdio whenever possible.
| 
| It is also possible for clients and servers to implement
| [custom transports](#custom-transports) in a pluggable fashion.
| 
| ## stdio
| 
| In the **stdio** transport:
| 
| - The client launches the MCP server as a subprocess.
| - The server receives JSON-RPC messages on its standard input (`stdin`) and writes
|   responses to its standard output (`stdout`).
| - Messages are delimited by newlines, and **MUST NOT** contain embedded newlines.
| - The server **MAY** write UTF-8 strings to its standard error (`stderr`) for logging
|   purposes. Clients **MAY** capture, forward, or ignore this logging.
| - The server **MUST NOT** write anything to its `stdout` that is not a valid MCP message.
| - The client **MUST NOT** write anything to the server's `stdin` that is not a valid MCP
|   message.
| 
| ```mermaid
| sequenceDiagram
|     participant Client
|     participant Server Process
| 
|     Client->>+Server Process: Launch subprocess
|     loop Message Exchange
|         Client->>Server Process: Write to stdin
|         Server Process->>Client: Write to stdout
|         Server Process--)Client: Optional logs on stderr
|     end
|     Client->>Server Process: Close stdin, terminate subprocess
|     deactivate Server Process
| ```
| 
| ## HTTP with SSE
| 
| In the **SSE** transport, the server operates as an independent process that can handle
| multiple client connections.
| 
| The server **MUST** provide two endpoints:
| 
| 1. An SSE endpoint, for clients to establish a connection and receive messages from the
|    server
| 2. A regular HTTP POST endpoint for clients to send messages to the server
| 
| When a client connects, the server **MUST** send an `endpoint` event containing a URI for
| the client to use for sending messages. All subsequent client messages **MUST** be sent
| as HTTP POST requests to this endpoint.
| 
| Server messages are sent as SSE `message` events, with the message content encoded as
| JSON in the event data.
| 
| ```mermaid
| sequenceDiagram
|     participant Client
|     participant Server
| 
|     Client->>Server: Open SSE connection
|     Server->>Client: endpoint event
|     loop Message Exchange
|         Client->>Server: HTTP POST messages
|         Server->>Client: SSE message events
|     end
|     Client->>Server: Close SSE connection
| ```
| 
| ## 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.
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/basic/utilities/_index.md:
--------------------------------------------------------------------------------
| ---
| title: Utilities
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| These optional features enhance the base protocol functionality with various utilities.
| 
| {{< cards >}} {{< card link="ping" title="Ping" icon="status-online" >}}
| {{< card link="cancellation" title="Cancellation" icon="x" >}}
| {{< card link="progress" title="Progress" icon="clock" >}} {{< /cards >}}
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/basic/utilities/cancellation.md:
--------------------------------------------------------------------------------
| ---
| title: Cancellation
| weight: 10
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| The Model Context Protocol (MCP) supports optional cancellation of in-progress requests
| through notification messages. Either side can send a cancellation notification to
| indicate that a previously-issued request should be terminated.
| 
| ## Cancellation Flow
| 
| When a party wants to cancel an in-progress request, it sends a `notifications/cancelled`
| notification containing:
| 
| - The ID of the request to cancel
| - An optional reason string that can be logged or displayed
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "method": "notifications/cancelled",
|   "params": {
|     "requestId": "123",
|     "reason": "User requested cancellation"
|   }
| }
| ```
| 
| ## Behavior Requirements
| 
| 1. Cancellation notifications **MUST** only reference requests that:
|    - Were previously issued in the same direction
|    - Are believed to still be in-progress
| 2. The `initialize` request **MUST NOT** be cancelled by clients
| 3. Receivers of cancellation notifications **SHOULD**:
|    - Stop processing the cancelled request
|    - Free associated resources
|    - Not send a response for the cancelled request
| 4. Receivers **MAY** ignore cancellation notifications if:
|    - The referenced request is unknown
|    - Processing has already completed
|    - The request cannot be cancelled
| 5. The sender of the cancellation notification **SHOULD** ignore any response to the
|    request that arrives afterward
| 
| ## Timing Considerations
| 
| Due to network latency, cancellation notifications may arrive after request processing
| has completed, and potentially after a response has already been sent.
| 
| Both parties **MUST** handle these race conditions gracefully:
| 
| ```mermaid
| sequenceDiagram
|    participant Client
|    participant Server
| 
|    Client->>Server: Request (ID: 123)
|    Note over Server: Processing starts
|    Client--)Server: notifications/cancelled (ID: 123)
|    alt
|       Note over Server: Processing may have<br/>completed before<br/>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.
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/basic/utilities/ping.md:
--------------------------------------------------------------------------------
| ---
| title: Ping
| weight: 5
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| The Model Context Protocol includes an optional ping mechanism that allows either party
| to verify that their counterpart is still responsive and the connection is alive.
| 
| ## Overview
| 
| The ping functionality is implemented through a simple request/response pattern. Either
| the client or server can initiate a ping by sending a `ping` request.
| 
| ## Message Format
| 
| A ping request is a standard JSON-RPC request with no parameters:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": "123",
|   "method": "ping"
| }
| ```
| 
| ## Behavior Requirements
| 
| 1. The receiver **MUST** respond promptly with an empty response:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": "123",
|   "result": {}
| }
| ```
| 
| 2. If no response is received within a reasonable timeout period, the sender **MAY**:
|    - Consider the connection stale
|    - Terminate the connection
|    - Attempt reconnection procedures
| 
| ## Usage Patterns
| 
| ```mermaid
| sequenceDiagram
|     participant Sender
|     participant Receiver
| 
|     Sender->>Receiver: ping request
|     Receiver->>Sender: empty response
| ```
| 
| ## Implementation Considerations
| 
| - Implementations **SHOULD** periodically issue pings to detect connection health
| - The frequency of pings **SHOULD** be configurable
| - Timeouts **SHOULD** be appropriate for the network environment
| - Excessive pinging **SHOULD** be avoided to reduce network overhead
| 
| ## Error Handling
| 
| - Timeouts **SHOULD** be treated as connection failures
| - Multiple failed pings **MAY** trigger connection reset
| - Implementations **SHOULD** log ping failures for diagnostics
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/basic/utilities/progress.md:
--------------------------------------------------------------------------------
| ---
| title: Progress
| weight: 30
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| The Model Context Protocol (MCP) supports optional progress tracking for long-running
| operations through notification messages. Either side can send progress notifications to
| provide updates about operation status.
| 
| ## Progress Flow
| 
| When a party wants to _receive_ progress updates for a request, it includes a
| `progressToken` in the request metadata.
| 
| - Progress tokens **MUST** be a string or integer value
| - Progress tokens can be chosen by the sender using any means, but **MUST** be unique
|   across all active requests.
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "method": "some_method",
|   "params": {
|     "_meta": {
|       "progressToken": "abc123"
|     }
|   }
| }
| ```
| 
| The receiver **MAY** then send progress notifications containing:
| 
| - The original progress token
| - The current progress value so far
| - An optional "total" value
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "method": "notifications/progress",
|   "params": {
|     "progressToken": "abc123",
|     "progress": 50,
|     "total": 100
|   }
| }
| ```
| 
| - The `progress` value **MUST** increase with each notification, even if the total is
|   unknown.
| - The `progress` and the `total` values **MAY** be floating point.
| 
| ## Behavior Requirements
| 
| 1. Progress notifications **MUST** only reference tokens that:
| 
|    - Were provided in an active request
|    - Are associated with an in-progress operation
| 
| 2. Receivers of progress requests **MAY**:
|    - Choose not to send any progress notifications
|    - Send notifications at whatever frequency they deem appropriate
|    - Omit the total value if unknown
| 
| ```mermaid
| sequenceDiagram
|     participant Sender
|     participant Receiver
| 
|     Note over Sender,Receiver: Request with progress token
|     Sender->>Receiver: Method request with progressToken
| 
|     Note over Sender,Receiver: Progress updates
|     loop Progress Updates
|         Receiver-->>Sender: Progress notification (0.2/1.0)
|         Receiver-->>Sender: Progress notification (0.6/1.0)
|         Receiver-->>Sender: Progress notification (1.0/1.0)
|     end
| 
|     Note over Sender,Receiver: Operation complete
|     Receiver->>Sender: Method response
| ```
| 
| ## Implementation Notes
| 
| - Senders and receivers **SHOULD** track active progress tokens
| - Both parties **SHOULD** implement rate limiting to prevent flooding
| - Progress notifications **MUST** stop after completion
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/client/_index.md:
--------------------------------------------------------------------------------
| ---
| title: Client Features
| cascade:
|   type: docs
| weight: 4
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| Clients can implement additional features to enrich connected MCP servers:
| 
| {{< cards >}} {{< card link="roots" title="Roots" icon="folder" >}}
| {{< card link="sampling" title="Sampling" icon="annotation" >}} {{< /cards >}}
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/client/roots.md:
--------------------------------------------------------------------------------
| ---
| title: Roots
| type: docs
| weight: 40
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| The Model Context Protocol (MCP) provides a standardized way for clients to expose
| filesystem "roots" to servers. Roots define the boundaries of where servers can operate
| within the filesystem, allowing them to understand which directories and files they have
| access to. Servers can request the list of roots from supporting clients and receive
| notifications when that list changes.
| 
| ## User Interaction Model
| 
| Roots in MCP are typically exposed through workspace or project configuration interfaces.
| 
| For example, implementations could offer a workspace/project picker that allows users to
| select directories and files the server should have access to. This can be combined with
| automatic workspace detection from version control systems or project files.
| 
| However, implementations are free to expose roots through any interface pattern that
| suits their needs&mdash;the protocol itself does not mandate any specific user
| interaction model.
| 
| ## Capabilities
| 
| Clients that support roots **MUST** declare the `roots` capability during
| [initialization]({{< ref "/specification/2024-11-05/basic/lifecycle#initialization" >}}):
| 
| ```json
| {
|   "capabilities": {
|     "roots": {
|       "listChanged": true
|     }
|   }
| }
| ```
| 
| `listChanged` indicates whether the client will emit notifications when the list of roots
| changes.
| 
| ## Protocol Messages
| 
| ### Listing Roots
| 
| To retrieve roots, servers send a `roots/list` request:
| 
| **Request:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "method": "roots/list"
| }
| ```
| 
| **Response:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "result": {
|     "roots": [
|       {
|         "uri": "file:///home/user/projects/myproject",
|         "name": "My Project"
|       }
|     ]
|   }
| }
| ```
| 
| ### Root List Changes
| 
| When roots change, clients that support `listChanged` **MUST** send a notification:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "method": "notifications/roots/list_changed"
| }
| ```
| 
| ## Message Flow
| 
| ```mermaid
| sequenceDiagram
|     participant Server
|     participant Client
| 
|     Note over Server,Client: Discovery
|     Server->>Client: roots/list
|     Client-->>Server: Available roots
| 
|     Note over Server,Client: Changes
|     Client--)Server: notifications/roots/list_changed
|     Server->>Client: roots/list
|     Client-->>Server: Updated roots
| ```
| 
| ## Data Types
| 
| ### Root
| 
| A root definition includes:
| 
| - `uri`: Unique identifier for the root. This **MUST** be a `file://` URI in the current
|   specification.
| - `name`: Optional human-readable name for display purposes.
| 
| Example roots for different use cases:
| 
| #### Project Directory
| 
| ```json
| {
|   "uri": "file:///home/user/projects/myproject",
|   "name": "My Project"
| }
| ```
| 
| #### Multiple Repositories
| 
| ```json
| [
|   {
|     "uri": "file:///home/user/repos/frontend",
|     "name": "Frontend Repository"
|   },
|   {
|     "uri": "file:///home/user/repos/backend",
|     "name": "Backend Repository"
|   }
| ]
| ```
| 
| ## Error Handling
| 
| Clients **SHOULD** return standard JSON-RPC errors for common failure cases:
| 
| - Client does not support roots: `-32601` (Method not found)
| - Internal errors: `-32603`
| 
| Example error:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "error": {
|     "code": -32601,
|     "message": "Roots not supported",
|     "data": {
|       "reason": "Client does not have roots capability"
|     }
|   }
| }
| ```
| 
| ## Security Considerations
| 
| 1. Clients **MUST**:
| 
|    - Only expose roots with appropriate permissions
|    - Validate all root URIs to prevent path traversal
|    - Implement proper access controls
|    - Monitor root accessibility
| 
| 2. Servers **SHOULD**:
|    - Handle cases where roots become unavailable
|    - Respect root boundaries during operations
|    - Validate all paths against provided roots
| 
| ## Implementation Guidelines
| 
| 1. Clients **SHOULD**:
| 
|    - Prompt users for consent before exposing roots to servers
|    - Provide clear user interfaces for root management
|    - Validate root accessibility before exposing
|    - Monitor for root changes
| 
| 2. Servers **SHOULD**:
|    - Check for roots capability before usage
|    - Handle root list changes gracefully
|    - Respect root boundaries in operations
|    - Cache root information appropriately
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/client/sampling.md:
--------------------------------------------------------------------------------
| ---
| title: Sampling
| type: docs
| weight: 40
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| The Model Context Protocol (MCP) provides a standardized way for servers to request LLM
| sampling ("completions" or "generations") from language models via clients. This flow
| allows clients to maintain control over model access, selection, and permissions while
| enabling servers to leverage AI capabilities&mdash;with no server API keys necessary.
| Servers can request text or image-based interactions and optionally include context from
| MCP servers in their prompts.
| 
| ## User Interaction Model
| 
| Sampling in MCP allows servers to implement agentic behaviors, by enabling LLM calls to
| occur _nested_ inside other MCP server features.
| 
| Implementations are free to expose sampling through any interface pattern that suits
| their needs&mdash;the protocol itself does not mandate any specific user interaction
| model.
| 
| {{< callout type="warning" >}} For trust & safety and security, there **SHOULD** always
| be a human in the loop with the ability to deny sampling requests.
| 
| Applications **SHOULD**:
| 
| - Provide UI that makes it easy and intuitive to review sampling requests
| - Allow users to view and edit prompts before sending
| - Present generated responses for review before delivery {{< /callout >}}
| 
| ## Capabilities
| 
| Clients that support sampling **MUST** declare the `sampling` capability during
| [initialization]({{< ref "/specification/2024-11-05/basic/lifecycle#initialization" >}}):
| 
| ```json
| {
|   "capabilities": {
|     "sampling": {}
|   }
| }
| ```
| 
| ## Protocol Messages
| 
| ### Creating Messages
| 
| To request a language model generation, servers send a `sampling/createMessage` request:
| 
| **Request:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "method": "sampling/createMessage",
|   "params": {
|     "messages": [
|       {
|         "role": "user",
|         "content": {
|           "type": "text",
|           "text": "What is the capital of France?"
|         }
|       }
|     ],
|     "modelPreferences": {
|       "hints": [
|         {
|           "name": "claude-3-sonnet"
|         }
|       ],
|       "intelligencePriority": 0.8,
|       "speedPriority": 0.5
|     },
|     "systemPrompt": "You are a helpful assistant.",
|     "maxTokens": 100
|   }
| }
| ```
| 
| **Response:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "result": {
|     "role": "assistant",
|     "content": {
|       "type": "text",
|       "text": "The capital of France is Paris."
|     },
|     "model": "claude-3-sonnet-20240307",
|     "stopReason": "endTurn"
|   }
| }
| ```
| 
| ## Message Flow
| 
| ```mermaid
| sequenceDiagram
|     participant Server
|     participant Client
|     participant User
|     participant LLM
| 
|     Note over Server,Client: Server initiates sampling
|     Server->>Client: sampling/createMessage
| 
|     Note over Client,User: Human-in-the-loop review
|     Client->>User: Present request for approval
|     User-->>Client: Review and approve/modify
| 
|     Note over Client,LLM: Model interaction
|     Client->>LLM: Forward approved request
|     LLM-->>Client: Return generation
| 
|     Note over Client,User: Response review
|     Client->>User: Present response for approval
|     User-->>Client: Review and approve/modify
| 
|     Note over Server,Client: Complete request
|     Client-->>Server: Return approved response
| ```
| 
| ## Data Types
| 
| ### Messages
| 
| Sampling messages can contain:
| 
| #### Text Content
| 
| ```json
| {
|   "type": "text",
|   "text": "The message content"
| }
| ```
| 
| #### Image Content
| 
| ```json
| {
|   "type": "image",
|   "data": "base64-encoded-image-data",
|   "mimeType": "image/jpeg"
| }
| ```
| 
| ### Model Preferences
| 
| Model selection in MCP requires careful abstraction since servers and clients may use
| different AI providers with distinct model offerings. A server cannot simply request a
| specific model by name since the client may not have access to that exact model or may
| prefer to use a different provider's equivalent model.
| 
| To solve this, MCP implements a preference system that combines abstract capability
| priorities with optional model hints:
| 
| #### Capability Priorities
| 
| Servers express their needs through three normalized priority values (0-1):
| 
| - `costPriority`: How important is minimizing costs? Higher values prefer cheaper models.
| - `speedPriority`: How important is low latency? Higher values prefer faster models.
| - `intelligencePriority`: How important are advanced capabilities? Higher values prefer
|   more capable models.
| 
| #### Model Hints
| 
| While priorities help select models based on characteristics, `hints` allow servers to
| suggest specific models or model families:
| 
| - Hints are treated as substrings that can match model names flexibly
| - Multiple hints are evaluated in order of preference
| - Clients **MAY** map hints to equivalent models from different providers
| - Hints are advisory&mdash;clients make final model selection
| 
| For example:
| 
| ```json
| {
|   "hints": [
|     { "name": "claude-3-sonnet" }, // Prefer Sonnet-class models
|     { "name": "claude" } // Fall back to any Claude model
|   ],
|   "costPriority": 0.3, // Cost is less important
|   "speedPriority": 0.8, // Speed is very important
|   "intelligencePriority": 0.5 // Moderate capability needs
| }
| ```
| 
| The client processes these preferences to select an appropriate model from its available
| options. For instance, if the client doesn't have access to Claude models but has Gemini,
| it might map the sonnet hint to `gemini-1.5-pro` based on similar capabilities.
| 
| ## Error Handling
| 
| Clients **SHOULD** return errors for common failure cases:
| 
| Example error:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "error": {
|     "code": -1,
|     "message": "User rejected sampling request"
|   }
| }
| ```
| 
| ## Security Considerations
| 
| 1. Clients **SHOULD** implement user approval controls
| 2. Both parties **SHOULD** validate message content
| 3. Clients **SHOULD** respect model preference hints
| 4. Clients **SHOULD** implement rate limiting
| 5. Both parties **MUST** handle sensitive data appropriately
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/server/_index.md:
--------------------------------------------------------------------------------
| ---
| title: Server Features
| cascade:
|   type: docs
| weight: 3
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| Servers provide the fundamental building blocks for adding context to language models via
| MCP. These primitives enable rich interactions between clients, servers, and language
| models:
| 
| - **Prompts**: Pre-defined templates or instructions that guide language model
|   interactions
| - **Resources**: Structured data or content that provides additional context to the model
| - **Tools**: Executable functions that allow models to perform actions or retrieve
|   information
| 
| Each primitive can be summarized in the following control hierarchy:
| 
| | Primitive | Control                | Description                                        | Example                         |
| | --------- | ---------------------- | -------------------------------------------------- | ------------------------------- |
| | Prompts   | User-controlled        | Interactive templates invoked by user choice       | Slash commands, menu options    |
| | Resources | Application-controlled | Contextual data attached and managed by the client | File contents, git history      |
| | Tools     | Model-controlled       | Functions exposed to the LLM to take actions       | API POST requests, file writing |
| 
| Explore these key primitives in more detail below:
| 
| {{< cards >}} {{< card link="prompts" title="Prompts" icon="chat-alt-2" >}}
| {{< card link="resources" title="Resources" icon="document" >}}
| {{< card link="tools" title="Tools" icon="adjustments" >}} {{< /cards >}}
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/server/prompts.md:
--------------------------------------------------------------------------------
| ---
| title: Prompts
| weight: 10
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| The Model Context Protocol (MCP) provides a standardized way for servers to expose prompt
| templates to clients. Prompts allow servers to provide structured messages and
| instructions for interacting with language models. Clients can discover available
| prompts, retrieve their contents, and provide arguments to customize them.
| 
| ## User Interaction Model
| 
| Prompts are designed to be **user-controlled**, meaning they are exposed from servers to
| clients with the intention of the user being able to explicitly select them for use.
| 
| Typically, prompts would be triggered through user-initiated commands in the user
| interface, which allows users to naturally discover and invoke available prompts.
| 
| For example, as slash commands:
| 
| ![Example of prompt exposed as slash command](slash-command.png)
| 
| However, implementors are free to expose prompts through any interface pattern that suits
| their needs&mdash;the protocol itself does not mandate any specific user interaction
| model.
| 
| ## Capabilities
| 
| Servers that support prompts **MUST** declare the `prompts` capability during
| [initialization]({{< ref "/specification/2024-11-05/basic/lifecycle#initialization" >}}):
| 
| ```json
| {
|   "capabilities": {
|     "prompts": {
|       "listChanged": true
|     }
|   }
| }
| ```
| 
| `listChanged` indicates whether the server will emit notifications when the list of
| available prompts changes.
| 
| ## Protocol Messages
| 
| ### Listing Prompts
| 
| To retrieve available prompts, clients send a `prompts/list` request. This operation
| supports
| [pagination]({{< ref "/specification/2024-11-05/server/utilities/pagination" >}}).
| 
| **Request:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "method": "prompts/list",
|   "params": {
|     "cursor": "optional-cursor-value"
|   }
| }
| ```
| 
| **Response:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "result": {
|     "prompts": [
|       {
|         "name": "code_review",
|         "description": "Asks the LLM to analyze code quality and suggest improvements",
|         "arguments": [
|           {
|             "name": "code",
|             "description": "The code to review",
|             "required": true
|           }
|         ]
|       }
|     ],
|     "nextCursor": "next-page-cursor"
|   }
| }
| ```
| 
| ### Getting a Prompt
| 
| To retrieve a specific prompt, clients send a `prompts/get` request. Arguments may be
| auto-completed through [the completion
| API]({{< ref "/specification/2024-11-05/server/utilities/completion" >}}).
| 
| **Request:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 2,
|   "method": "prompts/get",
|   "params": {
|     "name": "code_review",
|     "arguments": {
|       "code": "def hello():\n    print('world')"
|     }
|   }
| }
| ```
| 
| **Response:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 2,
|   "result": {
|     "description": "Code review prompt",
|     "messages": [
|       {
|         "role": "user",
|         "content": {
|           "type": "text",
|           "text": "Please review this Python code:\ndef hello():\n    print('world')"
|         }
|       }
|     ]
|   }
| }
| ```
| 
| ### List Changed Notification
| 
| When the list of available prompts changes, servers that declared the `listChanged`
| capability **SHOULD** send a notification:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "method": "notifications/prompts/list_changed"
| }
| ```
| 
| ## Message Flow
| 
| ```mermaid
| sequenceDiagram
|     participant Client
|     participant Server
| 
|     Note over Client,Server: Discovery
|     Client->>Server: prompts/list
|     Server-->>Client: List of prompts
| 
|     Note over Client,Server: Usage
|     Client->>Server: prompts/get
|     Server-->>Client: Prompt content
| 
|     opt listChanged
|       Note over Client,Server: Changes
|       Server--)Client: prompts/list_changed
|       Client->>Server: prompts/list
|       Server-->>Client: Updated prompts
|     end
| ```
| 
| ## Data Types
| 
| ### Prompt
| 
| A prompt definition includes:
| 
| - `name`: Unique identifier for the prompt
| - `description`: Optional human-readable description
| - `arguments`: Optional list of arguments for customization
| 
| ### PromptMessage
| 
| Messages in a prompt can contain:
| 
| - `role`: Either "user" or "assistant" to indicate the speaker
| - `content`: One of the following content types:
| 
| #### Text Content
| 
| Text content represents plain text messages:
| 
| ```json
| {
|   "type": "text",
|   "text": "The text content of the message"
| }
| ```
| 
| This is the most common content type used for natural language interactions.
| 
| #### Image Content
| 
| Image content allows including visual information in messages:
| 
| ```json
| {
|   "type": "image",
|   "data": "base64-encoded-image-data",
|   "mimeType": "image/png"
| }
| ```
| 
| The image data **MUST** be base64-encoded and include a valid MIME type. This enables
| multi-modal interactions where visual context is important.
| 
| #### Embedded Resources
| 
| Embedded resources allow referencing server-side resources directly in messages:
| 
| ```json
| {
|   "type": "resource",
|   "resource": {
|     "uri": "resource://example",
|     "mimeType": "text/plain",
|     "text": "Resource content"
|   }
| }
| ```
| 
| Resources can contain either text or binary (blob) data and **MUST** include:
| 
| - A valid resource URI
| - The appropriate MIME type
| - Either text content or base64-encoded blob data
| 
| Embedded resources enable prompts to seamlessly incorporate server-managed content like
| documentation, code samples, or other reference materials directly into the conversation
| flow.
| 
| ## Error Handling
| 
| Servers **SHOULD** return standard JSON-RPC errors for common failure cases:
| 
| - Invalid prompt name: `-32602` (Invalid params)
| - Missing required arguments: `-32602` (Invalid params)
| - Internal errors: `-32603` (Internal error)
| 
| ## Implementation Considerations
| 
| 1. Servers **SHOULD** validate prompt arguments before processing
| 2. Clients **SHOULD** handle pagination for large prompt lists
| 3. Both parties **SHOULD** respect capability negotiation
| 
| ## Security
| 
| Implementations **MUST** carefully validate all prompt inputs and outputs to prevent
| injection attacks or unauthorized access to resources.
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/server/resource-picker.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelcontextprotocol/specification/main/docs/specification/2024-11-05/server/resource-picker.png


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/server/resources.md:
--------------------------------------------------------------------------------
| ---
| title: Resources
| type: docs
| weight: 20
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| The Model Context Protocol (MCP) provides a standardized way for servers to expose
| resources to clients. Resources allow servers to share data that provides context to
| language models, such as files, database schemas, or application-specific information.
| Each resource is uniquely identified by a
| [URI](https://datatracker.ietf.org/doc/html/rfc3986).
| 
| ## User Interaction Model
| 
| Resources in MCP are designed to be **application-driven**, with host applications
| determining how to incorporate context based on their needs.
| 
| For example, applications could:
| 
| - Expose resources through UI elements for explicit selection, in a tree or list view
| - Allow the user to search through and filter available resources
| - Implement automatic context inclusion, based on heuristics or the AI model's selection
| 
| ![Example of resource context picker](resource-picker.png)
| 
| However, implementations are free to expose resources through any interface pattern that
| suits their needs&mdash;the protocol itself does not mandate any specific user
| interaction model.
| 
| ## Capabilities
| 
| Servers that support resources **MUST** declare the `resources` capability:
| 
| ```json
| {
|   "capabilities": {
|     "resources": {
|       "subscribe": true,
|       "listChanged": true
|     }
|   }
| }
| ```
| 
| The capability supports two optional features:
| 
| - `subscribe`: whether the client can subscribe to be notified of changes to individual
|   resources.
| - `listChanged`: whether the server will emit notifications when the list of available
|   resources changes.
| 
| Both `subscribe` and `listChanged` are optional&mdash;servers can support neither,
| either, or both:
| 
| ```json
| {
|   "capabilities": {
|     "resources": {} // Neither feature supported
|   }
| }
| ```
| 
| ```json
| {
|   "capabilities": {
|     "resources": {
|       "subscribe": true // Only subscriptions supported
|     }
|   }
| }
| ```
| 
| ```json
| {
|   "capabilities": {
|     "resources": {
|       "listChanged": true // Only list change notifications supported
|     }
|   }
| }
| ```
| 
| ## Protocol Messages
| 
| ### Listing Resources
| 
| To discover available resources, clients send a `resources/list` request. This operation
| supports
| [pagination]({{< ref "/specification/2024-11-05/server/utilities/pagination" >}}).
| 
| **Request:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "method": "resources/list",
|   "params": {
|     "cursor": "optional-cursor-value"
|   }
| }
| ```
| 
| **Response:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "result": {
|     "resources": [
|       {
|         "uri": "file:///project/src/main.rs",
|         "name": "main.rs",
|         "description": "Primary application entry point",
|         "mimeType": "text/x-rust"
|       }
|     ],
|     "nextCursor": "next-page-cursor"
|   }
| }
| ```
| 
| ### Reading Resources
| 
| To retrieve resource contents, clients send a `resources/read` request:
| 
| **Request:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 2,
|   "method": "resources/read",
|   "params": {
|     "uri": "file:///project/src/main.rs"
|   }
| }
| ```
| 
| **Response:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 2,
|   "result": {
|     "contents": [
|       {
|         "uri": "file:///project/src/main.rs",
|         "mimeType": "text/x-rust",
|         "text": "fn main() {\n    println!(\"Hello world!\");\n}"
|       }
|     ]
|   }
| }
| ```
| 
| ### Resource Templates
| 
| Resource templates allow servers to expose parameterized resources using
| [URI templates](https://datatracker.ietf.org/doc/html/rfc6570). Arguments may be
| auto-completed through [the completion
| API]({{< ref "/specification/2024-11-05/server/utilities/completion" >}}).
| 
| **Request:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 3,
|   "method": "resources/templates/list"
| }
| ```
| 
| **Response:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 3,
|   "result": {
|     "resourceTemplates": [
|       {
|         "uriTemplate": "file:///{path}",
|         "name": "Project Files",
|         "description": "Access files in the project directory",
|         "mimeType": "application/octet-stream"
|       }
|     ]
|   }
| }
| ```
| 
| ### List Changed Notification
| 
| When the list of available resources changes, servers that declared the `listChanged`
| capability **SHOULD** send a notification:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "method": "notifications/resources/list_changed"
| }
| ```
| 
| ### Subscriptions
| 
| The protocol supports optional subscriptions to resource changes. Clients can subscribe
| to specific resources and receive notifications when they change:
| 
| **Subscribe Request:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 4,
|   "method": "resources/subscribe",
|   "params": {
|     "uri": "file:///project/src/main.rs"
|   }
| }
| ```
| 
| **Update Notification:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "method": "notifications/resources/updated",
|   "params": {
|     "uri": "file:///project/src/main.rs"
|   }
| }
| ```
| 
| ## Message Flow
| 
| ```mermaid
| sequenceDiagram
|     participant Client
|     participant Server
| 
|     Note over Client,Server: Resource Discovery
|     Client->>Server: resources/list
|     Server-->>Client: List of resources
| 
|     Note over Client,Server: Resource Access
|     Client->>Server: resources/read
|     Server-->>Client: Resource contents
| 
|     Note over Client,Server: Subscriptions
|     Client->>Server: resources/subscribe
|     Server-->>Client: Subscription confirmed
| 
|     Note over Client,Server: Updates
|     Server--)Client: notifications/resources/updated
|     Client->>Server: resources/read
|     Server-->>Client: Updated contents
| ```
| 
| ## Data Types
| 
| ### Resource
| 
| A resource definition includes:
| 
| - `uri`: Unique identifier for the resource
| - `name`: Human-readable name
| - `description`: Optional description
| - `mimeType`: Optional MIME type
| 
| ### Resource Contents
| 
| Resources can contain either text or binary data:
| 
| #### Text Content
| 
| ```json
| {
|   "uri": "file:///example.txt",
|   "mimeType": "text/plain",
|   "text": "Resource content"
| }
| ```
| 
| #### Binary Content
| 
| ```json
| {
|   "uri": "file:///example.png",
|   "mimeType": "image/png",
|   "blob": "base64-encoded-data"
| }
| ```
| 
| ## Common URI Schemes
| 
| The protocol defines several standard URI schemes. This list not
| exhaustive&mdash;implementations are always free to use additional, custom URI schemes.
| 
| ### https://
| 
| Used to represent a resource available on the web.
| 
| Servers **SHOULD** use this scheme only when the client is able to fetch and load the
| resource directly from the web on its own—that is, it doesn’t need to read the resource
| via the MCP server.
| 
| For other use cases, servers **SHOULD** prefer to use another URI scheme, or define a
| custom one, even if the server will itself be downloading resource contents over the
| internet.
| 
| ### file://
| 
| Used to identify resources that behave like a filesystem. However, the resources do not
| need to map to an actual physical filesystem.
| 
| MCP servers **MAY** identify file:// resources with an
| [XDG MIME type](https://specifications.freedesktop.org/shared-mime-info-spec/0.14/ar01s02.html#id-1.3.14),
| like `inode/directory`, to represent non-regular files (such as directories) that don’t
| otherwise have a standard MIME type.
| 
| ### git://
| 
| Git version control integration.
| 
| ## Error Handling
| 
| Servers **SHOULD** return standard JSON-RPC errors for common failure cases:
| 
| - Resource not found: `-32002`
| - Internal errors: `-32603`
| 
| Example error:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 5,
|   "error": {
|     "code": -32002,
|     "message": "Resource not found",
|     "data": {
|       "uri": "file:///nonexistent.txt"
|     }
|   }
| }
| ```
| 
| ## Security Considerations
| 
| 1. Servers **MUST** validate all resource URIs
| 2. Access controls **SHOULD** be implemented for sensitive resources
| 3. Binary data **MUST** be properly encoded
| 4. Resource permissions **SHOULD** be checked before operations
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/server/slash-command.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelcontextprotocol/specification/main/docs/specification/2024-11-05/server/slash-command.png


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/server/tools.md:
--------------------------------------------------------------------------------
| ---
| title: Tools
| type: docs
| weight: 40
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| The Model Context Protocol (MCP) allows servers to expose tools that can be invoked by
| language models. Tools enable models to interact with external systems, such as querying
| databases, calling APIs, or performing computations. Each tool is uniquely identified by
| a name and includes metadata describing its schema.
| 
| ## User Interaction Model
| 
| Tools in MCP are designed to be **model-controlled**, meaning that the language model can
| discover and invoke tools automatically based on its contextual understanding and the
| user's prompts.
| 
| However, implementations are free to expose tools through any interface pattern that
| suits their needs&mdash;the protocol itself does not mandate any specific user
| interaction model.
| 
| {{< callout type="warning" >}} For trust & safety and security, there **SHOULD** always
| be a human in the loop with the ability to deny tool invocations.
| 
| Applications **SHOULD**:
| 
| - Provide UI that makes clear which tools are being exposed to the AI model
| - Insert clear visual indicators when tools are invoked
| - Present confirmation prompts to the user for operations, to ensure a human is in the
|   loop {{< /callout >}}
| 
| ## Capabilities
| 
| Servers that support tools **MUST** declare the `tools` capability:
| 
| ```json
| {
|   "capabilities": {
|     "tools": {
|       "listChanged": true
|     }
|   }
| }
| ```
| 
| `listChanged` indicates whether the server will emit notifications when the list of
| available tools changes.
| 
| ## Protocol Messages
| 
| ### Listing Tools
| 
| To discover available tools, clients send a `tools/list` request. This operation supports
| [pagination]({{< ref "/specification/2024-11-05/server/utilities/pagination" >}}).
| 
| **Request:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "method": "tools/list",
|   "params": {
|     "cursor": "optional-cursor-value"
|   }
| }
| ```
| 
| **Response:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "result": {
|     "tools": [
|       {
|         "name": "get_weather",
|         "description": "Get current weather information for a location",
|         "inputSchema": {
|           "type": "object",
|           "properties": {
|             "location": {
|               "type": "string",
|               "description": "City name or zip code"
|             }
|           },
|           "required": ["location"]
|         }
|       }
|     ],
|     "nextCursor": "next-page-cursor"
|   }
| }
| ```
| 
| ### Calling Tools
| 
| To invoke a tool, clients send a `tools/call` request:
| 
| **Request:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 2,
|   "method": "tools/call",
|   "params": {
|     "name": "get_weather",
|     "arguments": {
|       "location": "New York"
|     }
|   }
| }
| ```
| 
| **Response:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 2,
|   "result": {
|     "content": [
|       {
|         "type": "text",
|         "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
|       }
|     ],
|     "isError": false
|   }
| }
| ```
| 
| ### List Changed Notification
| 
| When the list of available tools changes, servers that declared the `listChanged`
| capability **SHOULD** send a notification:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "method": "notifications/tools/list_changed"
| }
| ```
| 
| ## Message Flow
| 
| ```mermaid
| sequenceDiagram
|     participant LLM
|     participant Client
|     participant Server
| 
|     Note over Client,Server: Discovery
|     Client->>Server: tools/list
|     Server-->>Client: List of tools
| 
|     Note over Client,LLM: Tool Selection
|     LLM->>Client: Select tool to use
| 
|     Note over Client,Server: Invocation
|     Client->>Server: tools/call
|     Server-->>Client: Tool result
|     Client->>LLM: Process result
| 
|     Note over Client,Server: Updates
|     Server--)Client: tools/list_changed
|     Client->>Server: tools/list
|     Server-->>Client: Updated tools
| ```
| 
| ## Data Types
| 
| ### Tool
| 
| A tool definition includes:
| 
| - `name`: Unique identifier for the tool
| - `description`: Human-readable description of functionality
| - `inputSchema`: JSON Schema defining expected parameters
| 
| ### Tool Result
| 
| Tool results can contain multiple content items of different types:
| 
| #### Text Content
| 
| ```json
| {
|   "type": "text",
|   "text": "Tool result text"
| }
| ```
| 
| #### Image Content
| 
| ```json
| {
|   "type": "image",
|   "data": "base64-encoded-data",
|   "mimeType": "image/png"
| }
| ```
| 
| #### Embedded Resources
| 
| [Resources]({{< ref "/specification/2024-11-05/server/resources" >}}) **MAY** be
| embedded, to provide additional context or data, behind a URI that can be subscribed to
| or fetched again by the client later:
| 
| ```json
| {
|   "type": "resource",
|   "resource": {
|     "uri": "resource://example",
|     "mimeType": "text/plain",
|     "text": "Resource content"
|   }
| }
| ```
| 
| ## Error Handling
| 
| Tools use two error reporting mechanisms:
| 
| 1. **Protocol Errors**: Standard JSON-RPC errors for issues like:
| 
|    - Unknown tools
|    - Invalid arguments
|    - Server errors
| 
| 2. **Tool Execution Errors**: Reported in tool results with `isError: true`:
|    - API failures
|    - Invalid input data
|    - Business logic errors
| 
| Example protocol error:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 3,
|   "error": {
|     "code": -32602,
|     "message": "Unknown tool: invalid_tool_name"
|   }
| }
| ```
| 
| Example tool execution error:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 4,
|   "result": {
|     "content": [
|       {
|         "type": "text",
|         "text": "Failed to fetch weather data: API rate limit exceeded"
|       }
|     ],
|     "isError": true
|   }
| }
| ```
| 
| ## Security Considerations
| 
| 1. Servers **MUST**:
| 
|    - Validate all tool inputs
|    - Implement proper access controls
|    - Rate limit tool invocations
|    - Sanitize tool outputs
| 
| 2. Clients **SHOULD**:
|    - Prompt for user confirmation on sensitive operations
|    - Show tool inputs to the user before calling the server, to avoid malicious or
|      accidental data exfiltration
|    - Validate tool results before passing to LLM
|    - Implement timeouts for tool calls
|    - Log tool usage for audit purposes
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/server/utilities/_index.md:
--------------------------------------------------------------------------------
| ---
| title: Utilities
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| These optional features can be used to enhance server functionality.
| 
| {{< cards >}} {{< card link="completion" title="Completion" icon="at-symbol" >}}
| {{< card link="logging" title="Logging" icon="terminal" >}}
| {{< card link="pagination" title="Pagination" icon="collection" >}} {{< /cards >}}
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/server/utilities/completion.md:
--------------------------------------------------------------------------------
| ---
| title: Completion
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| The Model Context Protocol (MCP) provides a standardized way for servers to offer
| argument autocompletion suggestions for prompts and resource URIs. This enables rich,
| IDE-like experiences where users receive contextual suggestions while entering argument
| values.
| 
| ## User Interaction Model
| 
| Completion in MCP is designed to support interactive user experiences similar to IDE code
| completion.
| 
| For example, applications may show completion suggestions in a dropdown or popup menu as
| users type, with the ability to filter and select from available options.
| 
| However, implementations are free to expose completion through any interface pattern that
| suits their needs&mdash;the protocol itself does not mandate any specific user
| interaction model.
| 
| ## Protocol Messages
| 
| ### Requesting Completions
| 
| To get completion suggestions, clients send a `completion/complete` request specifying
| what is being completed through a reference type:
| 
| **Request:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "method": "completion/complete",
|   "params": {
|     "ref": {
|       "type": "ref/prompt",
|       "name": "code_review"
|     },
|     "argument": {
|       "name": "language",
|       "value": "py"
|     }
|   }
| }
| ```
| 
| **Response:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "result": {
|     "completion": {
|       "values": ["python", "pytorch", "pyside"],
|       "total": 10,
|       "hasMore": true
|     }
|   }
| }
| ```
| 
| ### Reference Types
| 
| The protocol supports two types of completion references:
| 
| | Type           | Description                 | Example                                             |
| | -------------- | --------------------------- | --------------------------------------------------- |
| | `ref/prompt`   | References a prompt by name | `{"type": "ref/prompt", "name": "code_review"}`     |
| | `ref/resource` | References a resource URI   | `{"type": "ref/resource", "uri": "file:///{path}"}` |
| 
| ### Completion Results
| 
| Servers return an array of completion values ranked by relevance, with:
| 
| - Maximum 100 items per response
| - Optional total number of available matches
| - Boolean indicating if additional results exist
| 
| ## Message Flow
| 
| ```mermaid
| sequenceDiagram
|     participant Client
|     participant Server
| 
|     Note over Client: User types argument
|     Client->>Server: completion/complete
|     Server-->>Client: Completion suggestions
| 
|     Note over Client: User continues typing
|     Client->>Server: completion/complete
|     Server-->>Client: Refined suggestions
| ```
| 
| ## Data Types
| 
| ### CompleteRequest
| 
| - `ref`: A `PromptReference` or `ResourceReference`
| - `argument`: Object containing:
|   - `name`: Argument name
|   - `value`: Current value
| 
| ### CompleteResult
| 
| - `completion`: Object containing:
|   - `values`: Array of suggestions (max 100)
|   - `total`: Optional total matches
|   - `hasMore`: Additional results flag
| 
| ## Implementation Considerations
| 
| 1. Servers **SHOULD**:
| 
|    - Return suggestions sorted by relevance
|    - Implement fuzzy matching where appropriate
|    - Rate limit completion requests
|    - Validate all inputs
| 
| 2. Clients **SHOULD**:
|    - Debounce rapid completion requests
|    - Cache completion results where appropriate
|    - Handle missing or partial results gracefully
| 
| ## Security
| 
| Implementations **MUST**:
| 
| - Validate all completion inputs
| - Implement appropriate rate limiting
| - Control access to sensitive suggestions
| - Prevent completion-based information disclosure
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/server/utilities/logging.md:
--------------------------------------------------------------------------------
| ---
| title: Logging
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| The Model Context Protocol (MCP) provides a standardized way for servers to send
| structured log messages to clients. Clients can control logging verbosity by setting
| minimum log levels, with servers sending notifications containing severity levels,
| optional logger names, and arbitrary JSON-serializable data.
| 
| ## User Interaction Model
| 
| Implementations are free to expose logging through any interface pattern that suits their
| needs&mdash;the protocol itself does not mandate any specific user interaction model.
| 
| ## Capabilities
| 
| Servers that emit log message notifications **MUST** declare the `logging` capability:
| 
| ```json
| {
|   "capabilities": {
|     "logging": {}
|   }
| }
| ```
| 
| ## Log Levels
| 
| The protocol follows the standard syslog severity levels specified in
| [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1):
| 
| | Level     | Description                      | Example Use Case           |
| | --------- | -------------------------------- | -------------------------- |
| | debug     | Detailed debugging information   | Function entry/exit points |
| | info      | General informational messages   | Operation progress updates |
| | notice    | Normal but significant events    | Configuration changes      |
| | warning   | Warning conditions               | Deprecated feature usage   |
| | error     | Error conditions                 | Operation failures         |
| | critical  | Critical conditions              | System component failures  |
| | alert     | Action must be taken immediately | Data corruption detected   |
| | emergency | System is unusable               | Complete system failure    |
| 
| ## Protocol Messages
| 
| ### Setting Log Level
| 
| To configure the minimum log level, clients **MAY** send a `logging/setLevel` request:
| 
| **Request:**
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": 1,
|   "method": "logging/setLevel",
|   "params": {
|     "level": "info"
|   }
| }
| ```
| 
| ### Log Message Notifications
| 
| Servers send log messages using `notifications/message` notifications:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "method": "notifications/message",
|   "params": {
|     "level": "error",
|     "logger": "database",
|     "data": {
|       "error": "Connection failed",
|       "details": {
|         "host": "localhost",
|         "port": 5432
|       }
|     }
|   }
| }
| ```
| 
| ## Message Flow
| 
| ```mermaid
| sequenceDiagram
|     participant Client
|     participant Server
| 
|     Note over Client,Server: Configure Logging
|     Client->>Server: logging/setLevel (info)
|     Server-->>Client: Empty Result
| 
|     Note over Client,Server: Server Activity
|     Server--)Client: notifications/message (info)
|     Server--)Client: notifications/message (warning)
|     Server--)Client: notifications/message (error)
| 
|     Note over Client,Server: Level Change
|     Client->>Server: logging/setLevel (error)
|     Server-->>Client: Empty Result
|     Note over Server: Only sends error level<br/>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
| 


--------------------------------------------------------------------------------
/docs/specification/2024-11-05/server/utilities/pagination.md:
--------------------------------------------------------------------------------
| ---
| title: Pagination
| ---
| 
| {{< callout type="info" >}} **Protocol Revision**: 2024-11-05 {{< /callout >}}
| 
| The Model Context Protocol (MCP) supports paginating list operations that may return
| large result sets. Pagination allows servers to yield results in smaller chunks rather
| than all at once.
| 
| Pagination is especially important when connecting to external services over the
| internet, but also useful for local integrations to avoid performance issues with large
| data sets.
| 
| ## Pagination Model
| 
| Pagination in MCP uses an opaque cursor-based approach, instead of numbered pages.
| 
| - The **cursor** is an opaque string token, representing a position in the result set
| - **Page size** is determined by the server, and **MAY NOT** be fixed
| 
| ## Response Format
| 
| Pagination starts when the server sends a **response** that includes:
| 
| - The current page of results
| - An optional `nextCursor` field if more results exist
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "id": "123",
|   "result": {
|     "resources": [...],
|     "nextCursor": "eyJwYWdlIjogM30="
|   }
| }
| ```
| 
| ## Request Format
| 
| After receiving a cursor, the client can _continue_ paginating by issuing a request
| including that cursor:
| 
| ```json
| {
|   "jsonrpc": "2.0",
|   "method": "resources/list",
|   "params": {
|     "cursor": "eyJwYWdlIjogMn0="
|   }
| }
| ```
| 
| ## Pagination Flow
| 
| ```mermaid
| sequenceDiagram
|     participant Client
|     participant Server
| 
|     Client->>Server: List Request (no cursor)
|     loop Pagination Loop
|       Server-->>Client: Page of results + nextCursor
|       Client->>Server: List Request (with cursor)
|     end
| ```
| 
| ## Operations Supporting Pagination
| 
| The following MCP operations support pagination:
| 
| - `resources/list` - List available resources
| - `resources/templates/list` - List resource templates
| - `prompts/list` - List available prompts
| - `tools/list` - List available tools
| 
| ## Implementation Guidelines
| 
| 1. Servers **SHOULD**:
| 
|    - Provide stable cursors
|    - Handle invalid cursors gracefully
| 
| 2. Clients **SHOULD**:
| 
|    - Treat a missing `nextCursor` as the end of results
|    - Support both paginated and non-paginated flows
| 
| 3. Clients **MUST** treat cursors as opaque tokens:
|    - Don't make assumptions about cursor format
|    - Don't attempt to parse or modify cursors
|    - Don't persist cursors across sessions
| 
| ## Error Handling
| 
| Invalid cursors **SHOULD** result in an error with code -32602 (Invalid params).
| 


--------------------------------------------------------------------------------