Skip to main content
Nanobot supports the Model Context Protocol (MCP) — a standard for connecting AI assistants to external tool servers. MCP servers provide tools that the agent can use alongside its built-in capabilities. Tools are automatically discovered and registered when the gateway starts.

​
Configuration Format

MCP servers are configured under tools.mcpServers: 
{
  "tools": {
    "mcpServers": {
      "server-name": {
        // Server configuration
      }
    }
  }
}

​
Transport Modes

Nanobot supports two MCP transport modes:

​
Stdio (Local Process)

Launch a local MCP server as a subprocess.
​
type
string
default:"stdio"
Transport type. Auto-detected if command is present.
​
command
string
required
Command to run (e.g. "npx", "uvx", "python").
​
args
array
required
Command arguments.
​
env
object
Environment variables to pass to the subprocess.
​
toolTimeout
integer
default:30
Timeout in seconds for each tool call.
{
  "tools": {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
      }
    }
  }
}

​
HTTP/SSE (Remote Server)

Connect to a remote MCP server over HTTP.
​
type
string
Transport type:
  • "sse" — Server-Sent Events (URLs ending with /sse)
  • "streamableHttp" — Streamable HTTP (default for other URLs)
Auto-detected if url is present.
​
url
string
required
Server endpoint URL.
​
headers
object
Custom HTTP headers (e.g. authentication).
​
toolTimeout
integer
default:30
Timeout in seconds for each tool call.
{
  "tools": {
    "mcpServers": {
      "remote": {
        "url": "https://example.com/mcp/sse",
        "headers": {
          "Authorization": "Bearer your-token"
        }
      }
    }
  }
}

​
Tool Naming

MCP tools are automatically prefixed to avoid naming conflicts: 
mcp_{server-name}_{tool-name}
Example:
  • Server: filesystem
  • Tool: read_file
  • Registered as: mcp_filesystem_read_file
The agent can use these tools just like built-in ones.

​
Configuration Examples

​
Official MCP Servers

Access local files and directories.
{
  "tools": {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/path/to/allowed/directory"
        ]
      }
    }
  }
}
Provides: read_file, write_file, list_directory, etc.
Interact with GitHub repositories.
{
  "tools": {
    "mcpServers": {
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
        }
      }
    }
  }
}
Provides: Repository operations, issue management, PR creation, etc.
Access Google Drive files.
{
  "tools": {
    "mcpServers": {
      "gdrive": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-gdrive"]
      }
    }
  }
}
Note: Requires OAuth authentication flow on first run.
Query PostgreSQL databases.
{
  "tools": {
    "mcpServers": {
      "postgres": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-postgres"],
        "env": {
          "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/db"
        }
      }
    }
  }
}

​
Multiple Servers

Run multiple MCP servers simultaneously: 
{
  "tools": {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
      },
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
        }
      },
      "remote-api": {
        "url": "https://mcp.example.com/sse",
        "headers": {
          "Authorization": "Bearer your-token"
        }
      }
    }
  }
}

​
Tool Timeouts

By default, tool calls timeout after 30 seconds. Override for slow operations: 
{
  "tools": {
    "mcpServers": {
      "slow-server": {
        "url": "https://example.com/mcp/",
        "toolTimeout": 120
      }
    }
  }
}
The agent will wait up to 120 seconds for tools from this server.

​
Built-in Tools Configuration

In addition to MCP servers, nanobot has built-in tools with their own configuration:
​
tools.web.search.apiKey
string
Brave Search API key for web search functionality.
​
tools.web.search.maxResults
integer
default:5
Maximum number of search results to return.
​
tools.web.proxy
string
HTTP/SOCKS5 proxy for web requests (e.g. "http://127.0.0.1:7890").
{
  "tools": {
    "web": {
      "search": {
        "apiKey": "BSAxxxxxxxxxxxxx",
        "maxResults": 10
      },
      "proxy": "http://127.0.0.1:7890"
    }
  }
}

​
Shell Execution

​
tools.exec.timeout
integer
default:60
Timeout in seconds for shell commands.
​
tools.exec.pathAppend
string
Extra directories to append to PATH (e.g. "/usr/sbin:/opt/bin").
{
  "tools": {
    "exec": {
      "timeout": 120,
      "pathAppend": "/usr/sbin"
    }
  }
}

​
Workspace Restriction

​
tools.restrictToWorkspace
boolean
default:false
When true, restricts all agent tools (shell, file read/write/edit, list) to the workspace directory. Prevents path traversal and out-of-scope access.
{
  "tools": {
    "restrictToWorkspace": true
  }
}
Security: Enable this in production to sandbox the agent.

​
Complete Example

Full configuration with built-in tools and MCP servers: 
{
  "tools": {
    "restrictToWorkspace": false,
    "web": {
      "search": {
        "apiKey": "BSAxxxxxxxxxxxxx",
        "maxResults": 5
      },
      "proxy": "http://127.0.0.1:7890"
    },
    "exec": {
      "timeout": 60,
      "pathAppend": "/usr/sbin"
    },
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
      },
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
        },
        "toolTimeout": 45
      },
      "remote-api": {
        "url": "https://mcp.example.com/",
        "headers": {
          "Authorization": "Bearer your-token"
        },
        "toolTimeout": 120
      }
    }
  }
}

​
Compatibility

The MCP configuration format is compatible with:
  • Claude Desktop
  • Cursor IDE
  • Any MCP-compatible client
You can copy server configurations directly from MCP server documentation.

​
Troubleshooting

Check the gateway logs for connection errors:
nanobot gateway
# Look for "MCP server 'name': connected, X tools registered"
Common issues:
  • Missing command or url
  • Server process fails to start
  • Network issues for remote servers
  • Missing environment variables
Increase toolTimeout for slow operations:
{
  "tools": {
    "mcpServers": {
      "slow-server": {
        "url": "https://example.com/mcp/",
        "toolTimeout": 180
      }
    }
  }
}
Verify authentication credentials:
  • Stdio: Check env variables are set correctly
  • HTTP: Verify headers contain valid tokens
Example with debug logging:
{
  "tools": {
    "mcpServers": {
      "api": {
        "url": "https://mcp.example.com/",
        "headers": {
          "Authorization": "Bearer your-token",
          "X-Debug": "true"
        }
      }
    }
  }
}

​
Next Steps

Security

Configure access controls and sandboxing

MCP Documentation

Learn more about the Model Context Protocol

Build docs developers (and LLMs) love

Get started for freeTalk to us