monoceros add-mcp-server

Gives the AI agents in a workbench an MCP server to reach, so they can look something up instead of working from memory. The registration lands in the agent’s own config on the next monoceros apply.

monoceros add-mcp-server <name> <connector> [-- <opt>=<value> ...]

<name> is your workbench (acme below is a sample workbench name). <connector> is a catalog connector, which you can browse with monoceros list-components.

Example

monoceros add-mcp-server acme context7

That writes one entry into the workbench yml, and where the connector takes an API key, seeds it into acme.env as an empty key:

acme.yml

mcpServers:
  - name: context7
    options:
      apiKey: ${CONTEXT7_API_KEY}

acme.env

CONTEXT7_API_KEY=

Fill that in before you apply. A server registered without its key would show up in the agent’s tool list and then fail on first use, in the middle of a run, so apply stops on an empty credential rather than letting that happen.

Most of the catalog needs no key here. monoceros add-mcp-server acme rovo writes its one line and stops: Atlassian, Notion, Linear and Figma sign in interactively from inside the container instead, and Atlassian Forge and Microsoft Learn serve public documentation and need no account at all. Both cases leave your env file untouched. See Servers that sign in.

A server the catalog does not carry

The catalog curates a handful of connectors, and there are thousands of MCP servers. For anything else, put the config its provider publishes into the yml’s mcpServers: block directly, and it is just as reproducible as a catalog connector:

mcpServers:
  - name: acme-crm
    transport: stdio
    command: npx
    args: ['-y', '@acme/mcp-server']
    env:
      ACME_API_TOKEN: ${ACME_API_TOKEN}

transport is stdio for a server that runs inside your container, or http / sse for one you reach over the network. A stdio server runs someone else’s package inside your container on every session, so it is worth reading what you are pointing it at.

An entry that carries its own definition is never resolved against the catalog, even if a connector of the same name ships later. Your yml keeps meaning what it meant when you wrote it.

Behavior

• Idempotent. Re-adding the same connector with the same options is a no-op. Adding it with different options is an error, so a value you edited by hand is never silently overwritten. Remove it first, or edit the yml.
• Needs an agent. A workbench with mcp: entries and no AI agent installed fails to apply, instead of quietly ignoring the block.
• Edits the yml only. Run monoceros apply to register the server with the agents in the container.

What apply does with it

It merges your servers into the config of every agent in the workbench, Claude Code, OpenCode and Rovo Dev alike, and each of those files survives a rebuild and is also written by the agent itself. Only the entries Monoceros put there are touched, so a server you added yourself with claude mcp add stays. If the same name exists on both sides, apply stops and asks you to drop one of the two. Picking for you would either throw away the definition you wrote by hand or make your yml describe something the container does not do.

See also

• monoceros remove-mcp-server - the inverse.
• monoceros list-components - browse the connectors and their options.
• monoceros add-feature - add the agent that uses these servers.