Why doesn't editing mcp.json or "claude mcp add" work in codus?

Because codus manages the tool configuration for you. Every time it starts an agent, codus writes that agent's tool configuration itself and starts the agent in strict mode, so the agent loads only the servers codus hands it. Editing a config file by hand (such as an .mcp.json), or running claude mcp add in a terminal, has no effect, because codus does not read those. Add your servers in Settings under MCP servers, and codus takes care of the rest.

What codus does for you

When an agent starts, codus does two things:

1. It builds that agent's tool configuration fresh, from your MCP servers list in Settings.
2. It starts the agent in strict mode, which tells the agent to ignore any config file it might otherwise find sitting in the project folder and to use only the configuration codus wrote for it.

It does this every single time an agent starts, so your MCP servers list is always the single source of truth. This is also what keeps agents from crossing wires when you open the same folder in more than one place.

Why the manual routes are ignored

• Editing an mcp.json or .mcp.json by hand. codus rebuilds its own configuration each time an agent starts and runs it in strict mode, so a file you edited yourself is never read.
• Running claude mcp add in a terminal. That command writes to the Claude command-line tool's own configuration, which codus's strict start does not load.

Either way, the change is skipped quietly, with no error, which is why it can look like nothing happened. The one place that always takes effect is Settings under MCP servers.

Add servers here instead

1. Click the gear (⚙), then See all settings →.
2. Click MCP servers in the list on the left.
3. Add your server there. See How do I add a custom tool server (MCP) to codus? for each field.

Changes you make here reach your agents within seconds of saving, including any agent that is mid-conversation, with no restart and no terminal commands.

Good to know

• codus always adds its own built-in tools last when it builds the configuration, so nothing you add can knock them out. That is also why the name codus is reserved.
• Because codus rebuilds the configuration on every start, you never edit files, never restart, and never run terminal commands to manage your agents' tools. The MCP servers section is the whole job.

Common problems

• I ran claude mcp add and my agent cannot see the tool. That is expected. codus does not load servers added that way. Add the server again in Settings under MCP servers.
• I hand-edited an mcp.json and nothing changed. That is expected too. codus ignores it and uses its own configuration. Make the change in Settings under MCP servers instead.