modelcontextprotocol/docs
Watch
1
0
Fork
You've already forked docs
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update transports.mdx

Browse source
This commit is contained in:
Justin Spahr-Summers 2024-11-21 15:52:16 +00:00
commit 50ba756cef
No known key found for this signature in database
1 changed files with 162 additions and 175 deletions
Download patch file Download diff file Expand all files Collapse all files

335
docs/concepts/transports.mdx
View file

@ -5,128 +5,13 @@ description: "Learn about MCP's communication mechanisms"
Transports in the Model Context Protocol (MCP) provide the foundation for communication between clients and servers. A transport handles the underlying mechanics of how messages are sent and received. Transports in the Model Context Protocol (MCP) provide the foundation for communication between clients and servers. A transport handles the underlying mechanics of how messages are sent and received.
## How transports work ## Message Format
An MCP transport is built on a simple message-passing architecture where both clients and servers can send messages to each other. The transport layer is responsible for: MCP uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 as its wire format. The transport layer is responsible for converting MCP protocol messages into JSON-RPC format for transmission and converting received JSON-RPC messages back into MCP protocol messages.
- Establishing connections There are three types of JSON-RPC messages used:
- Sending messages
- Receiving messages
- Handling connection lifecycles
- Managing errors
- Ensuring reliable delivery
## Available transport types
MCP supports three main transport types:
### Standard input/output (stdio)
The stdio transport enables communication through standard input and output streams. This is particularly useful for local integrations and command-line tools.
```typescript
// Server implementation
const server = new Server({
name: "example-server",
version: "1.0.0"
});
const transport = new StdioServerTransport();
await server.connect(transport);
// Client implementation
const client = new Client({
name: "example-client",
version: "1.0.0"
});
const transport = new StdioClientTransport({
command: "./server",
args: ["--option", "value"]
});
await client.connect(transport);
```
### WebSocket
WebSocket transport provides real-time, bidirectional communication over a persistent connection. This is ideal for web-based applications that need low-latency messaging.
```typescript
// Server implementation
const server = new Server({
name: "example-server",
version: "1.0.0"
});
const transport = new WebSocketServerTransport();
await server.connect(transport);
// Client implementation
const client = new Client({
name: "example-client",
version: "1.0.0"
});
const transport = new WebSocketClientTransport(
new URL("ws://localhost:3000")
);
await client.connect(transport);
```
### Server-sent events
SSE transport enables server-to-client streaming with HTTP POST requests for client-to-server communication. This is useful when WebSocket support isn't available.
```typescript
// Server implementation
const server = new Server({
name: "example-server",
version: "1.0.0"
});
const transport = new SSEServerTransport("/message", response);
await server.connect(transport);
// Client implementation
const client = new Client({
name: "example-client",
version: "1.0.0"
});
const transport = new SSEClientTransport(
new URL("http://localhost:3000/sse")
);
await client.connect(transport);
```
## Transport interface
All transport implementations must conform to the Transport interface:
```typescript
interface Transport {
// Start processing messages
start(): Promise<void>;
// Send a JSON-RPC message
send(message: JSONRPCMessage): Promise<void>;
// Close the connection
close(): Promise<void>;
// Callbacks
onclose?: () => void;
onerror?: (error: Error) => void;
onmessage?: (message: JSONRPCMessage) => void;
}
```
## Message format
Messages sent over MCP transport follow the JSON-RPC 2.0 specification. There are three types of messages:
### Requests ### Requests
```typescript ```typescript
{ {
jsonrpc: "2.0", jsonrpc: "2.0",
@ -137,7 +22,6 @@ Messages sent over MCP transport follow the JSON-RPC 2.0 specification. There ar
``` ```
### Responses ### Responses
```typescript ```typescript
{ {
jsonrpc: "2.0", jsonrpc: "2.0",
@ -152,7 +36,6 @@ Messages sent over MCP transport follow the JSON-RPC 2.0 specification. There ar
``` ```
### Notifications ### Notifications
```typescript ```typescript
{ {
jsonrpc: "2.0", jsonrpc: "2.0",
@ -161,7 +44,130 @@ Messages sent over MCP transport follow the JSON-RPC 2.0 specification. There ar
} }
``` ```
## Error handling ## Built-in Transport Types
MCP includes two standard transport implementations:
### Standard Input/Output (stdio)
The stdio transport enables communication through standard input and output streams. This is particularly useful for local integrations and command-line tools.
Use stdio when:
- Building command-line tools
- Implementing local integrations
- Needing simple process communication
- Working with shell scripts
<Tabs>
<Tab title="TypeScript">
```typescript
// Server implementation
const server = new Server({
name: "example-server",
version: "1.0.0"
});
const transport = new StdioServerTransport();
await server.connect(transport);
// Client implementation
const client = new Client({
name: "example-client",
version: "1.0.0"
});
const transport = new StdioClientTransport({
command: "./server",
args: ["--option", "value"]
});
await client.connect(transport);
```
</Tab>
<Tab title="Python">
```python
# Python implementation coming soon
```
</Tab>
</Tabs>
### Server-Sent Events (SSE)
SSE transport enables server-to-client streaming with HTTP POST requests for client-to-server communication.
Use SSE when:
- Only server-to-client streaming is needed
- Working with restricted networks
- Implementing simple updates
<Tabs>
<Tab title="TypeScript">
```typescript
// Server implementation
const server = new Server({
name: "example-server",
version: "1.0.0"
});
const transport = new SSEServerTransport("/message", response);
await server.connect(transport);
// Client implementation
const client = new Client({
name: "example-client",
version: "1.0.0"
});
const transport = new SSEClientTransport(
new URL("http://localhost:3000/sse")
);
await client.connect(transport);
```
</Tab>
<Tab title="Python">
```python
# Python implementation coming soon
```
</Tab>
</Tabs>
## Custom Transports
MCP makes it easy to implement custom transports for specific needs. Any transport implementation just needs to conform to the Transport interface:
You can implement custom transports for:
- Custom network protocols
- Specialized communication channels
- Integration with existing systems
- Performance optimization
<Tabs>
<Tab title="TypeScript">
```typescript
interface Transport {
// Start processing messages
start(): Promise<void>;
// Send a JSON-RPC message
send(message: JSONRPCMessage): Promise<void>;
// Close the connection
close(): Promise<void>;
// Callbacks
onclose?: () => void;
onerror?: (error: Error) => void;
onmessage?: (message: JSONRPCMessage) => void;
}
```
</Tab>
<Tab title="Python">
```python
# Python implementation coming soon
```
</Tab>
</Tabs>
## Error Handling
Transport implementations should handle various error scenarios: Transport implementations should handle various error scenarios:
@ -173,29 +179,38 @@ Transport implementations should handle various error scenarios:
Example error handling: Example error handling:
```typescript <Tabs>
class ExampleTransport implements Transport { <Tab title="TypeScript">
async start() { ```typescript
try { class ExampleTransport implements Transport {
// Connection logic async start() {
} catch (error) { try {
this.onerror?.(new Error(`Failed to connect: ${error}`)); // Connection logic
throw error; } catch (error) {
} this.onerror?.(new Error(`Failed to connect: ${error}`));
} throw error;
}
}
async send(message: JSONRPCMessage) { async send(message: JSONRPCMessage) {
try { try {
// Sending logic // Sending logic
} catch (error) { } catch (error) {
this.onerror?.(new Error(`Failed to send message: ${error}`)); this.onerror?.(new Error(`Failed to send message: ${error}`));
throw error; throw error;
}
}
} }
} ```
} </Tab>
``` <Tab title="Python">
```python
# Python implementation coming soon
```
</Tab>
</Tabs>
## Best practices ## Best Practices
When implementing or using MCP transport: When implementing or using MCP transport:
@ -210,34 +225,31 @@ When implementing or using MCP transport:
9. Monitor connection health 9. Monitor connection health
10. Implement proper security measures 10. Implement proper security measures
## Security considerations ## Security Considerations
When implementing transport: When implementing transport:
### Authentication and authorization ### Authentication and Authorization
- Implement proper authentication mechanisms - Implement proper authentication mechanisms
- Validate client credentials - Validate client credentials
- Use secure token handling - Use secure token handling
- Implement authorization checks - Implement authorization checks
### Data security ### Data Security
- Use TLS for network transport - Use TLS for network transport
- Encrypt sensitive data - Encrypt sensitive data
- Validate message integrity - Validate message integrity
- Implement message size limits - Implement message size limits
- Sanitize input data - Sanitize input data
### Network security ### Network Security
- Implement rate limiting - Implement rate limiting
- Use appropriate timeouts - Use appropriate timeouts
- Handle denial of service scenarios - Handle denial of service scenarios
- Monitor for unusual patterns - Monitor for unusual patterns
- Implement proper firewall rules - Implement proper firewall rules
## Debugging transport ## Debugging Transport
Tips for debugging transport issues: Tips for debugging transport issues:
@ -251,28 +263,3 @@ Tips for debugging transport issues:
8. Monitor resource usage 8. Monitor resource usage
9. Test edge cases 9. Test edge cases
10. Use proper error tracking 10. Use proper error tracking
## Transport selection guide
Choose the appropriate transport based on your needs:
### Use stdio when
- Building command-line tools
- Implementing local integrations
- Needing simple process communication
- Working with shell scripts
### Use WebSocket when
- Real-time updates are needed
- Low latency is required
- Bidirectional communication is necessary
- Working with web applications
### Use SSE when
- Only server-to-client streaming is needed
- WebSocket support is limited
- Working with restricted networks
- Implementing simple updates