---
title: Why doesn't editing mcp.json or "claude mcp add" work in codus?
question: mcp.json ignored
area: mcp
order: 3
surface: desktop
audience: beginner
keywords: [mcp.json, .mcp.json, claude mcp add, ignored, not working, strict, config, hand edit, edit by hand, terminal, add server manually, tools not loading, custom tools, MCP servers, extra tools, servers]
related: [add-a-custom-mcp-server, what-are-custom-tools-mcp, mcp-servers-and-agent-browser]
updated: 2026-07-21
---

# 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?](add-a-custom-mcp-server.md) 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.