MCP Integration

The AgentTeams CLI ships with a built-in MCP (Model Context Protocol) stdio server. Agent CLIs such as Claude Code can search eight record types — plans, completion reports, co-actions, post-mortems, conventions, documents, code reviews, and comments — list them within a project or known parent scope, and read the full records they select. The tool profile determines whether the connection is read-only or also exposes write tools.

The agentteams mcp subcommands handle registration, so you never have to look up each tool’s config syntax. For exact lists, relevance search, full-record reads, and the complete tool catalog, see MCP Tools.

AgentTeams CLI requires Node.js >=20.12.0. This also applies when registering through npx -y @agentteams/cli mcp.

Automatic registration

Run it with no arguments and it registers every client it detects on this machine into the current repository (project scope).

agentteams mcp install

For each client you get the detection evidence, the target config file, and what was applied, followed by a summary line counting registrations, skips, and failures. One client failing does not stop the ones behind it, and any failure makes the command exit non-zero.

Some clients read the same config file — Claude Code and GitHub Copilot CLI both use the project’s .mcp.json. Such a file is written once, and the clients behind it report that the entry is already there.

To see what would change first, add --dry-run. No file and no client setting is touched. Detection may still run a client’s own --help to confirm the executable is the one it claims to be.

agentteams mcp install --dry-run

--dry-run and --yes state opposite intents, so they cannot be combined: passing both fails with an error and runs nothing.

--json also prints the plan instead of applying it by default. Add --yes to perform the batch registration while using JSON output:

agentteams mcp install --json          # prints the plan
agentteams mcp install --json --yes    # applies it

A machine-wide user-scope registration is previewed first and applied only on approval.

agentteams mcp install --scope user
agentteams mcp install --scope user --yes

--scope user alone only prints the plan; only --scope user --yes applies it.

How the two scopes differ

• Project scope (the default) — writes only to client config files inside the current repository. The server shows up when you open the client in this repository. These files are repository state, so they are shared with everyone who clones it: the entry always spawns npx -y @agentteams/cli mcp, which works on any machine, rather than whichever runtime the machine that registered it happened to have.
• User scope — writes to the client’s machine-wide user configuration. Register once and the same server is available across repositories. Because the file never leaves this machine, the entry uses the globally installed agentteams when one is on PATH, which starts faster.

Either way, the entry contains no API key and no value pointing at one AgentTeams project. When the server runs it resolves the project from the AgentTeams configuration of the repository you are working in, plus your stored login. That is why a single user-scope registration keeps working as you move between repositories: each run targets that repository’s project.

Registering during initial setup

Add --mcp when you first connect a project, and the same project-scope registration runs right after the connection completes.

agentteams init --mcp

Without --mcp, agentteams init changes no client configuration at all and simply names agentteams mcp install in its closing steps. If one client fails to register, the initialization still succeeds and the failed client is listed with the command to retry it.

Registering a single client

# project scope (default): this repository only
agentteams mcp install --client claude-code
 
# user scope: the whole machine (explicit opt-in)
agentteams mcp install --client cursor-cli --scope user

Use config when you only want the fragment and no changes. Omit --client to print them all.

agentteams mcp config --client codex

config also defaults to project scope. Add --scope user only when you need a user-scope fragment. It never modifies a file or client setting, and it never prints your real API key.

Supported clients

Codex’s user scope is registered through Codex’s own codex mcp add command, so it is applied automatically. That command has no project-scope option, so only the project scope needs the TOML fragment config prints to be pasted in by hand. In a batch install, Codex project scope is reported as “manual configuration needed” rather than a failure, and the fragment to paste is printed with it. The target config file for each scope is listed in MCP Tools.

Kiro CLI is registered with the full profile by default. If the current tool catalog is not compatible with Kiro, registration automatically selects a compatible profile and reports the selected profile in the result. Kiro uses this registration only when the agent setting includeMcpJson is true; an agent set to false ignores it.

Rerunning Grok Build registration updates the existing entry. Grok also reads .mcp.json and Claude/Cursor configs, so the same server can appear twice when AgentTeams is present in more than one of those sources. Remove the registration you do not want Grok to use.

Oh My Pi registration uses ~/.omp/agent/mcp.json (or PI_CODING_AGENT_DIR/mcp.json) at user scope and .omp/mcp.json at project scope.

Register Muse Code with agentteams mcp install --client muse --scope user. It writes ~/.config/muse/settings.json, or $XDG_CONFIG_HOME/muse/settings.json when XDG_CONFIG_HOME is set, using schema_version: 1 and mcp_servers. If project-scope registration prints a manual-configuration notice, rerun with --scope user.

Orca is not an MCP client. Register the individual agents you launch from Orca using the table above — see Orca Integration.

Tool profiles

An MCP client loads the definitions (description + input schema) of every registered tool into context when a conversation starts. The more tools there are, the larger that fixed cost is from the very first request. A profile picks which set of tools the server exposes, which is how you control that cost.

Choose one with --tool-profile at registration time. Omitting it means full.

agentteams mcp install --client claude-code --tool-profile read
agentteams mcp config --client codex --tool-profile minimal

minimal is the smallest useful combination: search to find what exists, then read a plan or document in full. Its upfront definition cost is roughly 1/13 of full (measured 2026-08-05: 45,240 chars → 3,407 chars), but no list tools and no write tools are exposed. It is the wrong choice for work that needs exact counts or complete inventories.

A profile only sets the exposed surface. Narrowing it does not change server permissions or the project binding, and widening it does not grant permissions the caller did not already have.

Choosing a profile

Start by checking whether your client supports native tool discovery. Clients that do (recent Claude Code, for example) fetch definitions on demand, so full costs little upfront — measured on 2026-08-05 with Claude Code 2.1.220, registering all 30 tools added 628 input tokens to the first request, not the 10,906 tokens their definitions occupy. The output of agentteams mcp install / config reports per-client support along with the evidence link.

• Native discovery verified → leave full as is.
• Native discovery unsupported or unverified → pick read, documents, or comments to match the work you actually do, and use minimal when upfront cost matters most.

To change profiles, register the same client again with a different --tool-profile. The desktop app’s delegated runs use their own profile independently of this registration — see Desktop.

Cleaning up an existing registration

install updates an existing server of the same name or reports it as already registered; it never deletes a registration made at the other scope. To drop a user-scope registration, remove it with that client’s own removal command or settings UI.

If an older CLI left a registration carrying an API key or a project ID as environment values, and that value points at a different project than the current repository, the MCP server exits with a project binding mismatch before registering any tools. Remove that entry and re-run agentteams mcp install from the repository root to replace it with a value-free one.

Where the credentials live

An MCP registration entry carries no API key and no project or team ID. When the server runs it reads the repository’s .agentteams/config.json and your stored login — the OS credential store, or a file only your account can read when that store is unavailable. Nothing in a client config file is a secret, so sharing a registration never shares a credential.

If there is no login yet, connect the repository with agentteams init.

Troubleshooting

Manual registration

There is always a way back to doing it by hand, and config prints exactly that fragment.

agentteams mcp config --client claude-code --scope project

For Claude Code, for example, you can register directly:

claude mcp add agentteams --scope user -- agentteams mcp

If you edit an mcpServers-style JSON config by hand, the shape is:

{
  "mcpServers": {
    "agentteams": {
      "command": "agentteams",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Do not add credentials or a project ID when you write it by hand either. The server reads the repository configuration and your stored login at request time, so the shape above is already the complete entry.

Which runtime the entry spawns

agentteams mcp install / config prints which command it chose:

• Project scope always uses npx -y @agentteams/cli mcp. The file is committed and read on other people’s machines, so it must not encode what happens to be on the registering machine’s PATH.
• User scope uses agentteams mcp when a global agentteams is on PATH (npm install -g @agentteams/cli). This is the fast path: no download, no cold start.
• User scope falls back to npx -y @agentteams/cli mcp when it is not. Registering through npx @agentteams/cli mcp install without a global install lands here, as does any MCP client launched from a GUI that never inherits a login shell’s PATH.

If you write the config by hand and the client reports “server failed to start”, the bare executable is almost certainly not on the PATH that client sees. Either install the CLI globally or use the npx form:

{
  "mcpServers": {
    "agentteams": {
      "command": "npx",
      "args": ["-y", "@agentteams/cli", "mcp"],
      "env": {}
    }
  }
}