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:
// Request
{
jsonrpc: "2.0",
id: number,
method: string,
params: object
}
// Response
{
jsonrpc: "2.0",
id: number,
result?: object,
error?: { message: string }
}
Initialization Flow
- Spawn Process: Main process spawns MCP server as child process
- Handshake: Send
initializewith protocol version - Confirmation: Send
notifications/initialized - Ready: Server becomes ready for tool calls
Server Configuration
interface MCPServerConfig {
command: string // Executable path
args?: string[] // Command arguments
env?: Record<string, string> // Environment variables
}
MCP Server Management
Starting a Server
await window.api.mcpStart('my-server', {
command: '/path/to/server',
args: ['--arg1', '--arg2'],
env: { CUSTOM_VAR: 'value' }
})
Stopping a Server
await window.api.mcpStop('my-server')
Listing Tools
const { tools, error } = await window.api.mcpListTools('my-server')
Calling a Tool
const { result, error } = await window.api.mcpCallTool(
'my-server',
'tool_name',
{ param1: 'value', param2: 123 }
)
Server Status
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 querynumResults(number, optional): Number of results (default: 10)
Example:
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:
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 selectorvalue(string, optional): Value for input
Example:
await window.api.mcpCallTool('browser-server', 'browser_automation', {
action: 'click',
selector: '#submit-button'
})
System Tools
terminal
Execute shell commands.
Parameters:
command(string): Command to executecwd(string, optional): Working directory
Example:
await window.api.mcpCallTool('system-server', 'terminal', {
command: 'ls -la',
cwd: '/home/user'
})
file_system
File operations.
Parameters:
action(string): read, write, list, deletepath(string): File pathcontent(string, optional): Content for write
Example:
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 pathcontent(string): Code contentlanguage(string, optional): Programming language
Example:
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 pathanalysis(boolean, optional): Perform analysis
Example:
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:
#!/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
-
Navigate to Settings > Skills & Tools
-
Add new MCP server configuration:
- Name:
my-custom-server - Command:
/path/to/server.js - Args:
[] - Env:
{}
- Name:
-
Start the server from the MCP panel
-
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
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
- Check command path is correct
- Verify executable permissions
- Check environment variables
- View main process logs for errors
Tools Not Appearing
- Verify server is in "ready" status
- Check
tools/listresponse - Ensure tool schema is valid
- Restart MCP server
Timeout Errors
- Check tool execution time
- Optimize slow operations
- Increase timeout if needed
- Implement async patterns
Communication Errors
- Verify stdio pipes are working
- Check JSON-RPC format
- Ensure protocol version matches
- 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
Related Documentation
- Architecture - System architecture
- Agent System - Agent system details
- Workflows - Workflow automation