117 lines
2.2 KiB
Markdown
117 lines
2.2 KiB
Markdown
# Model Context Protocol (MCP) Reference
|
|
|
|
## Protocol Overview
|
|
|
|
MCP is JSON-RPC 2.0 based protocol for AI-tool integration.
|
|
|
|
**Version**: 2025-03-26
|
|
**Foundation**: JSON-RPC 2.0
|
|
**Architecture**: Client-Host-Server
|
|
|
|
## Connection Lifecycle
|
|
|
|
1. **Initialize**: Client sends `initialize` request with capabilities
|
|
2. **Response**: Server responds with its capabilities
|
|
3. **Handshake**: Client sends `notifications/initialized`
|
|
4. **Active**: Bidirectional messaging
|
|
5. **Shutdown**: Close connections, cleanup
|
|
|
|
## Core Capabilities
|
|
|
|
### Tools (Executable Functions)
|
|
|
|
Tools are functions that servers expose for execution.
|
|
|
|
**List Tools**:
|
|
```json
|
|
{"method": "tools/list"}
|
|
```
|
|
|
|
**Call Tool**:
|
|
```json
|
|
{
|
|
"method": "tools/call",
|
|
"params": {
|
|
"name": "tool_name",
|
|
"arguments": {}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Prompts (Interaction Templates)
|
|
|
|
Prompts are reusable templates for LLM interactions.
|
|
|
|
**List Prompts**:
|
|
```json
|
|
{"method": "prompts/list"}
|
|
```
|
|
|
|
**Get Prompt**:
|
|
```json
|
|
{
|
|
"method": "prompts/get",
|
|
"params": {
|
|
"name": "prompt_name",
|
|
"arguments": {}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Resources (Data Sources)
|
|
|
|
Resources expose read-only data to clients.
|
|
|
|
**List Resources**:
|
|
```json
|
|
{"method": "resources/list"}
|
|
```
|
|
|
|
**Read Resource**:
|
|
```json
|
|
{
|
|
"method": "resources/read",
|
|
"params": {"uri": "resource://path"}
|
|
}
|
|
```
|
|
|
|
## Transport Types
|
|
|
|
### stdio (Local)
|
|
|
|
Server runs as subprocess. Messages via stdin/stdout.
|
|
|
|
```typescript
|
|
const transport = new StdioClientTransport({
|
|
command: 'node',
|
|
args: ['server.js']
|
|
});
|
|
```
|
|
|
|
### HTTP+SSE (Remote)
|
|
|
|
POST for requests, GET for server events.
|
|
|
|
```typescript
|
|
const transport = new StreamableHTTPClientTransport({
|
|
url: 'http://localhost:3000/mcp'
|
|
});
|
|
```
|
|
|
|
## Error Codes
|
|
|
|
- **-32700**: Parse error
|
|
- **-32600**: Invalid request
|
|
- **-32601**: Method not found
|
|
- **-32602**: Invalid params
|
|
- **-32603**: Internal error
|
|
- **-32002**: Resource not found (MCP-specific)
|
|
|
|
## Best Practices
|
|
|
|
1. **Progressive Disclosure**: Load tool definitions on-demand
|
|
2. **Context Efficiency**: Filter data before returning
|
|
3. **Security**: Validate inputs, sanitize outputs
|
|
4. **Resource Management**: Cleanup connections properly
|
|
5. **Error Handling**: Handle all error cases gracefully
|