Arg0/Docs

MCP Integration

Extend tool capabilities with MCP - Integrate external tools and services through the Model Context Protocol for extensible AI agent capabilities.

Model Context Protocol (MCP) integration details for extending tool capabilities.

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 with isolated child processes.

MCP Protocol

Communication Model

MCP uses stdio-based JSON-RPC for communication:

typescript
// Request
{
  jsonrpc: "2.0",
  id: number,
  method: string,
  params: object
}

// Response
{
  jsonrpc: "2.0",
  id: number,
  result?: object,
  error?: { message: string }
}

Initialization Flow

  1. Spawn Process: Main process spawns MCP server as child process
  2. Handshake: Send initialize with protocol version
  3. Confirmation: Send notifications/initialized
  4. Ready: Server becomes ready for tool calls

Server Configuration

typescript
interface MCPServerConfig {
  command: string      // Executable path
  args?: string[]       // Command arguments
  env?: Record<string, string>  // Environment variables
}

MCP Server Management

Starting a Server

typescript
await window.api.mcpStart('my-server', {
  command: '/path/to/server',
  args: ['--arg1', '--arg2'],
  env: { CUSTOM_VAR: 'value' }
})

Stopping a Server

typescript
await window.api.mcpStop('my-server')

Listing Tools

typescript
const { tools, error } = await window.api.mcpListTools('my-server')

Calling a Tool

typescript
const { result, error } = await window.api.mcpCallTool(
  'my-server',
  'tool_name',
  { param1: 'value', param2: 123 }
)

Server Status

typescript
const { servers } = await window.api.mcpStatus()
// Returns: [{ name: 'my-server', ready: true }, ...]

Built-in MCP Tools

Web Tools

web_search

Search the web for information.

Parameters:

  • query (string): Search query
  • numResults (number, optional): Number of results (default: 10)

Example:

typescript
await window.api.mcpCallTool('exa-server', 'web_search', {
  query: 'React hooks tutorial',
  numResults: 5
})

browser

Open URL and extract content.

Parameters:

  • url (string): URL to open

Example:

typescript
await window.api.mcpCallTool('browser-server', 'browser', {
  url: 'https://example.com'
})

browser_automation

Automate browser interactions.

Parameters:

  • action (string): Action type (navigate, click, type, etc.)
  • selector (string, optional): CSS selector
  • value (string, optional): Value for input

Example:

typescript
await window.api.mcpCallTool('browser-server', 'browser_automation', {
  action: 'click',
  selector: '#submit-button'
})

System Tools

terminal

Execute shell commands.

Parameters:

  • command (string): Command to execute
  • cwd (string, optional): Working directory

Example:

typescript
await window.api.mcpCallTool('system-server', 'terminal', {
  command: 'ls -la',
  cwd: '/home/user'
})

file_system

File operations.

Parameters:

  • action (string): read, write, list, delete
  • path (string): File path
  • content (string, optional): Content for write

Example:

typescript
await window.api.mcpCallTool('system-server', 'file_system', {
  action: 'read',
  path: '/home/user/file.txt'
})

Code Tools

code_writer

Write or edit code files.

Parameters:

  • path (string): File path
  • content (string): Code content
  • language (string, optional): Programming language

Example:

typescript
await window.api.mcpCallTool('code-server', 'code_writer', {
  path: '/src/app.ts',
  content: 'function hello() { return "world"; }',
  language: 'typescript'
})

code_reader

Read and analyze code.

Parameters:

  • path (string): File path
  • analysis (boolean, optional): Perform analysis

Example:

typescript
await window.api.mcpCallTool('code-server', 'code_reader', {
  path: '/src/app.ts',
  analysis: true
})

Creating Custom MCP Servers

Server Structure

A basic MCP server implementation:

typescript
#!/usr/bin/env node

const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');

const server = new Server({
  name: "my-custom-server",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

// Register tools
server.setRequestHandler('tools/list', async () => {
  return {
    tools: [
      {
        name: "my_tool",
        description: "Description of my tool",
        inputSchema: {
          type: "object",
          properties: {
            param1: { type: "string", description: "Parameter 1" }
          },
          required: ["param1"]
        }
      }
    ]
  };
});

server.setRequestHandler('tools/call', async (request) => {
  const { name, arguments: args } = request.params;
  
  if (name === "my_tool") {
    // Implement tool logic
    return {
      content: [{
        type: "text",
        text: `Tool executed with: ${args.param1}`
      }]
    };
  }
  
  throw new Error(`Unknown tool: ${name}`);
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);

Configuration in Arg0 Desktop

  1. Navigate to Settings > Skills & Tools

  2. Add new MCP server configuration:

    • Name: my-custom-server
    • Command: /path/to/server.js
    • Args: []
    • Env: {}
  3. Start the server from the MCP panel

  4. Tools will appear in the tool catalog

MCP Server Lifecycle

Process Management

  • Spawn: Child process created with stdio pipes
  • Handshake: Protocol initialization
  • Ready: Server accepts tool calls
  • Timeout: 20 seconds per request
  • Cleanup: Process killed on app quit

Error Handling

  • Timeout: Request fails after 20s
  • Process Death: Server restarts on crash
  • Invalid Response: Error returned to agent
  • Handshake Failure: Server marked as not ready

Status Tracking

typescript
interface MCPServerStatus {
  name: string
  ready: boolean
  process?: ChildProcess
  lastError?: string
}

Security Considerations

Process Isolation

  • Each MCP server runs in separate child process
  • Stdio communication only (no shared memory)
  • No direct file system access
  • Environment variable isolation

Input Validation

  • All parameters validated before sending
  • Type checking via JSON schema
  • Path validation for file operations
  • Command validation for shell operations

Resource Limits

  • Timeout: 20 seconds per request
  • Memory: Limited by OS process limits
  • CPU: Limited by OS scheduling
  • Network: No direct network access (via tools only)

Troubleshooting

Server Won't Start

  1. Check command path is correct
  2. Verify executable permissions
  3. Check environment variables
  4. View main process logs for errors

Tools Not Appearing

  1. Verify server is in "ready" status
  2. Check tools/list response
  3. Ensure tool schema is valid
  4. Restart MCP server

Timeout Errors

  1. Check tool execution time
  2. Optimize slow operations
  3. Increase timeout if needed
  4. Implement async patterns

Communication Errors

  1. Verify stdio pipes are working
  2. Check JSON-RPC format
  3. Ensure protocol version matches
  4. Review server logs

Best Practices

Tool Design

  • Keep tools focused and single-purpose
  • Use clear, descriptive names
  • Provide detailed parameter descriptions
  • Include examples in descriptions
  • Handle errors gracefully

Server Implementation

  • Use async/await for I/O operations
  • Implement proper error handling
  • Log important events
  • Validate all inputs
  • Use timeouts for external calls

Configuration

  • Use absolute paths for commands
  • Document required environment variables
  • Test server independently
  • Version your server implementations
  • Provide fallback behavior