Parallel Coding Agents and Duplicate MCP Servers

Parallel coding agents can start duplicate MCP server processes because each session makes its own connections. With stdio MCP, the client launches the server as a subprocess; separate agent sessions that enable the same stdio server can therefore launch separate copies. Disable servers a task does not need in each agent’s configuration before starting the session. If several agents need the same service, a suitable Streamable HTTP server can accept multiple client connections without each client launching that server locally.

Why a worktree does not limit MCP processes

A Git worktree is a separate working tree attached to the same repository. It gives an agent its own checkout, but it does not decide which MCP servers the agent starts. That decision comes from the agent’s MCP settings and the settings loaded for its current directory. For more on the checkout setup, see Git worktrees for AI agents.

Keep those two kinds of isolation separate when planning parallel work. A worktree protects file edits from another agent’s uncommitted edits. An MCP setting controls access to an external tool and, for stdio servers, whether another local process is launched. Adding worktrees alone will not reduce the number of enabled stdio connections.

Start with a task inventory. For example, suppose one agent is editing a UI component, another is changing a database migration, and a third is reviewing a pull request. The UI task might need a browser tool; the migration task might need a database tool; the review task might need neither. Give each session only the servers its task calls for. Treat server names in the examples below, such as browser and database, as placeholders for names already present in your configuration.

Task question	Configuration choice
Does this task need any tool from the server?	If no, disable the whole server for that session.
Does it need only some tools from that server?	Use a tool allowlist if the client supports one, but expect the server connection to remain.
Do several sessions need the same service?	Consider a supported HTTP endpoint, accounting for its authentication and access rules.

The distinction in the middle row matters: hiding tools from the model does not necessarily prevent the client from connecting to their server. To limit processes, disable the server or change how clients connect to it.

Claude Code: toggle servers by project

Claude Code lets you toggle a server off in /mcp without removing its configuration. The choice is recorded per project, and a disabled server is still shown in the panel. From the directory where an agent will run, inspect the server list and turn off entries the task will not use:

claude mcp list

Then open Claude Code and use /mcp to toggle the unwanted servers. Check the panel again before launching other sessions. If two tasks use different projects or worktree directories, review each session’s effective server list; a choice made for one project is not a general policy for every project.

Claude Code has local, project, and user MCP scopes. Local and project entries load for the current project; user entries load across projects. If an unneeded server was added at user scope, a per-project toggle is useful for a task-specific exclusion. If you no longer want that server configured, claude mcp remove <name> --scope <scope> removes the entry from the chosen scope. Removal is a different decision from temporarily disabling it, particularly for a remote server whose stored sign-in information you may want to keep.

For a session that should load only a deliberately selected MCP configuration, Claude Code also supports --mcp-config with --strict-mcp-config. The strict flag limits the session to servers supplied through --mcp-config. Use that when you launch scripted tasks with a known server list, and check how any managed MCP configuration applies in your environment. A normal /mcp toggle is simpler when you are working interactively.

Codex CLI: disable a configured server

Codex keeps MCP server entries in config.toml, with user configuration at ~/.codex/config.toml and project configuration at .codex/config.toml in trusted projects. Run codex mcp list to identify the server names before editing a setting. A project configuration is useful when everyone running that project should share the same choice; a user setting is useful for your own default.

To retain a server definition while turning it off, set the server’s enabled key to false. For a server named browser, the relevant TOML entry is:

[mcp_servers.browser]
enabled = false

Place that entry in the configuration layer that should own the decision. If the server is defined in another layer, keep its command, URL, and credentials there; the example changes only the enabled state. Project settings load only for a trusted project, so check that condition before relying on a project-level exclusion. Reopen the agent and inspect /mcp to confirm the resulting server list.

For one task, use a CLI override instead of changing a file. Codex accepts dotted configuration keys through -c or --config, including MCP server enablement:

codex -c mcp_servers.browser.enabled=false

Add another -c mcp_servers.database.enabled=false for another configured server that this run does not need. This is useful when parallel tasks need different server sets from the same user configuration. Put the override in the command that starts the relevant agent session; an override on one session does not configure its peers.

Codex also has enabled_tools and disabled_tools keys for filtering tools exposed by an MCP server. Use them when an agent needs only part of a server’s toolset. Use enabled = false when the goal is to avoid connecting to that server at all.

Gemini CLI: choose session or persistent exclusions

Gemini CLI provides server enable and disable commands, including a --session option. To disable browser for one task, enter the session-only slash command inside that task’s interactive Gemini session:

/mcp disable browser --session

To undo that choice in the same interactive session, enter /mcp enable browser --session. It clears the session-only disable; it does not override a persistent disable or an mcp.allowed or mcp.excluded rule. Without --session, /mcp disable browser persists the choice in a user-wide enablement file, potentially affecting other tasks. The shell gemini mcp disable browser --session command exits after changing only its own in-memory state; it cannot change an already-running or later-launched agent session.

A disabled server appears as disabled in /mcp and does not connect or provide tools. Use the session-only slash command when another task may need the server.

For a configuration-driven choice, Gemini CLI reads server definitions from mcpServers in settings.json. Its mcp.allowed list permits only named servers to connect; mcp.excluded prevents named servers from connecting. For example, this setting permits a task’s database server while excluding other configured servers:

{
  "mcp": {
    "allowed": ["database"]
  }
}

Choose an allowlist when the intended set is small and explicit. Choose mcp.excluded when most configured servers remain useful and you need to block a few. Check which user or project settings file your session loads before applying either choice across parallel tasks.

Gemini CLI also supports includeTools and excludeTools inside a server definition. Those filter discovered tools after a connection is established. They are appropriate for limiting tool availability, but mcp.allowed, mcp.excluded, or disabling the server is the direct choice for avoiding that server connection.

When sharing one server makes sense

Streamable HTTP uses an independently running server that can handle multiple client connections. It can be useful when several agents genuinely need the same service and that service offers an HTTP MCP endpoint. Point the clients at the supported endpoint instead of giving each a stdio launch command. Confirm authentication and access boundaries for the service before sharing it: fewer local child processes does not imply that separate agents should share credentials or unrestricted data access.

For a task that never uses the service, disabling its connection remains the clearest option. Changing a local stdio server to HTTP solely to make an unused tool available to every session adds setup without helping that task.

Check the effective setup before parallel work

List configured servers in each CLI, then inspect the active session’s MCP view: claude mcp list and /mcp, codex mcp list and /mcp, or gemini mcp list and /mcp. Compare the list with the task inventory. A configured entry, an active connection, and a tool visible to the model answer different questions; check the state that matters to your goal.

If duplicates remain, trace which settings each session loads. Look for user-level entries that apply everywhere, project entries in a worktree, and command-line overrides used on only one launch. Change one server choice at a time and start a fresh session to check the result. Keep a server enabled where the task actually needs it; a missing tool during implementation is harder to diagnose than an explicit task-to-server list.

Where Parallel Code fits

Parallel Code is our free, open-source desktop app for macOS and Linux. It runs several AI coding agents in parallel, each in its own git worktree. Set the MCP server choices in the agent CLIs you use for those sessions; the worktrees isolate the agents’ code changes while those CLI settings determine their MCP connections.

Frequently asked questions

Why does each agent have its own MCP server process?

For a stdio server, the MCP client launches a subprocess and communicates through its input and output streams. Separate agent sessions with that server enabled can each start one; a Git worktree does not turn those separate client connections into a shared process.

Will filtering MCP tools reduce the number of processes?

Do not assume so. Tool filters control which capabilities an agent can see or use; Gemini CLI, for example, filters discovered tools after connecting. Disable the whole server when the task needs none of its tools.

Can I disable a server for just one task?

Yes. Claude Code offers a per-project /mcp toggle, Codex CLI accepts a per-run -c mcp_servers.<name>.enabled=false override, and Gemini CLI accepts /mcp disable <name> --session inside the target interactive session. Apply the choice to the specific session before relying on it in parallel work.

Should every agent use one shared HTTP MCP server?

Only when the service supports an HTTP MCP endpoint and the tasks need it. A shared endpoint avoids separate local stdio launches for that service, but each agent still needs an appropriate connection and access policy.