MCP servers

Connect Model Context Protocol servers to a project workspace so bot-agent can use their tools.

The runtime can load extra tools from Model Context Protocol (MCP) servers. From the control plane's point of view an MCP config is just a JSON file in the project workspace. After the next workspace sync, bot-agent reads those files from its home directory and exposes each MCP tool as mcp_{server}_{tool}.

This dashboard never starts MCP processes. Stdio servers run on the agent host. HTTP servers are called from the agent host. Put host-specific secrets in the agent environment, not in the workspace file.

Config files

bot-agent loads every *.mcp.config.json file in the home directory after each workspace sync:

File	Where it comes from	Who should edit it
`remote.mcp.config.json`	Project workspace (synced)	Dashboard MCP servers tab, CLI, or Files
`team.mcp.config.json` (or any other `*.mcp.config.json`)	Project workspace (synced)	Same
`local.mcp.config.json`	Agent home only	The person running `bot-agent`

local.mcp.config.json is never taken from the workspace zip. The control plane ignores it: you cannot create, list, or edit it from the MCP servers UI or /api/cli/**/mcp routes. Use it on the agent machine for overrides that must not ship with the project.

Load order is remote.mcp.config.json, then other managed files in name order, then local.mcp.config.json. Later files win when two configs use the same server name.

Manage servers in the dashboard

Open a project.
Choose MCP servers in the sidebar (/projects/{projectId}/mcp).
Project members can view configs. write and admin members can add, edit, disable, or delete servers.
For HTTP (Streamable HTTP) servers, Test Connection in the add/edit dialog talks to the URL from the control plane and lists advertised tools. Stdio is not tested here because that command runs on the agent host. ${NAME} placeholders are not expanded during the test.
New servers are written to remote.mcp.config.json unless you pick another managed file.

You can also keep extra files such as team.mcp.config.json when one group of servers should stay separate from the default remote file. Duplicate names across files show up as warnings; the later file is the one the runtime keeps.

The Files browser still shows the raw JSON. Prefer the MCP servers UI so the file stays valid.

Transports

stdio

Runs a local command on the agent host. Typical shape:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"],
      "env": {
        "TOKEN": "${FS_TOKEN}"
      }
    }
  }
}

The command must already be available on the machine that runs bot-agent. The control plane does not install it.

HTTP

Calls a remote MCP endpoint over Streamable HTTP (http / sse / streamable-http in the file are treated as HTTP):

{
  "mcpServers": {
    "search": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  }
}

URLs must be http or https.

Environment expansion

On the agent host, ${NAME} in command, args, cwd, env, url, and headers is replaced from that process environment. Unset names are left as the literal ${NAME}.

Store placeholders in the workspace. Put the real values in the agent host environment (or in local.mcp.config.json on that host). Workspace JSON is visible to every project member who can read files.

Tool filtering and disable

Field	Effect
`disabled: true`	Server is skipped
`disabledTools` / `blockedTools`	Those original tool names are hidden
`enabledTools`	If set, only those original tool names are kept
`timeoutMs`	Per-call timeout (default 60000)

Server names must match [A-Za-z0-9][A-Za-z0-9._-]{0,63}.

The runtime snapshots MCP tools the first time a conversation lists tools. Elicitation, prompts, and resources are not supported.

CLI

Same operations as the dashboard:

bot mcp list PROJECT_ID
bot mcp add PROJECT_ID filesystem --command npx --arg -y --arg @modelcontextprotocol/server-filesystem --arg /data
bot mcp add PROJECT_ID search --transport http --url https://mcp.example.com/mcp --header Authorization='Bearer ${MCP_TOKEN}'
bot mcp test PROJECT_ID --url https://mcp.example.com/mcp --header Authorization="Bearer $MCP_TOKEN"
bot mcp add PROJECT_ID filesystem --command npx --disabled
bot mcp delete PROJECT_ID filesystem --yes
bot mcp files create PROJECT_ID team.mcp.config.json

--file defaults to remote.mcp.config.json. local.mcp.config.json is rejected.

Architecture — runtime loop and how tools are invoked
CLI — install and login
Security — keep secrets off the workspace when you can