Skip to content

Commit 231bf61

Browse files
jspahrsummersjspahrsummers
authored
Merge pull request modelcontextprotocol#60 from modelcontextprotocol/justin/spec-updates
Justin's updates
2 parents 14bf4b0 + 5eb7663 commit 231bf61

27 files changed

+669
-607
lines changed

‎docs/specification/_index.md

Lines changed: 70 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,14 @@ weight: 10
77
---
88

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

13-
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).
13+
[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.
14+
15+
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).
16+
17+
For implementation guides and examples, visit [modelcontextprotocol.io](https://modelcontextprotocol.io).
1418

1519
## Overview
1620

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

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

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

29-
## Core Protocol Features
33+
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.
3034

31-
MCP defines several key components:
35+
## Key Details
3236

3337
### Base Protocol
34-
- JSON-RPC message format
35-
- Capability negotiation
36-
- Session lifecycle management
38+
- [JSON-RPC](https://www.jsonrpc.org/) message format
39+
- Stateful connections
40+
- Server and client capability negotiation
41+
42+
### Features
43+
44+
Servers offer any of the following features to clients:
45+
46+
- **Resources**: Context and data, for the user or the AI model to use
47+
- **Prompts**: Templated messages and workflows for users
48+
- **Tools**: Functions for the AI model to execute
3749

38-
### Context Primitives
39-
- **Resources**: Data exposed via URIs
40-
- **Prompts**: Template-based interactions
41-
- **Tools**: Executable functions
42-
- **Sampling**: LLM generation control
50+
Clients may offer the following feature to servers:
4351

44-
### Cross-Cutting Concerns
52+
- **Sampling**: Server-initiated agentic behaviors and recursive LLM interactions
53+
54+
### Additional Utilities
55+
56+
- Configuration
4557
- Progress tracking
46-
- Error handling
47-
- Security boundaries
48-
- Backwards compatibility
58+
- Cancellation
59+
- Error reporting
60+
- Logging
61+
62+
## Security and Trust & Safety
63+
64+
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.
65+
66+
### Key Principles
67+
68+
1. **User Consent and Control**
69+
- Users must explicitly consent to and understand all data access and operations
70+
- Users must retain control over what data is shared and what actions are taken
71+
- Implementors should provide clear UIs for reviewing and authorizing activities
72+
73+
2. **Data Privacy**
74+
- Hosts must obtain explicit user consent before exposing user data to servers
75+
- Hosts must not transmit resource data elsewhere without user consent
76+
- User data should be protected with appropriate access controls
77+
78+
3. **Tool Safety**
79+
- Tools represent arbitrary code execution and must be treated with appropriate caution
80+
- Hosts must obtain explicit user consent before invoking any tool
81+
- Users should understand what each tool does before authorizing its use
82+
83+
4. **LLM Sampling Controls**
84+
- Users must explicitly approve any LLM sampling requests
85+
- Users should control:
86+
- Whether sampling occurs at all
87+
- The actual prompt that will be sent
88+
- What results the server can see
89+
- The protocol intentionally limits server visibility into prompts
90+
91+
### Implementation Guidelines
92+
93+
While MCP itself cannot enforce these security principles at the protocol level, implementors **SHOULD**:
94+
95+
1. Build robust consent and authorization flows into their applications
96+
2. Provide clear documentation of security implications
97+
3. Implement appropriate access controls and data protections
98+
4. Follow security best practices in their integrations
99+
5. Consider privacy implications in their feature designs
49100

50101
## Learn More
51102

‎docs/specification/architecture/_index.md

Lines changed: 48 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ The Model Context Protocol (MCP) follows a client-host-server architecture where
1010
## Core Components
1111

1212
```mermaid
13-
graph TB
13+
graph LR
1414
subgraph "Application Host Process"
1515
H[Host]
1616
C1[Client 1]
@@ -20,21 +20,26 @@ graph TB
2020
H --> C2
2121
H --> C3
2222
end
23-
S1[Server 1<br>Files & Git]
24-
S2[Server 2<br>Database]
25-
S3[Server 3<br>External APIs]
2623
27-
R1[("Local<br>Resource A")]
28-
R2[("Local<br>Resource B")]
29-
R3[("Local<br>Resource C")]
24+
subgraph "Local machine"
25+
S1[Server 1<br>Files & Git]
26+
S2[Server 2<br>Database]
27+
R1[("Local<br>Resource A")]
28+
R2[("Local<br>Resource B")]
3029
31-
C1 --> S1
32-
C2 --> S2
33-
C3 --> S3
30+
C1 --> S1
31+
C2 --> S2
32+
S1 <--> R1
33+
S2 <--> R2
34+
end
35+
36+
subgraph "Internet"
37+
S3[Server 3<br>External APIs]
38+
R3[("Remote<br>Resource C")]
3439
35-
S1 <--> R1
36-
S2 <--> R2
37-
S3 <--> R3
40+
C3 --> S3
41+
S3 <--> R3
42+
end
3843
```
3944

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

65-
## Protocol Capabilities and Flow
70+
## Message Types
71+
MCP defines three core message types based on [JSON-RPC 2.0](https://www.jsonrpc.org/specification):
72+
73+
- **Requests**: Bidirectional messages with method and parameters expecting a response
74+
- **Responses**: Successful results or errors matching specific request IDs
75+
- **Notifications**: One-way messages requiring no response
76+
77+
Each message type follows the JSON-RPC 2.0 specification for structure and delivery semantics.
78+
79+
## Capability Negotiation
6680

6781
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.
6882

6983
- Servers declare capabilities like resource subscriptions, tool support, and prompt templates
7084
- Clients declare capabilities like sampling support and notification handling
7185
- Both parties must respect declared capabilities throughout the session
72-
- Additional capabilities can be negotiated through protocol extensions
86+
- Additional capabilities can be negotiated through extensions to the protocol
7387

7488
```mermaid
7589
sequenceDiagram
7690
participant Host
7791
participant Client
7892
participant Server
7993
80-
Host->>Client: Initialize client
81-
Client->>Server: Initialize session with capabilities
82-
Server-->>Client: Negotiate supported capabilities
94+
Host->>+Client: Initialize client
95+
Client->>+Server: Initialize session with capabilities
96+
Server-->>Client: Respond with supported capabilities
8397
8498
Note over Host,Server: Active Session with Negotiated Features
8599
86-
alt Server Request (if sampling capable)
100+
loop Client Requests
101+
Host->>Client: User- or model-initiated action
102+
Client->>Server: Request (tools/resources)
103+
Server-->>Client: Response
104+
Client-->>Host: Update UI or respond to model
105+
end
106+
107+
loop Server Requests
87108
Server->>Client: Request (sampling)
88109
Client->>Host: Forward to AI
89110
Host-->>Client: AI response
90111
Client-->>Server: Response
91-
else Client Request (based on server caps)
92-
Client->>Server: Request (tools/resources)
93-
Server-->>Client: Response
94-
else Notifications (if supported)
112+
end
113+
114+
loop Notifications
95115
Server--)Client: Resource updates
96116
Client--)Server: Status changes
97117
end
98118
99119
Host->>Client: Terminate
100-
Client->>Server: End session
120+
Client->>-Server: End session
121+
deactivate Server
101122
```
102123

103124
Each capability unlocks specific protocol features for use during the session. For example:
104-
- Resource subscriptions require the server to declare subscription support
125+
- Implemented [server features]({{< ref "/specification/server" >}}) must be advertised in the server's capabilities
126+
- Emitting resource subscription notifications requires the server to declare subscription support
105127
- Tool invocation requires the server to declare tool capabilities
106-
- Sampling requires the client to declare sampling support
128+
- [Sampling]({{< ref "/specification/client" >}}) requires the client to declare support in its capabilities
107129

108130
This capability negotiation ensures clients and servers have a clear understanding of supported functionality while maintaining protocol extensibility.
109-
110-
### Message Types
111-
MCP defines three core message types based on [JSON-RPC 2.0](https://www.jsonrpc.org/specification):
112-
113-
- **Requests**: Bidirectional messages with method and parameters expecting a response
114-
- **Responses**: Results or errors matching specific request IDs
115-
- **Notifications**: One-way messages requiring no response
116-
117-
Each message type follows the JSON-RPC 2.0 specification for structure and delivery semantics.
118-
119-
## Protocol Features
120-
121-
### Server Features
122-
Servers implement several foundational features that provide context and capabilities to clients:
123-
124-
- **Resources**: Structured data or content exposed via URIs that can be read and optionally subscribed to for updates
125-
- **Prompts**: Pre-defined templates or instructions that guide language model interactions
126-
- **Tools**: Executable functions that allow models to perform actions or retrieve information
127-
- **Utilities**: Helper features for logging, argument completion, and other ancillary functions
128-
129-
The server features focus on exposing data and functionality in a controlled way while maintaining security boundaries.
130-
131-
### Client Features
132-
Clients provide core features for interacting with servers and coordinating with hosts:
133-
134-
- **Sampling**: Ability to request and control language model interactions
135-
- **Root Directory Access**: Controlled exposure of filesystem locations to servers
136-
137-
The client features emphasize safe integration of server capabilities while protecting user privacy and security.

‎docs/specification/basic/_index.md

Lines changed: 30 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -5,47 +5,53 @@ cascade:
55
weight: 2
66
---
77

8-
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.
8+
{{< callout type="info" >}}
9+
**Protocol Revision**: {{< param protocolRevision >}}
10+
{{< /callout >}}
911

10-
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:
12+
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:
1113

12-
| Type | Description | Requirements |
13-
|----------------|----------------------------------------|---------------------------------------|
14-
| `Requests` | Messages sent to initiate an operation | Must include unique ID and method name|
15-
| `Responses` | Messages sent in reply to requests | Must include same ID as request |
16-
| `Notifications`| One-way messages with no reply | Must not include an ID |
14+
| Type | Description | Requirements |
15+
|----------------|----------------------------------------|----------------------------------------|
16+
| `Requests` | Messages sent to initiate an operation | Must include unique ID and method name |
17+
| `Responses` | Messages sent in reply to requests | Must include same ID as request |
18+
| `Notifications`| One-way messages with no reply | Must not include an ID |
1719

18-
The Model Context Protocol consists of several key components that work together:
20+
**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.
21+
22+
## Protocol Layers
1923

20-
**Protocol Layers:**
24+
The Model Context Protocol consists of several key components that work together:
2125

22-
- **Base Protocol**: Core JSON-RPC message types and fundamental operations such as capability exchange
26+
- **Base Protocol**: Core JSON-RPC message types
2327
- **Lifecycle Management**: Connection initialization, capability negotiation, and session control
2428
- **Server Features**: Resources, prompts, and tools exposed by servers
25-
- **Client Features**: Sampling and root directory capabilities
29+
- **Client Features**: Sampling and root directory lists provided by clients
2630
- **Utilities**: Cross-cutting concerns like logging and argument completion
2731

2832
All implementations **MUST** support the base protocol and lifecycle management components. Other components **MAY** be implemented based on the specific needs of the application.
2933

3034
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.
3135

32-
### Model Context Protocol specific methods
33-
34-
MCP defines methods based on JSON-RPC that clients and servers implement:
36+
See the following pages for more details on the different components:
3537

3638
{{< cards >}}
37-
{{< card link="lifecycle" title="Lifecycle" icon="refresh" >}}
38-
{{< card link="resources" title="Resources" icon="document" >}}
39-
{{< card link="prompts" title="Prompts" icon="chat-alt-2" >}}
40-
{{< card link="tools" title="Tools" icon="adjustments" >}}
41-
{{< card link="logging" title="Logging" icon="annotation" >}}
42-
{{< card link="sampling" title="Sampling" icon="code" >}}
39+
{{< card link="/specification/basic/lifecycle" title="Lifecycle" icon="refresh" >}}
40+
{{< card link="/specification/server/resources" title="Resources" icon="document" >}}
41+
{{< card link="/specification/server/prompts" title="Prompts" icon="chat-alt-2" >}}
42+
{{< card link="/specification/server/tools" title="Tools" icon="adjustments" >}}
43+
{{< card link="/specification/server/utilities/logging" title="Logging" icon="annotation" >}}
44+
{{< card link="/specification/client/sampling" title="Sampling" icon="code" >}}
4345
{{< /cards >}}
4446

45-
### Authentication
47+
## Auth
48+
49+
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!
50+
51+
Clients and servers **MAY** negotiate their own custom authentication and authorization strategies.
4652

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

49-
## Specification
55+
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.
5056

51-
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.
57+
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.

0 commit comments

Comments
 (0)