Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HKUDS/nanobot/llms.txt

Use this file to discover all available pages before exploring further.

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