📖 Guide
🔧 API
💡 Examples
📖 Guide
🔧 API
💡 Examples

MCP Services API

AIO Sandbox provides comprehensive Model Context Protocol (MCP) integration, aggregating multiple useful MCP servers into a single endpoint for easy agent integration.

MCP Hub Endpoint

Base URL: /mcp or /v1/mcp
Protocol: Streamable HTTP with MCP-compatible message format

The MCP Hub aggregates the following pre-configured servers:

Service Description Capabilities
Browser Browser automation and control Navigate, interact, screenshot, extract content
File File system operations Read, write, search, manage files and directories
Terminal Shell command execution Run commands, manage sessions, stream output
Markitdown Document conversion Convert documents to markdown format
Arxiv Academic paper access Search and retrieve research papers

Connection Methods

Streamable HTTP

Connect to the MCP hub using standard HTTP with MCP message format:

# Test MCP connection
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {
        "roots": {
          "listChanged": true
        }
      },
      "clientInfo": {
        "name": "aio-sandbox-client",
        "version": "1.0.0"
      }
    }
  }'

Alternative Endpoint

You can also use the versioned endpoint:

curl -X POST http://localhost:8080/v1/mcp

MCP Message Flow

1. Initialize Connection

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "sampling": {}
    },
    "clientInfo": {
      "name": "aio-sandbox-client",
      "version": "1.0.0"
    }
  }
}

2. List Available Tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

3. Call Tools

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "browser_navigate",
    "arguments": {
      "url": "https://example.com"
    }
  }
}

Available MCP Tools

Browser Tools

Navigate and interact with web pages:

{
  "name": "browser_navigate",
  "description": "Navigate to a URL",
  "inputSchema": {
    "type": "object",
    "properties": {
      "url": {
        "type": "string",
        "description": "URL to navigate to"
      }
    },
    "required": ["url"]
  }
}

File System Tools

Manage files and directories:

{
  "name": "file_read",
  "description": "Read file contents",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "File path to read"
      }
    },
    "required": ["path"]
  }
}

Terminal Tools

Execute shell commands:

{
  "name": "terminal_exec",
  "description": "Execute shell command",
  "inputSchema": {
    "type": "object",
    "properties": {
      "command": {
        "type": "string",
        "description": "Command to execute"
      }
    },
    "required": ["command"]
  }
}

Integration Examples

Python MCP Client

import asyncio
import aiohttp
import json

class MCPClient:
    def __init__(self, base_url="http://localhost:8080"):
        self.base_url = base_url
        self.mcp_url = f"{base_url}/mcp"
        self.session = None
        self.request_id = 0
    
    async def __aenter__(self):
        self.session = aiohttp.ClientSession()
        return self
    
    async def __aexit__(self, exc_type, exc_val, exc_tb):
        await self.session.close()
    
    def _next_id(self):
        self.request_id += 1
        return self.request_id
    
    async def send_request(self, method, params=None):
        payload = {
            "jsonrpc": "2.0",
            "id": self._next_id(),
            "method": method,
            "params": params or {}
        }
        
        async with self.session.post(
            self.mcp_url,
            json=payload,
            headers={"Content-Type": "application/json"}
        ) as response:
            return await response.json()
    
    async def initialize(self):
        return await self.send_request("initialize", {
            "protocolVersion": "2024-11-05",
            "capabilities": {
                "roots": {"listChanged": True},
                "sampling": {}
            },
            "clientInfo": {
                "name": "python-mcp-client",
                "version": "1.0.0"
            }
        })
    
    async def list_tools(self):
        return await self.send_request("tools/list")
    
    async def call_tool(self, name, arguments):
        return await self.send_request("tools/call", {
            "name": name,
            "arguments": arguments
        })

# Usage example
async def demo():
    async with MCPClient() as client:
        # Initialize connection
        init_result = await client.initialize()
        print("Initialized:", init_result)
        
        # List available tools
        tools = await client.list_tools()
        print("Available tools:", [tool["name"] for tool in tools.get("result", {}).get("tools", [])])
        
        # Navigate to a website
        nav_result = await client.call_tool("browser_navigate", {
            "url": "https://example.com"
        })
        print("Navigation result:", nav_result)
        
        # Read a file
        file_result = await client.call_tool("file_read", {
            "path": "/etc/os-release"
        })
        print("File content:", file_result)

asyncio.run(demo())

JavaScript MCP Client

class MCPClient {
    constructor(baseUrl = 'http://localhost:8080') {
        this.baseUrl = baseUrl;
        this.mcpUrl = `${baseUrl}/mcp`;
        this.requestId = 0;
    }
    
    nextId() {
        return ++this.requestId;
    }
    
    async sendRequest(method, params = {}) {
        const payload = {
            jsonrpc: '2.0',
            id: this.nextId(),
            method,
            params
        };
        
        const response = await fetch(this.mcpUrl, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(payload)
        });
        
        return await response.json();
    }
    
    async initialize() {
        return await this.sendRequest('initialize', {
            protocolVersion: '2024-11-05',
            capabilities: {
                roots: { listChanged: true },
                sampling: {}
            },
            clientInfo: {
                name: 'javascript-mcp-client',
                version: '1.0.0'
            }
        });
    }
    
    async listTools() {
        return await this.sendRequest('tools/list');
    }
    
    async callTool(name, arguments) {
        return await this.sendRequest('tools/call', {
            name,
            arguments
        });
    }
}

// Usage example
async function demo() {
    const client = new MCPClient();
    
    // Initialize
    const initResult = await client.initialize();
    console.log('Initialized:', initResult);
    
    // List tools
    const tools = await client.listTools();
    console.log('Available tools:', tools.result?.tools?.map(t => t.name));
    
    // Execute a command
    const cmdResult = await client.callTool('terminal_exec', {
        command: 'ls -la'
    });
    console.log('Command result:', cmdResult);
}

demo().catch(console.error);

Error Handling

MCP responses follow the JSON-RPC 2.0 error format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": {
      "details": "Additional error information"
    }
  }
}

Common error codes:

  • -32700: Parse error
  • -32600: Invalid Request
  • -32601: Method not found
  • -32602: Invalid params
  • -32603: Internal error

Rate Limiting

MCP services have the following rate limits:

  • Tools/list: 10 requests/minute
  • Tools/call: 100 requests/minute per tool
  • File operations: 50 operations/minute
  • Browser actions: 20 actions/minute

Security Considerations

  • MCP services run in the same sandbox environment
  • File operations are restricted to the sandbox file system
  • Browser actions are isolated within the container
  • No external network access from MCP tools (except browser)

Next Steps

For more details about the Model Context Protocol, visit the official MCP documentation.

ON THIS PAGE