Skip to main content
The MCP integration allows nanobot agents to connect to external MCP servers and use their tools as native nanobot tools.

​
Overview

Model Context Protocol (MCP) is a standardized protocol for AI agents to interact with external tools and services. Nanobot’s MCP integration:
  • Connects to MCP servers via stdio, SSE, or HTTP transports
  • Wraps MCP tools as native nanobot tools
  • Handles authentication and configuration
  • Provides timeout and error handling

​
Configuration

MCP servers are configured in ~/.nanobot/config.json: 
{
  "mcp": {
    "servers": {
      "filesystem": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
        "env": {}
      },
      "brave-search": {
        "type": "sse",
        "url": "https://mcp.example.com/brave/sse",
        "headers": {
          "Authorization": "Bearer token123"
        },
        "tool_timeout": 30
      },
      "custom-api": {
        "type": "streamableHttp",
        "url": "https://api.example.com/mcp",
        "headers": {
          "X-API-Key": "your-api-key"
        }
      }
    }
  }
}

​
Transport Types

​
stdio (Standard Input/Output)

Runs an MCP server as a subprocess and communicates via stdin/stdout. 
{
  "type": "stdio",
  "command": "python",
  "args": ["-m", "my_mcp_server"],
  "env": {
    "API_KEY": "your-key"
  }
}
Use for:
  • Local MCP server processes
  • Node.js packages (via npx)
  • Python modules
  • Binary executables
Auto-detection: If command is specified without type, stdio is assumed.

​
SSE (Server-Sent Events)

Connects to an MCP server over HTTP using Server-Sent Events for streaming. 
{
  "type": "sse",
  "url": "https://mcp.example.com/sse",
  "headers": {
    "Authorization": "Bearer token"
  }
}
Use for:
  • Remote MCP servers
  • Cloud-hosted tools
  • Services requiring authentication
Auto-detection: URLs ending with /sse automatically use SSE transport.

​
streamableHttp (Streamable HTTP)

Connects to an MCP server over HTTP with bidirectional streaming. 
{
  "type": "streamableHttp",
  "url": "https://api.example.com/mcp",
  "headers": {
    "X-API-Key": "key123"
  }
}
Use for:
  • REST-style MCP servers
  • APIs with custom headers
  • Services requiring special authentication
Auto-detection: URLs not ending with /sse automatically use streamableHttp transport.

​
Tool Naming

MCP tools are prefixed with the server name to avoid conflicts: MCP Server: filesystem
MCP Tool: read_file
Nanobot Tool: mcp_filesystem_read_file This allows multiple MCP servers to provide tools with the same name.

​
Tool Schema

​
MCPToolWrapper Properties

  • name: mcp_{server_name}_{tool_name}
  • description: From MCP tool definition
  • parameters: JSON Schema from inputSchema
  • execute: Async method calling MCP server

​
Example Tool

Given this MCP tool definition: 
{
  "name": "read_file",
  "description": "Read a file from the filesystem",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "File path to read"
      }
    },
    "required": ["path"]
  }
}
Nanobot creates a tool with: 
name = "mcp_filesystem_read_file"
description = "Read a file from the filesystem"
parameters = {
    "type": "object",
    "properties": {
        "path": {
            "type": "string",
            "description": "File path to read"
        }
    },
    "required": ["path"]
}

​
Usage Example

Once configured, agents can use MCP tools like any other tool: 
{
  "name": "mcp_filesystem_read_file",
  "arguments": {
    "path": "/workspace/data.txt"
  }
}
The agent automatically:
  1. Routes the call to the correct MCP server
  2. Sends the request with proper formatting
  3. Waits for the response (with timeout)
  4. Returns the result as a string

​
Timeout Handling

Each tool call has a configurable timeout: 
{
  "servers": {
    "slow-api": {
      "url": "https://api.example.com/mcp",
      "tool_timeout": 60
    }
  }
}
Default timeout: 30 seconds If a tool call exceeds the timeout: 
(MCP tool call timed out after 30s)

​
Connection Lifecycle

┌──────────────┐
│  Nanobot     │
│  Startup     │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  Read MCP    │
│  Config      │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  Connect to  │
│  MCP Servers │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  Initialize  │
│  Sessions    │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  List Tools  │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  Register    │
│  Tools       │
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  Tools       │
│  Available   │
└──────────────┘

​
Error Handling

​
Connection Failed

MCP server 'custom-api': failed to connect: Connection refused
Server is not running or URL is incorrect.

​
Tool Timeout

(MCP tool call timed out after 30s)
Tool took too long to respond. Increase tool_timeout or optimize the server.

​
Invalid Response

Error executing tool: Expected TextContent, got ImageContent
MCP server returned unexpected content type.

​
Unknown Transport

MCP server 'myserver': unknown transport type 'websocket'
Invalid transport type. Use stdio, sse, or streamableHttp.

​
Response Format

MCP tools can return multiple content blocks: 
result = await session.call_tool("tool_name", arguments={...})

# result.content is a list of content blocks
for block in result.content:
    if isinstance(block, types.TextContent):
        print(block.text)
    else:
        print(str(block))
Nanobot concatenates all blocks with newlines: 
Block 1 text
Block 2 text
Block 3 text

​
Authentication

​
Headers

Pass authentication headers in the configuration: 
{
  "url": "https://api.example.com/mcp",
  "headers": {
    "Authorization": "Bearer your-token",
    "X-API-Key": "your-key"
  }
}

​
Environment Variables

Pass environment variables to stdio servers: 
{
  "type": "stdio",
  "command": "python",
  "args": ["-m", "server"],
  "env": {
    "API_KEY": "your-key",
    "SECRET": "your-secret"
  }
}

​
Best Practices

​
Server Naming

Use descriptive, unique names: ✅ Good: 
{
  "brave-search": {...},
  "github-api": {...},
  "local-filesystem": {...}
}
❌ Bad: 
{
  "server1": {...},
  "api": {...},
  "test": {...}
}

​
Tool Timeouts

Set appropriate timeouts based on expected response times:
  • Fast APIs: 10-30 seconds
  • Database queries: 30-60 seconds
  • Long-running operations: 60-300 seconds

​
Error Handling

Check logs for connection issues: 
logger.info("MCP server 'name': connected, 5 tools registered")
logger.error("MCP server 'name': failed to connect: error")

​
Environment Variables

Store secrets in environment variables, not config files: 
{
  "env": {
    "API_KEY": "${API_KEY}"
  }
}
Then set: export API_KEY=your-secret-key

​
Available MCP Servers

Popular MCP servers:
  • @modelcontextprotocol/server-filesystem - File operations
  • @modelcontextprotocol/server-github - GitHub API
  • @modelcontextprotocol/server-postgres - PostgreSQL queries
  • @modelcontextprotocol/server-brave-search - Brave Search API
  • @modelcontextprotocol/server-google-maps - Google Maps API
See MCP Documentation for more servers.

​
Implementation

See nanobot/agent/tools/mcp.py for the implementation:
  • MCPToolWrapper: line 14
  • connect_mcp_servers: line 56

Build docs developers (and LLMs) love

Get started for freeTalk to us