MCP Protocol Reference
This document provides a comprehensive reference for the Model Context Protocol (MCP), explaining its endpoints, request/response formats, and usage guidelines.
Protocol Overview
The Model Context Protocol is a JSON-RPC 2.0 based protocol designed for communication between clients and AI model servers. It defines a standard interface for:
- Exchanging messages in conversations
- Managing conversation context
- Executing tools
- Querying resources
- Handling streaming responses
Base URL
All MCP API requests are made to the base URL of your MCP server, typically:
https://your-mcp-server.trmx.ai/
Authentication
Most MCP servers require authentication. The protocol supports several authentication mechanisms:
API Key Authentication
POST /api/chat
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
{
"method": "message.send",
"params": {
// ...
}
}
OAuth Authentication
POST /api/chat
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH_TOKEN
{
"method": "message.send",
"params": {
// ...
}
}
Core Methods
message.send
Sends a message to the AI model.
Request
{
"method": "message.send",
"params": {
"content": "What's the weather like today?",
"contextId": "user-123-conversation-456",
"role": "user"
},
"id": "request-789"
}
Parameters
Parameter | Type | Description |
---|---|---|
content | string | The message content |
contextId | string | Unique identifier for the conversation |
role | string | Role of the message sender (usually "user") |
attachments | array | Optional array of attachments (images, files, etc.) |
metadata | object | Optional metadata for the message |
Response
{
"result": {
"id": "msg-abc123",
"content": "Based on your location in San Francisco, it's currently 65°F and sunny.",
"role": "assistant",
"timestamp": "2023-09-15T14:32:21Z"
},
"id": "request-789"
}
context.create
Creates a new conversation context.
Request
{
"method": "context.create",
"params": {
"contextId": "user-123-conversation-456",
"systemPrompt": "You are a helpful assistant that provides accurate and concise information."
},
"id": "request-790"
}
Parameters
Parameter | Type | Description |
---|---|---|
contextId | string | Unique identifier for the conversation |
systemPrompt | string | System prompt that defines AI behavior |
metadata | object | Optional metadata for the context |
Response
{
"result": {
"contextId": "user-123-conversation-456",
"created": true,
"timestamp": "2023-09-15T14:30:00Z"
},
"id": "request-790"
}
context.get
Retrieves a conversation context.
Request
{
"method": "context.get",
"params": {
"contextId": "user-123-conversation-456"
},
"id": "request-791"
}
Parameters
Parameter | Type | Description |
---|---|---|
contextId | string | Unique identifier for the conversation |
Response
{
"result": {
"contextId": "user-123-conversation-456",
"messages": [
{
"id": "msg-system-1",
"content": "You are a helpful assistant that provides accurate and concise information.",
"role": "system",
"timestamp": "2023-09-15T14:30:00Z"
},
{
"id": "msg-user-1",
"content": "What's the weather like today?",
"role": "user",
"timestamp": "2023-09-15T14:32:00Z"
},
{
"id": "msg-assistant-1",
"content": "Based on your location in San Francisco, it's currently 65°F and sunny.",
"role": "assistant",
"timestamp": "2023-09-15T14:32:21Z"
}
],
"metadata": {},
"created": "2023-09-15T14:30:00Z",
"updated": "2023-09-15T14:32:21Z"
},
"id": "request-791"
}
context.delete
Deletes a conversation context.
Request
{
"method": "context.delete",
"params": {
"contextId": "user-123-conversation-456"
},
"id": "request-792"
}
Parameters
Parameter | Type | Description |
---|---|---|
contextId | string | Unique identifier for the conversation |
Response
{
"result": {
"deleted": true
},
"id": "request-792"
}
tools.list
Lists available tools.
Request
{
"method": "tools.list",
"params": {},
"id": "request-793"
}
Response
{
"result": {
"tools": [
{
"name": "calculator",
"description": "Performs basic arithmetic calculations",
"parameters": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": ["add", "subtract", "multiply", "divide"],
"description": "The operation to perform"
},
"a": {
"type": "number",
"description": "First operand"
},
"b": {
"type": "number",
"description": "Second operand"
}
},
"required": ["operation", "a", "b"]
}
},
{
"name": "weather",
"description": "Gets current weather information for a location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City name or zip code"
},
"units": {
"type": "string",
"enum": ["metric", "imperial"],
"description": "Units of measurement",
"default": "metric"
}
},
"required": ["location"]
}
}
]
},
"id": "request-793"
}
tools.call
Calls a tool with specific parameters.
Request
{
"method": "tools.call",
"params": {
"name": "calculator",
"arguments": {
"operation": "add",
"a": 5,
"b": 3
},
"contextId": "user-123-conversation-456"
},
"id": "request-794"
}
Parameters
Parameter | Type | Description |
---|---|---|
name | string | The name of the tool to call |
arguments | object | Arguments to pass to the tool |
contextId | string | Optional conversation context ID |
Response
{
"result": {
"result": 8
},
"id": "request-794"
}
resources.list
Lists available resources.
Request
{
"method": "resources.list",
"params": {},
"id": "request-795"
}
Response
{
"result": {
"resources": [
{
"name": "knowledge_base",
"description": "Access to company knowledge base articles"
},
{
"name": "product_catalog",
"description": "Access to product information"
}
]
},
"id": "request-795"
}
resources.query
Queries a resource with a specific query string.
Request
{
"method": "resources.query",
"params": {
"name": "knowledge_base",
"query": "How to reset password",
"limit": 3
},
"id": "request-796"
}
Parameters
Parameter | Type | Description |
---|---|---|
name | string | The name of the resource to query |
query | string | The search query |
limit | number | Maximum number of results to return |
Response
{
"result": {
"items": [
{
"id": "kb-123",
"title": "Password Reset Guide",
"content": "To reset your password, follow these steps: 1...",
"url": "https://example.com/support/password-reset"
},
{
"id": "kb-124",
"title": "Account Recovery Options",
"content": "If you forget your password, you can recover your account by...",
"url": "https://example.com/support/account-recovery"
}
]
},
"id": "request-796"
}
Streaming Responses
MCP supports streaming responses through HTTP Server-Sent Events (SSE).
Streaming Request
To request a streaming response, append /stream
to the endpoint path:
POST /api/chat/stream
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
{
"method": "message.send",
"params": {
"content": "Write a story about space exploration",
"contextId": "user-123-conversation-456"
},
"id": "request-797"
}
Streaming Response
The server will respond with a stream of events:
event: message.chunk
data: {"id":"chunk-1","content":"In the year 2150, "}
event: message.chunk
data: {"id":"chunk-2","content":"humanity had established "}
event: message.chunk
data: {"id":"chunk-3","content":"colonies on Mars and beyond."}
event: message.done
data: {"id":"msg-abc124","role":"assistant","timestamp":"2023-09-15T14:35:00Z"}
Error Handling
MCP uses standard JSON-RPC 2.0 error format:
{
"error": {
"code": -32603,
"message": "Internal error",
"data": {
"details": "Database connection failed"
}
},
"id": "request-798"
}
Common Error Codes
Code | Message | Description |
---|---|---|
-32600 | Invalid request | The JSON sent is not a valid request object |
-32601 | Method not found | The method does not exist / is not available |
-32602 | Invalid params | Invalid method parameter(s) |
-32603 | Internal error | Internal JSON-RPC error |
-32001 | Authentication error | Authentication failed or not provided |
-32002 | Context not found | The specified context ID was not found |
-32003 | Tool not found | The specified tool was not found |
-32004 | Resource not found | The specified resource was not found |
-32005 | Rate limit exceeded | Request rate limit exceeded |
Content Types
Text Content
For text messages, the content is a simple string:
{
"content": "What is the capital of France?"
}
Multi-Modal Content
For multi-modal content, use an array of content objects:
{
"content": [
{
"type": "text",
"text": "What is this image showing?"
},
{
"type": "image",
"image_url": {
"url": "https://example.com/image.jpg"
}
}
]
}
Implementation Guidelines
When implementing an MCP server or client, follow these guidelines:
- Error Handling: Implement proper error handling with appropriate status codes and messages
- Timeouts: Set appropriate timeouts for long-running operations
- Context Management: Implement proper context lifecycle management
- Security: Always use HTTPS and implement proper authentication and authorization
- Rate Limiting: Implement rate limiting to prevent abuse
- Logging: Log API requests and errors for debugging and auditing
- Versioning: Consider adding API version to the endpoint path