Skip to content

Commit 1363e2c

Browse files
jspahrsummersjspahrsummers
authored
Merge pull request modelcontextprotocol#18 from modelcontextprotocol/justin/concepts
Revise "Concepts" section, stub tabs to switch to Python
2 parents 588673f + 50ba756 commit 1363e2c

File tree

6 files changed

+681
-706
lines changed

6 files changed

+681
-706
lines changed

‎docs/concepts/architecture.mdx‎

Lines changed: 135 additions & 121 deletions
Original file line numberDiff line numberDiff line change
@@ -3,49 +3,69 @@ title: "Core architecture"
33
description: "Understand how MCP connects clients, servers, and LLMs"
44
---
55

6-
The Model Context Protocol (MCP) is built on a flexible, extensible architecture that enables seamless communication between LLM applications and external services. This document covers the core architectural components and concepts.
6+
The Model Context Protocol (MCP) is built on a flexible, extensible architecture that enables seamless communication between LLM applications and integrations. This document covers the core architectural components and concepts.
77

88
## Overview
99

1010
MCP follows a client-server architecture where:
1111

12-
- **Clients** are LLM applications (like claude.ai or IDEs) that initiate connections
12+
- **Hosts** are LLM applications (like Claude Desktop or IDEs) that initiate connections
13+
- **Clients** maintain 1:1 connections with servers, inside the host application
1314
- **Servers** provide context, tools, and prompts to clients
14-
- **Hosts** are processes that run MCP clients
1515

1616
```mermaid
1717
flowchart LR
18-
subgraph "Host (e.g., claude.ai)"
19-
client[MCP Client]
18+
subgraph " Host (e.g., Claude Desktop) "
19+
client1[MCP Client]
20+
client2[MCP Client]
2021
end
2122
subgraph "Server Process"
22-
server[MCP Server]
23+
server1[MCP Server]
2324
end
24-
25-
client <-->|Transport Layer| server
25+
subgraph "Server Process"
26+
server2[MCP Server]
27+
end
28+
29+
client1 <-->|Transport Layer| server1
30+
client2 <-->|Transport Layer| server2
2631
```
2732

2833
## Core components
2934

3035
### Protocol layer
3136

32-
The protocol layer handles message framing, request/response linking, and high-level communication patterns. Key classes include:
37+
The protocol layer handles message framing, request/response linking, and high-level communication patterns.
3338

34-
```typescript
35-
class Protocol<SendRequestT, SendNotificationT, SendResultT> {
36-
// Handle incoming requests
37-
setRequestHandler<T>(schema: T, handler: (request: T) => Result): void
38-
39-
// Handle incoming notifications
40-
setNotificationHandler<T>(schema: T, handler: (notification: T) => void): void
41-
42-
// Send requests and await responses
43-
request<T>(request: Request, schema: T): Promise<T>
44-
45-
// Send one-way notifications
46-
notification(notification: Notification): Promise<void>
47-
}
48-
```
39+
<Tabs>
40+
<Tab title="TypeScript">
41+
```typescript
42+
class Protocol<Request, Notification, Result> {
43+
// Handle incoming requests
44+
setRequestHandler<T>(schema: T, handler: (request: T, extra: RequestHandlerExtra) => Promise<Result>): void
45+
46+
// Handle incoming notifications
47+
setNotificationHandler<T>(schema: T, handler: (notification: T) => Promise<void>): void
48+
49+
// Send requests and await responses
50+
request<T>(request: Request, schema: T, options?: RequestOptions): Promise<T>
51+
52+
// Send one-way notifications
53+
notification(notification: Notification): Promise<void>
54+
}
55+
```
56+
</Tab>
57+
<Tab title="Python">
58+
```python
59+
# Python implementation coming soon
60+
```
61+
</Tab>
62+
</Tabs>
63+
64+
Key classes include:
65+
66+
* `Protocol`
67+
* `Client`
68+
* `Server`
4969

5070
### Transport layer
5171

@@ -54,66 +74,48 @@ The transport layer handles the actual communication between clients and servers
5474
1. **Stdio transport**
5575
- Uses standard input/output for communication
5676
- Ideal for local processes
57-
```typescript
58-
class StdioTransport implements Transport {
59-
constructor(stdin: Readable, stdout: Writable)
60-
send(message: JSONRPCMessage): Promise<void>
61-
}
62-
```
63-
64-
2. **WebSocket transport**
65-
- Enables real-time bidirectional communication
66-
- Supports remote connections
67-
```typescript
68-
class WebSocketTransport implements Transport {
69-
constructor(url: URL)
70-
send(message: JSONRPCMessage): Promise<void>
71-
}
72-
```
73-
74-
3. **SSE transport**
77+
78+
2. **HTTP with SSE transport**
7579
- Uses Server-Sent Events for server-to-client messages
7680
- HTTP POST for client-to-server messages
77-
```typescript
78-
class SSETransport implements Transport {
79-
constructor(url: URL)
80-
send(message: JSONRPCMessage): Promise<void>
81-
}
82-
```
81+
82+
All transports use [JSON-RPC](https://www.jsonrpc.org/) 2.0 to exchange messages. See the [specification](https://spec.modelcontextprotocol.io) for detailed information about the Model Context Protocol message format.
8383

8484
### Message types
8585

86-
MCP uses JSON-RPC 2.0 as its message format with three main types:
87-
88-
1. **Requests**
89-
```typescript
90-
interface Request {
91-
method: string
92-
params?: {
93-
_meta?: {
94-
progressToken?: string | number
95-
}
96-
}
97-
}
98-
```
99-
100-
2. **Notifications**
101-
```typescript
102-
interface Notification {
103-
method: string
104-
params?: {
105-
_meta?: Record<string, unknown>
106-
}
107-
}
108-
```
109-
110-
3. **Results**
111-
```typescript
112-
interface Result {
113-
_meta?: Record<string, unknown>
114-
[key: string]: unknown
115-
}
116-
```
86+
MCP has these main types of messages:
87+
88+
1. **Requests** expect a response from the other side:
89+
```typescript
90+
interface Request {
91+
method: string;
92+
params?: { ... };
93+
}
94+
```
95+
96+
2. **Notifications** are one-way messages that don't expect a response:
97+
```typescript
98+
interface Notification {
99+
method: string;
100+
params?: { ... };
101+
}
102+
```
103+
104+
3. **Results** are successful responses to requests:
105+
```typescript
106+
interface Result {
107+
[key: string]: unknown;
108+
}
109+
```
110+
111+
4. **Errors** indicate that a request failed:
112+
```typescript
113+
interface Error {
114+
code: number;
115+
message: string;
116+
data?: unknown;
117+
}
118+
```
117119

118120
## Connection lifecycle
119121

@@ -123,27 +125,25 @@ MCP uses JSON-RPC 2.0 as its message format with three main types:
123125
sequenceDiagram
124126
participant Client
125127
participant Server
126-
128+
127129
Client->>Server: initialize request
128130
Server->>Client: initialize response
129131
Client->>Server: initialized notification
130-
132+
131133
Note over Client,Server: Connection ready for use
132134
```
133135

134-
1. Client sends `initialize` request with capabilities
135-
2. Server responds with supported features
136-
3. Client sends `initialized` notification
136+
1. Client sends `initialize` request with protocol version and capabilities
137+
2. Server responds with its protocol version and capabilities
138+
3. Client sends `initialized` notification as acknowledgment
137139
4. Normal message exchange begins
138140

139141
### 2. Message exchange
140142

141143
After initialization, the following patterns are supported:
142144

143-
- **Request-Response**: Client sends request, server responds
145+
- **Request-Response**: Client or server sends requests, the other responds
144146
- **Notifications**: Either party sends one-way messages
145-
- **Progress Updates**: Long-running operations can report progress
146-
- **Resource Updates**: Servers notify about changed resources
147147

148148
### 3. Termination
149149

@@ -154,19 +154,21 @@ Either party can terminate the connection:
154154

155155
## Error handling
156156

157-
MCP defines standard error codes and handling:
157+
MCP defines these standard error codes:
158158

159159
```typescript
160160
enum ErrorCode {
161-
ConnectionClosed = -1,
162-
ParseError = -32700,
163-
InvalidRequest = -32600,
164-
MethodNotFound = -32601,
165-
InvalidParams = -32602,
166-
InternalError = -32603
161+
// Standard JSON-RPC error codes
162+
ParseError = -32700,
163+
InvalidRequest = -32600,
164+
MethodNotFound = -32601,
165+
InvalidParams = -32602,
166+
InternalError = -32603
167167
}
168168
```
169169

170+
SDKs and applications can define their own error codes above -32000.
171+
170172
Errors are propagated through:
171173
- Error responses to requests
172174
- Error events on transports
@@ -176,31 +178,44 @@ Errors are propagated through:
176178

177179
Here's a basic example of implementing an MCP server:
178180

179-
```typescript
180-
import { Server } from "@modelcontextprotocol/sdk/server";
181-
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";
182-
183-
const server = new Server({
184-
name: "example-server",
185-
version: "1.0.0"
186-
});
187-
188-
// Handle requests
189-
server.setRequestHandler(ListResourcesRequestSchema, async () => {
190-
return {
181+
<Tabs>
182+
<Tab title="TypeScript">
183+
```typescript
184+
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
185+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
186+
187+
const server = new Server({
188+
name: "example-server",
189+
version: "1.0.0"
190+
}, {
191+
capabilities: {
192+
resources: {}
193+
}
194+
});
195+
196+
// Handle requests
197+
server.setRequestHandler(ListResourcesRequestSchema, async () => {
198+
return {
191199
resources: [
192-
{
193-
uri: "example://resource",
194-
name: "Example Resource"
195-
}
200+
{
201+
uri: "example://resource",
202+
name: "Example Resource"
203+
}
196204
]
197-
};
198-
});
199-
200-
// Connect transport
201-
const transport = new StdioServerTransport();
202-
await server.connect(transport);
203-
```
205+
};
206+
});
207+
208+
// Connect transport
209+
const transport = new StdioServerTransport();
210+
await server.connect(transport);
211+
```
212+
</Tab>
213+
<Tab title="Python">
214+
```python
215+
# Python implementation coming soon
216+
```
217+
</Tab>
218+
</Tabs>
204219

205220
## Best practices
206221

@@ -212,9 +227,8 @@ await server.connect(transport);
212227
- Simple process management
213228

214229
2. **Remote communication**
215-
- WebSocket for full-duplex communication
216-
- SSE for scenarios requiring HTTP compatibility
217-
- Consider security implications
230+
- Use SSE for scenarios requiring HTTP compatibility
231+
- Consider security implications including authentication and authorization
218232

219233
### Message handling
220234

@@ -277,4 +291,4 @@ await server.connect(transport);
277291
- Test different transports
278292
- Verify error handling
279293
- Check edge cases
280-
- Load test servers
294+
- Load test servers

0 commit comments

Comments
 (0)