Arg0/Docs

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

  1. Handshake: Client sends initialize request
  2. Capabilities: Server responds with capabilities
  3. Initialized: Client sends initialized notification
  4. 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

  1. Verify server command path
  2. Check server logs
  3. Test server independently
  4. Verify JSON-RPC format
  5. Check for protocol version mismatch

Tool Execution Failures

  1. Validate tool parameters
  2. Check tool schema
  3. Review server logs
  4. Test tool independently
  5. Check for timeout issues

Performance Issues

  1. Optimize tool execution
  2. Implement caching
  3. Use streaming for large results
  4. Reduce tool complexity
  5. Monitor resource usage