MCP Integration

MiniBot can connect remote Model Context Protocol servers in either eager bridge mode or lazy mode. Bridge mode exposes every remote tool at startup; lazy mode keeps the model’s initial tool surface small and loads full remote schemas only when needed.

No extra is required: the MCP client speaks JSON-RPC to the server process directly and has no third-party MCP SDK dependency. Only the test fixtures use the mcp package.

Tool Naming

Bridge mode (the default) calls tools/list for each configured server and exposes tool names as:

<name_prefix>_<server_name>__<remote_tool_name>

Example: prefix mcp, server dice_cli, remote tool roll_dice → mcp_dice_cli__roll_dice.

Lazy mode exposes two bindings per server instead:

<name_prefix>_<server_name>__list_tools
<name_prefix>_<server_name>__call_tool

When available, server initialization instructions are included in the main agent’s system prompt while that server has an attached tool; they are omitted when tool policy hides the server. Lazy binding descriptions also include the instructions. Call list_tools to retrieve the remote names, descriptions, and complete input schemas, then call call_tool with the selected remote name and arguments. MiniBot initializes lazy servers at startup to obtain that metadata, but defers tools/list until the catalog is requested.

Configuration

[tools.mcp]
enabled = true
name_prefix = "mcp"
timeout_seconds = 10

Stdio transport example:

[[tools.mcp.servers]]
name = "dice_cli"
mode = "bridge"
transport = "stdio"
command = "python"
args = ["tests/fixtures/mcp/stdio_dice_server.py"]
env = {}
cwd = "."

HTTP transport example:

[[tools.mcp.servers]]
name = "dice_http"
mode = "lazy"
transport = "http"
url = "http://127.0.0.1:8765/mcp"
headers = {}
catalog_cache_ttl_seconds = 60

mode defaults to "bridge" for compatibility. For "lazy" servers, catalog_cache_ttl_seconds controls automatic catalog discovery before a direct call_tool; set it to 0 to disable the cache. An explicit list_tools call always refreshes the catalog.

See Suggested MCP Servers for recommended servers (email, long-term memory) and how to run local MCP binaries, including under Docker.

Note

Browser automation no longer goes through an MCP server. It now drives the playwright-cli binary directly through the bash tool via a dedicated agent skill — see agents/browser_agent.md for the canonical setup (tools_allow includes bash, list_files, read_file, grep, http_request, pre_response, wait; no mcp_servers entry needed).

Reloading Servers

Bridge mode builds one tool per remote tool when MiniBot starts, so a tool the server adds later, or a server that was down at startup, is invisible until the next restart. Set reload = true to expose a reload_mcp tool to the main agent:

[tools.mcp]
enabled = true
reload = true

reload defaults to false. When it is on, reload_mcp queries every configured server again and swaps the main agent’s MCP tools, the server instructions in its system prompt and the /mcp page. The result lists, per server, the tools it now offers or the error it returned, plus the tool names added and removed.

  • A server that does not respond keeps the tools it had before and is reported with its error, so a failed reload never removes working tools.

  • If the reloaded tools cannot be applied to the main agent, the whole reload is rolled back and the previous tools and connections stay in place.

  • Only the servers already in the configuration are queried: adding or removing a server, or changing its command, URL, headers or tool filters, still needs a restart.

  • Calls already running against a server when it is reloaded can fail, because its previous connection is closed once the new tools are in place.

  • Specialist agents are not affected: they start their own MCP connections for each task.

Tool Filtering

  • enabled_tools — if empty, all discovered tools are allowed; if set, only listed remote tool names are exposed.

  • disabled_tools — always excluded, even if also present in enabled_tools.

Lazy catalogs and lazy calls apply the same filters. A direct lazy call discovers the catalog first when needed and rejects a disabled or unavailable remote tool before sending tools/call.

Troubleshooting

  • If eager discovery fails, startup logs include failed to load mcp tools with the server name.

  • If lazy metadata discovery fails, MiniBot keeps the lazy bindings with a configured-server fallback description; catalog and call requests retry the connection later.

  • If the main agent answers without using tools (common with some OpenRouter models), set [orchestration].main_tool_use_guardrail = "llm_classifier" to enforce a tool-routing classification step before each final answer.