Skip to content

Commit

Permalink
Merge pull request #60 from modelcontextprotocol/justin/spec-updates
Browse files Browse the repository at this point in the history 
Justin's updates
  • Loading branch information
@jspahrsummers
jspahrsummers authored Nov 22, 2024
2 parents 14bf4b0 + 5eb7663 commit 231bf61
Show file tree
Hide file tree
Showing 27 changed files with 669 additions and 607 deletions.
89 changes: 70 additions & 19 deletions docs/specification/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,14 @@ weight: 10
---

{{< callout type="info" >}}
**Protocol Revision**: 2024-11-05
**Protocol Revision**: {{< param protocolRevision >}}
{{< /callout >}}

The Model Context Protocol (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/schema.ts). For implementation guides and examples, visit [modelcontextprotocol.io](https://modelcontextprotocol.io).
[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/schema.ts).

For implementation guides and examples, visit [modelcontextprotocol.io](https://modelcontextprotocol.io).

## Overview

Expand All @@ -20,32 +24,79 @@ MCP provides a standardized way for applications to:
- Expose tools and capabilities to AI systems
- Build composable integrations and workflows

The protocol uses JSON-RPC 2.0 messages to establish communication between:
The protocol uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 messages to establish communication between:

- **Clients**: Applications that integrate with language models
- **Hosts**: LLM applications that initiate connections
- **Clients**: Connectors within the host application
- **Servers**: Services that provide context and capabilities
- **Hosts**: Processes that manage client connections

## Core Protocol Features
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.

MCP defines several key components:
## Key Details

### Base Protocol
- JSON-RPC message format
- Capability negotiation
- Session lifecycle management
- [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

### Context Primitives
- **Resources**: Data exposed via URIs
- **Prompts**: Template-based interactions
- **Tools**: Executable functions
- **Sampling**: LLM generation control
Clients may offer the following feature to servers:

### Cross-Cutting Concerns
- **Sampling**: Server-initiated agentic behaviors and recursive LLM interactions

### Additional Utilities

- Configuration
- Progress tracking
- Error handling
- Security boundaries
- Backwards compatibility
- 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

Expand Down
103 changes: 48 additions & 55 deletions docs/specification/architecture/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ The Model Context Protocol (MCP) follows a client-host-server architecture where
## Core Components

```mermaid
graph TB
graph LR
subgraph "Application Host Process"
H[Host]
C1[Client 1]
Expand All @@ -20,21 +20,26 @@ graph TB
H --> C2
H --> C3
end
S1[Server 1<br>Files & Git]
S2[Server 2<br>Database]
S3[Server 3<br>External APIs]
R1[("Local<br>Resource A")]
R2[("Local<br>Resource B")]
R3[("Local<br>Resource C")]
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
C3 --> S3
C1 --> S1
C2 --> S2
S1 <--> R1
S2 <--> R2
end
subgraph "Internet"
S3[Server 3<br>External APIs]
R3[("Remote<br>Resource C")]
S1 <--> R1
S2 <--> R2
S3 <--> R3
C3 --> S3
S3 <--> R3
end
```

### Host
Expand Down Expand Up @@ -62,76 +67,64 @@ Servers provide specialized context and capabilities:
- Must respect security constraints
- Can be local processes or remote services

## Protocol Capabilities and Flow
## 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 protocol extensions
- 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: Negotiate supported capabilities
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
alt Server Request (if sampling capable)
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
else Client Request (based on server caps)
Client->>Server: Request (tools/resources)
Server-->>Client: Response
else Notifications (if supported)
end
loop Notifications
Server--)Client: Resource updates
Client--)Server: Status changes
end
Host->>Client: Terminate
Client->>Server: End session
Client->>-Server: End session
deactivate Server
```

Each capability unlocks specific protocol features for use during the session. For example:
- Resource subscriptions require the server to declare subscription support
- Implemented [server features]({{< ref "/specification/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 requires the client to declare sampling support
- [Sampling]({{< ref "/specification/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.

### 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**: 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.

## Protocol Features

### Server Features
Servers implement several foundational features that provide context and capabilities to clients:

- **Resources**: Structured data or content exposed via URIs that can be read and optionally subscribed to for updates
- **Prompts**: Pre-defined templates or instructions that guide language model interactions
- **Tools**: Executable functions that allow models to perform actions or retrieve information
- **Utilities**: Helper features for logging, argument completion, and other ancillary functions

The server features focus on exposing data and functionality in a controlled way while maintaining security boundaries.

### Client Features
Clients provide core features for interacting with servers and coordinating with hosts:

- **Sampling**: Ability to request and control language model interactions
- **Root Directory Access**: Controlled exposure of filesystem locations to servers

The client features emphasize safe integration of server capabilities while protecting user privacy and security.
54 changes: 30 additions & 24 deletions docs/specification/basic/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,47 +5,53 @@ cascade:
weight: 2
---

The Model Context Protocol (MCP) defines a set of JSON-RPC methods for communication between clients and servers in AI-assisted applications. MCP uses [JSON-RPC 2.0](https://www.jsonrpc.org/specification) as its base protocol.
{{< callout type="info" >}}
**Protocol Revision**: {{< param protocolRevision >}}
{{< /callout >}}

All messages in MCP **MUST** follow the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines three fundamental types of messages:
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 |
| 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 |

The Model Context Protocol consists of several key components that work together:
**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

**Protocol Layers:**
The Model Context Protocol consists of several key components that work together:

- **Base Protocol**: Core JSON-RPC message types and fundamental operations such as capability exchange
- **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 capabilities
- **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.

### Model Context Protocol specific methods

MCP defines methods based on JSON-RPC that clients and servers implement:
See the following pages for more details on the different components:

{{< cards >}}
{{< card link="lifecycle" title="Lifecycle" icon="refresh" >}}
{{< card link="resources" title="Resources" icon="document" >}}
{{< card link="prompts" title="Prompts" icon="chat-alt-2" >}}
{{< card link="tools" title="Tools" icon="adjustments" >}}
{{< card link="logging" title="Logging" icon="annotation" >}}
{{< card link="sampling" title="Sampling" icon="code" >}}
{{< card link="/specification/basic/lifecycle" title="Lifecycle" icon="refresh" >}}
{{< card link="/specification/server/resources" title="Resources" icon="document" >}}
{{< card link="/specification/server/prompts" title="Prompts" icon="chat-alt-2" >}}
{{< card link="/specification/server/tools" title="Tools" icon="adjustments" >}}
{{< card link="/specification/server/utilities/logging" title="Logging" icon="annotation" >}}
{{< card link="/specification/client/sampling" title="Sampling" icon="code" >}}
{{< /cards >}}

### Authentication
## 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.

Authentication mechanisms are not part of the core MCP specification. Implementations **MAY** provide authentication based on the transport they use.
## Schema

## Specification
The full specification of the protocol is defined as a [TypeScript schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/schema.ts). This is the source of truth for all protocol messages and structures.

The official specification can be found in [TypeScript source](http://github.com/modelcontextprotocol/specification/tree/main/schema/schema.ts) and [JSON Schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/schema.json) formats. The TypeScript version serves as the source of truth, while the JSON Schema version is generated from it.
There is also a [JSON Schema](http://github.com/modelcontextprotocol/specification/tree/main/schema/schema.json), which is automatically generated from the TypeScript source of truth, for use with various automated tooling.
Loading

0 comments on commit 231bf61

Please sign in to comment.