Skip to main content

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

ParameterTypeDescription
contentstringThe message content
contextIdstringUnique identifier for the conversation
rolestringRole of the message sender (usually "user")
attachmentsarrayOptional array of attachments (images, files, etc.)
metadataobjectOptional 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

ParameterTypeDescription
contextIdstringUnique identifier for the conversation
systemPromptstringSystem prompt that defines AI behavior
metadataobjectOptional 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

ParameterTypeDescription
contextIdstringUnique 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

ParameterTypeDescription
contextIdstringUnique 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

ParameterTypeDescription
namestringThe name of the tool to call
argumentsobjectArguments to pass to the tool
contextIdstringOptional 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

ParameterTypeDescription
namestringThe name of the resource to query
querystringThe search query
limitnumberMaximum 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

CodeMessageDescription
-32600Invalid requestThe JSON sent is not a valid request object
-32601Method not foundThe method does not exist / is not available
-32602Invalid paramsInvalid method parameter(s)
-32603Internal errorInternal JSON-RPC error
-32001Authentication errorAuthentication failed or not provided
-32002Context not foundThe specified context ID was not found
-32003Tool not foundThe specified tool was not found
-32004Resource not foundThe specified resource was not found
-32005Rate limit exceededRequest 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:

  1. Error Handling: Implement proper error handling with appropriate status codes and messages
  2. Timeouts: Set appropriate timeouts for long-running operations
  3. Context Management: Implement proper context lifecycle management
  4. Security: Always use HTTPS and implement proper authentication and authorization
  5. Rate Limiting: Implement rate limiting to prevent abuse
  6. Logging: Log API requests and errors for debugging and auditing
  7. Versioning: Consider adding API version to the endpoint path

Next Steps