Skip to content

Commit 2653e2b

Browse files
pcarletonpcarleton
committed
copy current spec to draft for next revision
1 parent 0115a7b commit 2653e2b

File tree

20 files changed

+3013
-0
lines changed

20 files changed

+3013
-0
lines changed

‎docs/specification/draft/architecture/index.mdx

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
---
2+
title: Architecture
3+
---
4+
5+
The Model Context Protocol (MCP) follows a client-host-server architecture where each
6+
host can run multiple client instances. This architecture enables users to integrate AI
7+
capabilities across applications while maintaining clear security boundaries and
8+
isolating concerns. Built on JSON-RPC, MCP provides a stateful session protocol focused
9+
on context exchange and sampling coordination between clients and servers.
10+
11+
## Core Components
12+
13+
```mermaid
14+
graph LR
15+
subgraph "Application Host Process"
16+
H[Host]
17+
C1[Client 1]
18+
C2[Client 2]
19+
C3[Client 3]
20+
H --> C1
21+
H --> C2
22+
H --> C3
23+
end
24+
25+
subgraph "Local machine"
26+
S1[Server 1<br>Files & Git]
27+
S2[Server 2<br>Database]
28+
R1[("Local<br>Resource A")]
29+
R2[("Local<br>Resource B")]
30+
31+
C1 --> S1
32+
C2 --> S2
33+
S1 <--> R1
34+
S2 <--> R2
35+
end
36+
37+
subgraph "Internet"
38+
S3[Server 3<br>External APIs]
39+
R3[("Remote<br>Resource C")]
40+
41+
C3 --> S3
42+
S3 <--> R3
43+
end
44+
```
45+
46+
### Host
47+
48+
The host process acts as the container and coordinator:
49+
50+
- Creates and manages multiple client instances
51+
- Controls client connection permissions and lifecycle
52+
- Enforces security policies and consent requirements
53+
- Handles user authorization decisions
54+
- Coordinates AI/LLM integration and sampling
55+
- Manages context aggregation across clients
56+
57+
### Clients
58+
59+
Each client is created by the host and maintains an isolated server connection:
60+
61+
- Establishes one stateful session per server
62+
- Handles protocol negotiation and capability exchange
63+
- Routes protocol messages bidirectionally
64+
- Manages subscriptions and notifications
65+
- Maintains security boundaries between servers
66+
67+
A host application creates and manages multiple clients, with each client having a 1:1
68+
relationship with a particular server.
69+
70+
### Servers
71+
72+
Servers provide specialized context and capabilities:
73+
74+
- Expose resources, tools and prompts via MCP primitives
75+
- Operate independently with focused responsibilities
76+
- Request sampling through client interfaces
77+
- Must respect security constraints
78+
- Can be local processes or remote services
79+
80+
## Design Principles
81+
82+
MCP is built on several key design principles that inform its architecture and
83+
implementation:
84+
85+
1. **Servers should be extremely easy to build**
86+
87+
- Host applications handle complex orchestration responsibilities
88+
- Servers focus on specific, well-defined capabilities
89+
- Simple interfaces minimize implementation overhead
90+
- Clear separation enables maintainable code
91+
92+
2. **Servers should be highly composable**
93+
94+
- Each server provides focused functionality in isolation
95+
- Multiple servers can be combined seamlessly
96+
- Shared protocol enables interoperability
97+
- Modular design supports extensibility
98+
99+
3. **Servers should not be able to read the whole conversation, nor "see into" other
100+
servers**
101+
102+
- Servers receive only necessary contextual information
103+
- Full conversation history stays with the host
104+
- Each server connection maintains isolation
105+
- Cross-server interactions are controlled by the host
106+
- Host process enforces security boundaries
107+
108+
4. **Features can be added to servers and clients progressively**
109+
- Core protocol provides minimal required functionality
110+
- Additional capabilities can be negotiated as needed
111+
- Servers and clients evolve independently
112+
- Protocol designed for future extensibility
113+
- Backwards compatibility is maintained
114+
115+
## Capability Negotiation
116+
117+
The Model Context Protocol uses a capability-based negotiation system where clients and
118+
servers explicitly declare their supported features during initialization. Capabilities
119+
determine which protocol features and primitives are available during a session.
120+
121+
- Servers declare capabilities like resource subscriptions, tool support, and prompt
122+
templates
123+
- Clients declare capabilities like sampling support and notification handling
124+
- Both parties must respect declared capabilities throughout the session
125+
- Additional capabilities can be negotiated through extensions to the protocol
126+
127+
```mermaid
128+
sequenceDiagram
129+
participant Host
130+
participant Client
131+
participant Server
132+
133+
Host->>+Client: Initialize client
134+
Client->>+Server: Initialize session with capabilities
135+
Server-->>Client: Respond with supported capabilities
136+
137+
Note over Host,Server: Active Session with Negotiated Features
138+
139+
loop Client Requests
140+
Host->>Client: User- or model-initiated action
141+
Client->>Server: Request (tools/resources)
142+
Server-->>Client: Response
143+
Client-->>Host: Update UI or respond to model
144+
end
145+
146+
loop Server Requests
147+
Server->>Client: Request (sampling)
148+
Client->>Host: Forward to AI
149+
Host-->>Client: AI response
150+
Client-->>Server: Response
151+
end
152+
153+
loop Notifications
154+
Server--)Client: Resource updates
155+
Client--)Server: Status changes
156+
end
157+
158+
Host->>Client: Terminate
159+
Client->>-Server: End session
160+
deactivate Server
161+
```
162+
163+
Each capability unlocks specific protocol features for use during the session. For
164+
example:
165+
166+
- Implemented [server features](/specification/2025-03-26/server) must be advertised in the
167+
server's capabilities
168+
- Emitting resource subscription notifications requires the server to declare
169+
subscription support
170+
- Tool invocation requires the server to declare tool capabilities
171+
- [Sampling](/specification/2025-03-26/client) requires the client to declare support in its
172+
capabilities
173+
174+
This capability negotiation ensures clients and servers have a clear understanding of
175+
supported functionality while maintaining protocol extensibility.

‎docs/specification/draft/basic/index.mdx

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: Overview
3+
---
4+
5+
<Info>**Protocol Revision**: 2025-03-26</Info>
6+
7+
The Model Context Protocol consists of several key components that work together:
8+
9+
- **Base Protocol**: Core JSON-RPC message types
10+
- **Lifecycle Management**: Connection initialization, capability negotiation, and
11+
session control
12+
- **Server Features**: Resources, prompts, and tools exposed by servers
13+
- **Client Features**: Sampling and root directory lists provided by clients
14+
- **Utilities**: Cross-cutting concerns like logging and argument completion
15+
16+
All implementations **MUST** support the base protocol and lifecycle management
17+
components. Other components **MAY** be implemented based on the specific needs of the
18+
application.
19+
20+
These protocol layers establish clear separation of concerns while enabling rich
21+
interactions between clients and servers. The modular design allows implementations to
22+
support exactly the features they need.
23+
24+
## Messages
25+
26+
All messages between MCP clients and servers **MUST** follow the
27+
[JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification. The protocol defines
28+
these types of messages:
29+
30+
### Requests
31+
32+
Requests are sent from the client to the server or vice versa, to initiate an operation.
33+
34+
```typescript
35+
{
36+
jsonrpc: "2.0";
37+
id: string | number;
38+
method: string;
39+
params?: {
40+
[key: string]: unknown;
41+
};
42+
}
43+
```
44+
45+
- Requests **MUST** include a string or integer ID.
46+
- Unlike base JSON-RPC, the ID **MUST NOT** be `null`.
47+
- The request ID **MUST NOT** have been previously used by the requestor within the same
48+
session.
49+
50+
### Responses
51+
52+
Responses are sent in reply to requests, containing the result or error of the operation.
53+
54+
```typescript
55+
{
56+
jsonrpc: "2.0";
57+
id: string | number;
58+
result?: {
59+
[key: string]: unknown;
60+
}
61+
error?: {
62+
code: number;
63+
message: string;
64+
data?: unknown;
65+
}
66+
}
67+
```
68+
69+
- Responses **MUST** include the same ID as the request they correspond to.
70+
- **Responses** are further sub-categorized as either **successful results** or
71+
**errors**. Either a `result` or an `error` **MUST** be set. A response **MUST NOT**
72+
set both.
73+
- Results **MAY** follow any JSON object structure, while errors **MUST** include an
74+
error code and message at minimum.
75+
- Error codes **MUST** be integers.
76+
77+
### Notifications
78+
79+
Notifications are sent from the client to the server or vice versa, as a one-way message.
80+
The receiver **MUST NOT** send a response.
81+
82+
```typescript
83+
{
84+
jsonrpc: "2.0";
85+
method: string;
86+
params?: {
87+
[key: string]: unknown;
88+
};
89+
}
90+
```
91+
92+
- Notifications **MUST NOT** include an ID.
93+
94+
### Batching
95+
96+
JSON-RPC also defines a means to
97+
[batch multiple requests and notifications](https://www.jsonrpc.org/specification#batch),
98+
by sending them in an array. MCP implementations **MAY** support sending JSON-RPC
99+
batches, but **MUST** support receiving JSON-RPC batches.
100+
101+
## Auth
102+
103+
MCP provides an [Authorization](/specification/2025-03-26/basic/authorization) framework for use with HTTP.
104+
Implementations using an HTTP-based transport **SHOULD** conform to this specification,
105+
whereas implementations using STDIO transport **SHOULD NOT** follow this specification,
106+
and instead retrieve credentials from the environment.
107+
108+
Additionally, clients and servers **MAY** negotiate their own custom authentication and
109+
authorization strategies.
110+
111+
For further discussions and contributions to the evolution of MCP’s auth mechanisms, join
112+
us in
113+
[GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions)
114+
to help shape the future of the protocol!
115+
116+
## Schema
117+
118+
The full specification of the protocol is defined as a
119+
[TypeScript schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-03-26/schema.ts).
120+
This is the source of truth for all protocol messages and structures.
121+
122+
There is also a
123+
[JSON Schema](https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-03-26/schema.json),
124+
which is automatically generated from the TypeScript source of truth, for use with
125+
various automated tooling.

0 commit comments

Comments
 (0)