MCP Servers

  • Desktop, mobile and web
  • All plans
View as Markdown

What it does

Your own MCP servers (GitHub, Notion, Sentry, a database bridge, anything you already use from a CLI) are handed to every agent AgentsRoom launches, whatever CLI it runs on, next to the AgentsRoom servers. You declare a server once, in the usual mcpServers JSON block that every CLI documents, and the desktop writes it into each CLI's generated configuration at launch. Before version 1.176.0 (2026-09-16) a user-level server only reached Claude Code and, through the Use my personal CLI configuration switch, Codex; every other provider ignored it.

Three levels declare servers, with the same logic as environment variables: merged by name, the narrowest level wins. Settings (every agent of every CLI, every project), project (every agent of that repository) and agent (that agent alone). An agent's editor lists what it inherits from the two wider levels and lets you switch a server off just for it.

Where to find it

  • Settings > AI providers & accounts > MCP servers: below the per-CLI blocks, not inside one CLI's tab, because a server is a tool you want everywhere.
  • Project settings > AI providers > MCP servers.
  • Add / Edit agent modal > Advanced options > MCP servers. The same field exists on a scheduled task's agent section.

How to use it

  1. Open one of the three MCP servers fields. Each shows a list, one row per server, with a Remote or Local badge, a Handed to agents switch and a Remove this server button.
  2. Add from catalog opens the MCP server catalog: servers published to the official MCP registry by their maintainers, with a search box, a Verified publisher mark and a Load more button. Add on a row builds the declaration for you: a remote server (url and headers) when the entry has one, otherwise the first launchable local package. Where a token is needed, the declaration is filled with a {{secret:NAME}} reference, to store in the Secret Manager under that name.
  3. Paste JSON shows the raw block, so you can paste the mcpServers object you already use in a CLI config, with or without the "mcpServers" wrapper. A local server needs command (plus args and env), a remote one needs url (plus headers and type: http or sse). Errors are listed by server name; the block stays open until it parses, and the catalog refuses to add to a broken block ("The current block is not valid JSON: fix it before adding a server.").
  4. Save. Every agent launched from then on, on any CLI, gets the servers.

Switching a server off writes "disabled": true in its entry. On an inherited row (the agent editor shows the servers coming "from Settings" or "from project") the switch writes an override holding only { "disabled": true }, which turns the server off at that level without redeclaring it. A disabled server is skipped at launch.

Any string value (url, header, env value, argument) accepts {{secret:NAME}}; the value is resolved on the desktop at launch, never stored resolved in the declaration. Names starting with agentsroom are reserved and refused.

Settings

  • mcpServers (global, Settings > AI providers & accounts): the JSON block handed to every agent of every CLI and every project. Empty by default.
  • mcpServers (project override, Project settings > AI providers): same block for every agent of the project; wins over the global block by name.
  • mcpServers (agent, agent editor > Advanced options): the agent's own block; wins over both. An entry holding only {"disabled": true} switches an inherited server off.

Agent tools (MCP)

  • settings_get / settings_set: read or write the mcpServers block at the global or project scope.
  • agents_save: accepts mcpServers on a saved agent.

Providers

The declaration is the same everywhere; the desktop translates it into each CLI's own format at launch.

  • Claude Code and GitHub Copilot CLI: a private launch file passed on the command line, so nothing lands in the project's shared .mcp.json. For Claude Code that file is passed again when a conversation is resumed: a resumed agent keeps the servers declared in AgentsRoom (fixed 2026-09-19; before, a resumed Claude Code agent lost them, completely on an AgentsRoom account profile, invisibly when the same servers also sat in the CLI's own configuration).
  • Codex, OpenCode, Grok Build, Mistral Vibe, Kimi Code, Antigravity, Amp, Cursor, oh-my-pi, Freebuff, Devin: written into the CLI's project-level config file, which AgentsRoom keeps out of git.
  • Codex and Mistral Vibe have no SSE transport: an sse server is ignored for them; http works.
  • Aider has no MCP client at all: servers are not delivered.

Mobile

No editing screen on the phone (the mobile companion edits no launch settings, environment variables included). The behaviour is identical: an agent started from the phone is launched by the desktop with the same servers, from the three levels.

Limits

  • Values are written resolved into the CLI's project config files, which AgentsRoom adds to .gitignore. Committing one of those files by hand would publish a resolved token.
  • A {{secret:NAME}} that does not exist in the vault is written as is, never replaced by an empty string.
  • Not available on team steps: a team node has no MCP servers field.
  • A server name only uses letters, digits, dots, dashes and underscores.

Common questions

  • My MCP server works in Claude Code but my Codex or Grok agents do not see it. Declare it in Settings > AI providers & accounts > MCP servers (or in the project settings): from 1.176.0 that block reaches every CLI. A server that only lives in your personal CLI config still reaches only that CLI.
  • My Claude Code agents on an AgentsRoom account do not see the servers I added with claude mcp add. Those live in the CLI's own config, which a managed account does not read by default. Turn on Use my personal CLI configuration (Settings > AI providers & accounts): user-scope servers and, since 2026-09-20, project-scope servers added for that folder are then merged into every account. See Multiple Accounts.
  • My Claude Code agent had my MCP servers, but after a restart or a resume they are gone. Update AgentsRoom: the launch file that carries the servers declared in Settings, the project or the agent was not passed again when the conversation was resumed. It is now, on a resume as on a fresh start. If you only noticed it on an AgentsRoom account profile, that is expected: on the default profile the CLI's own configuration often lists the same servers and hid the loss.
  • How do I remove a server for one agent only? In the agent's editor, Advanced options > MCP servers, switch off the inherited row: the agent stores a {"disabled": true} override, the other agents keep the server.
  • Do I have to paste my API token in the JSON? No. Store it in the Secret Manager and write {{secret:NAME}} in the header or env value; the catalog does that for you.
  • Why is my server name refused? Names starting with agentsroom are reserved for the servers AgentsRoom manages itself.
  • Where does a project-level server show up in the agent modal? As an inherited row marked "from project", next to the rows "from Settings".

Related