MCP Protocol
Standard protocol for AI tool integration - Understand the Model Context Protocol specification for building standardized AI tool integrations.
Model Context Protocol specification and implementation details.
Overview
MCP (Model Context Protocol) is a standardized protocol for AI agents to interact with external tools and services. Arg0 Desktop implements MCP through stdio JSON-RPC communication.
Protocol Specification
Communication Model
MCP uses stdio-based JSON-RPC 2.0 for communication:
typescript
// Request
{
"jsonrpc": "2.0",
"id": number,
"method": string,
"params": object
}
// Response
{
"jsonrpc": "2.0",
"id": number,
"result": object | undefined,
"error": {
"code": number,
"message": string,
"data": any
} | undefined
}
Initialization Flow
- Handshake: Client sends initialize request
- Capabilities: Server responds with capabilities
- Initialized: Client sends initialized notification
- Ready: Server is ready for tool calls
Methods
initialize
Initialize the MCP connection.
Request:
json
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {
"roots": {
"listChanged": true
},
"sampling": {}
},
"clientInfo": {
"name": "arg0-desktop",
"version": "1.0.0"
}
}
}
Response:
json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2024-11-05",
"capabilities": {
"tools": {},
"resources": {}
},
"serverInfo": {
"name": "my-server",
"version": "1.0.0"
}
}
}
notifications/initialized
Notify server that initialization is complete.
Request:
json
{
"jsonrpc": "2.0",
"method": "notifications/initialized"
}
tools/list
List available tools.
Request:
json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list"
}
Response:
json
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"tools": [
{
"name": "my_tool",
"description": "Description of my tool",
"inputSchema": {
"type": "object",
"properties": {
"param1": {
"type": "string",
"description": "Parameter 1"
}
},
"required": ["param1"]
}
}
]
}
}
tools/call
Execute a tool.
Request:
json
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "my_tool",
"arguments": {
"param1": "value"
}
}
}
Response:
json
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "Tool execution result"
}
]
}
}
resources/list
List available resources.
Request:
json
{
"jsonrpc": "2.0",
"id": 4,
"method": "resources/list"
}
Response:
json
{
"jsonrpc": "2.0",
"id": 4,
"result": {
"resources": [
{
"uri": "file:///path/to/file.txt",
"name": "file.txt",
"description": "A file",
"mimeType": "text/plain"
}
]
}
}
resources/read
Read a resource.
Request:
json
{
"jsonrpc": "2.0",
"id": 5,
"method": "resources/read",
"params": {
"uri": "file:///path/to/file.txt"
}
}
Response:
json
{
"jsonrpc": "2.0",
"id": 5,
"result": {
"contents": [
{
"uri": "file:///path/to/file.txt",
"mimeType": "text/plain",
"text": "File contents"
}
]
}
}
Tool Schema
Tool Definition
typescript
interface Tool {
name: string
description: string
inputSchema: {
type: "object"
properties: Record<string, {
type: string
description: string
enum?: string[]
default?: any
}>
required: string[]
}
}
Tool Result
typescript
interface ToolResult {
content: Array<{
type: "text" | "image" | "resource"
text?: string
data?: string
mimeType?: string
}>
isError?: boolean
}
Error Handling
Error Response
json
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32600,
"message": "Invalid Request",
"data": "Additional error details"
}
}
Error Codes
-32700: Parse error-32600: Invalid request-32601: Method not found-32602: Invalid params-32603: Internal error-32000: Server error
Implementation in Arg0 Desktop
Server Management
typescript
interface MCPServer {
name: string
process: ChildProcess
ready: boolean
tools: Tool[]
}
interface MCPServerConfig {
command: string
args?: string[]
env?: Record<string, string>
}
Communication Flow
typescript
// 1. Start server
const server = await window.api.mcpStart('my-server', {
command: '/path/to/server',
args: ['--arg1']
})
// 2. List tools
const { tools } = await window.api.mcpListTools('my-server')
// 3. Call tool
const { result } = await window.api.mcpCallTool('my-server', 'tool_name', {
param1: 'value'
})
// 4. Stop server
await window.api.mcpStop('my-server')
Timeout Handling
- Default timeout: 20 seconds per request
- Timeout on no response
- Process cleanup on timeout
- Error returned to caller
Best Practices
Server Implementation
- Handle all required methods
- Validate input parameters
- Return appropriate error codes
- Provide clear error messages
- Implement proper cleanup
Client Implementation
- Send proper JSON-RPC requests
- Handle errors gracefully
- Implement retry logic
- Manage server lifecycle
- Monitor server health
Tool Design
- Use descriptive names
- Provide clear descriptions
- Define proper schemas
- Handle edge cases
- Return structured results
Troubleshooting
Connection Issues
- Verify server command path
- Check server logs
- Test server independently
- Verify JSON-RPC format
- Check for protocol version mismatch
Tool Execution Failures
- Validate tool parameters
- Check tool schema
- Review server logs
- Test tool independently
- Check for timeout issues
Performance Issues
- Optimize tool execution
- Implement caching
- Use streaming for large results
- Reduce tool complexity
- Monitor resource usage
Related Documentation
- MCP Integration - MCP usage in Arg0 Desktop
- Agent Implementation - Agent system
- IPC API - IPC communication