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 internal entity types — plans, completion reports, co-actions, post-mortems, conventions, documents, code reviews, and comments — list them exactly within a project or known parent scope, and read the full records they select. Everything is read-only.

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 prints the project-scope detection result and plan for this repository without changing a single file.

agentteams mcp install

For each client you get the detection evidence, the target config file, and the strategy that would be used. A batch project-scope preview never writes files; choose one client to apply.

agentteams mcp install --client claude-code

If you truly need a machine-wide user-scope registration, preview and approve it explicitly.

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

Only --scope user --yes performs a batch user-scope apply. A batch apply with the default project scope is refused because the CLI cannot safely choose repository files for every client.

⚠️ A user-scope registration is machine-wide and binds the client to one AgentTeams project. If that client already has an agentteams server pointing at a different project, applying the plan re-points it. Check the project and team IDs in the preview output first.

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 has no safe automated path, so paste the TOML fragment that config prints. The target config file for each scope is listed in MCP Tools.

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

Migrating an existing user-scope registration

User-scope registrations created under the old default are not deleted or overwritten automatically. Migrate each repository as follows:

1. From the repository root, run agentteams mcp install and verify the project-scope plan plus its project and team IDs.
2. Apply agentteams mcp install --client <client> for that repository, or manually apply the fragment from agentteams mcp config --client <client>.
3. After the client loads the project config successfully, remove the old user-scope agentteams server with that client’s own removal command or settings UI.

If an existing user-scope server is bound to a different project than the current repository, the MCP server exits with a project binding mismatch before registering any search/list/get tools. Check the local and bound project IDs in the error and re-register from the current repository at project scope.

Required environment variables

Agent CLIs spawn the MCP server from an arbitrary working directory, so the three values below must be carried by the server config itself rather than by a project-folder config file.

Key handling differs per scope.

• User scope — automatic registration writes the literal key and restricts the config file to owner-only permissions.
• Project scope — committable files carry only an environment reference. Set the key in your shell environment beforehand.

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": {}
    }
  }
}

No credentials or project binding go into the entry. The server reads .agentteams/config.json and the OS credential store at request time, so nothing in an MCP config file is a secret.

Which runtime the entry spawns

agentteams mcp install / config picks the command from what your machine can actually spawn, and prints which one it chose:

• agentteams mcp — used when a global agentteams is on PATH (npm install -g @agentteams/cli). This is the fast path: no download, no cold start.
• npx -y @agentteams/cli mcp — used 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": {}
    }
  }
}