Skip to main content
The Lacanians
Tutorial7 min read

One MCP Config for Every Coding Agent

Teams that run several coding agents end up hand-editing the same MCP servers in many files, and every exposed tool spends context. Define servers once, sync them, and load tools on demand.

A

Abdul Hamid Achik

The Same Server, Twelve Files

A team adopts a second coding agent, then a third. Each one reads its MCP servers from its own file, in its own format: JSON in ~/.claude.json, TOML in ~/.codex/config.toml, YAML for others. Adding one server means editing every file, and the definitions drift the first time someone forgets one.

The second cost is quieter. Each agent loads the full tool list of every server you give it: names, descriptions and input schemas, before the first prompt is typed. With a dozen servers that is hundreds of tool definitions per session, and most sessions use a handful.

Both problems have the same cause. The MCP server list lives in the agent, when it should live in one place you control. This post walks through mcphub, an open-source Go tool we use for this, as the worked example. The pattern applies even if you build your own.

Define Servers Once

mcphub keeps one mcphub.yaml as the source of truth. If your agents already have servers configured, import them instead of retyping:

mcphub init --from-agents   # import servers your harnesses already declare
mcphub list                 # see what is configured

A trimmed config looks like this:

version: 1
expose: lazy

servers:
  codemap:
    command: codemap
    args: [serve]
    enabled: true
    description: Code knowledge graph
    use_when: ["understand symbols, references, and structure in a codebase"]
  vecgrep:
    command: vecgrep
    args: [serve, --mcp]
    enabled: true
    description: Semantic code search

agents:
  claude:
    type: claude
    path: ~/.claude.json
    mode: gateway
  opencode:
    type: opencode
    path: ~/.config/opencode/opencode.json
    mode: direct

The agents block lists each harness, where its config lives, and how it should connect. At the time of writing, mcphub supports twelve harnesses, including Claude Code, Codex, opencode, Gemini CLI and Copilot CLI. Secrets stay out of the file: a server can declare vault: <project> and mcphub injects its secrets at spawn through tvault.

Sync With a Dry Run First

Changing twelve config files should never be a blind write. mcphub sync is a dry run unless you pass --write:

mcphub sync                 # preview every agent, change nothing
mcphub sync claude          # preview one agent
mcphub sync --write         # apply, saving a timestamped .bak first

The preview shows each agent, its mode and the exact change per server:

» claude  (claude, gateway) → /Users/you/.claude.json
    add      mcphub
» opencode  (opencode, direct) → /Users/you/.config/opencode/opencode.json
    up to date

Three properties make this safe to run on a shared machine:

  • Surgical merge. mcphub reads the file, touches only its MCP section, and leaves your other settings alone.
  • Ownership tracking. It records which entries it wrote. A later sync removes only those, never a server you added by hand.
  • Backups. Every write copies the original to <path>.bak-<YYYYMMDD-HHMMSS> first.

Each plan also gets an ID such as plan_1783926023922898000_claude. If a change misbehaves, mcphub sync --rollback <planId> restores the exact backup taken for that plan. One caveat from the docs: TOML, YAML and JSONC files are round-tripped through a generic map, so comments and key order can change on write. The .bak keeps the original byte for byte.

Gateway Mode and Direct Mode

Each agent picks a mode, and this choice controls the context cost.

In direct mode, sync writes every enabled server into the agent verbatim. The agent talks to each server itself and loads every tool schema. Use it when an agent needs a server’s native behavior, or when you have only a couple of servers.

In gateway mode, sync writes a single entry named mcphub, which runs mcphub mcp serve. That process connects to every downstream server and re-exposes their tools as namespaced server__tool names on one stdio connection. A search tool on a server named vecgrep becomes vecgrep__search. The agent sees one server instead of a dozen.

For agents that already carry direct copies of servers, mcphub offload --write removes the redundant entries so only the gateway remains. It touches only servers mcphub both proxies and previously wrote. Without that step, the agent keeps paying for the old direct entries.

Lazy Exposure Keeps Schemas Out of Context

A gateway alone still mounts every downstream tool. Setting expose: lazy changes what the gateway advertises: only its seven management tools, plus anything you pin. The rest of the catalog stays callable, but the agent reaches it on demand.

The loop an agent follows is short:

mcphub_resolve_tool "find code by meaning"    # route the task to a tool
mcphub_describe_tool vecgrep__vecgrep_search  # optional: full schema
mcphub_call_tool {server, tool, arguments}    # run it through the gateway

mcphub_resolve_tool returns a ranked recommendation, the required fields and an argument template. It also returns a status of confident, ambiguous or no_match, and an agent should run only a confident, unambiguous answer. The use_when phrases in your config are the vocabulary the resolver matches against, so write them as user outcomes, not tool names.

The gateway also sends instructions at connect time, telling the model it is in lazy mode and should resolve at the start of a task and when work changes phase. Models that ignore those instructions will underuse the catalog. Lazy mode is a trade, and the docs say so: with one or two servers the indirection can cost as much as it saves, and each first use of an unpinned tool adds a lookup step.

Pin the Tools You Always Use

Pins remove that lookup for hot paths. A pinned tool stays mounted under its server__tool name even in lazy mode:

mcphub pin codemap vecgrep              # whole servers
mcphub pin codemap__codemap_semantic    # one tool
mcphub pin --top 8                      # your 8 most-called tools
mcphub pin                              # list current pins

Pins land in a top-level pin: list in mcphub.yaml, so they sit in version control with everything else. In gateway mode no sync is needed. Restart the agents so their gateway processes reload the config. For per-agent control, an agent entry can carry its own servers and tools lists, and gateway agents launch as mcphub mcp serve --agent <name> so excluded servers are never started.

See Which Servers Earn Their Context

Pins and disables are better chosen from data. The gateway records every proxied call to a local SQLite database: server, tool, duration, success or error, payload sizes and an estimated token cost. The estimate is roughly four bytes per token, a heuristic meant for comparing servers against each other, not for billing.

mcphub stats --since 7d     # what is pulling weight this week
mcphub stats --tools        # which exact tools cost the most
mcphub status               # per-agent sync drift and unused servers

status flags servers that are enabled but have never been called, which are dead weight in every agent’s context. The docs show output in this shape:

Unused:  monitor, vidtrace (enabled but never called)
         → consider `mcphub disable <name>` to shrink agent context.

One limit matters here: only calls that pass through the gateway are recorded. An agent in direct mode talks to servers itself, so its usage is invisible. If you want the numbers, run the agent in gateway mode.

A Review Loop to Adopt

The transferable part is the loop, whichever tool you use:

  1. Keep one source of truth for MCP servers, in version control.
  2. Preview every change to agent configs before applying, and keep a restorable backup.
  3. Give agents the smallest tool surface that still lets them reach everything.
  4. Measure usage locally, then disable or pin based on the last week, not on guesses.

If you are wiring several agents into a team workflow and want this kind of setup designed for your stack, that is the work we do under agent and AI systems. To build the servers themselves, see Building Custom MCP Servers in Go, and for the wider picture, The MCP Revolution.

A

Abdul Hamid Achik

Founder and lead engineer at The Lacanians. Abdul builds production software, developer tools, and local-first systems from Guadalajara for teams worldwide.