Connect an external AI agent to Agent Teams
Agent Teams is a local desktop app, not a hosted agent API. Its built-in MCP server can let an external local Claude Code or Codex client manage team drafts in the running app. This is different from adding an external MCP tool to a team.
Prerequisites
- Install Agent Teams on macOS, Windows or Linux and open the desktop app.
- Use a local Claude Code or Codex CLI that can register an MCP Streamable HTTP server. An authenticated runtime may be needed for that client's own model calls; Agent Teams does not require its own signup.
- In Agent Teams Settings → External agent connection, check that MCP and control are both ready. The URL is generated by the running app. If not ready, use Retry connection and follow the displayed recovery instructions.
A ready endpoint is not proof that an external client has connected. Do not try to connect to agentteams.live or api.agentteams.live as an MCP service.
Recommended: use the app-generated instructions
- From the desktop team list, open Manage teams with a prompt.
- Describe the team or configuration change you want.
- Use Copy to obtain the current MCP endpoint, the supported client registration command, the app/root identity checks, and the intended operation limits.
- Run only the command for your client in a terminal on the same computer. The generated prompt includes:
- Claude Code:
claude mcp add --transport http --scope user <server-name> <app-mcp-url> - Codex:
codex mcp add <server-name> --url <app-mcp-url>
- Claude Code:
- Start a fresh client session/reload if the client does not hot-discover newly registered tools. In the client, confirm the
agent-teamstools are actually available, then callapp_get_connection_info. - Compare the live
appInstanceIdanddataRootFingerprintto the copied prompt before any mutation. If either differs, get a new prompt from the app. If only the generation changed, use the generation returned by live discovery.
<server-name> and <app-mcp-url> are placeholders: use the exact values from the running app, not those literal strings. On Windows use the quoting syntax of your shell.
What this connection can do
The management MCP scope currently supports:
| Operation | MCP tool | Restriction |
|---|---|---|
| Discover the app | app_get_connection_info | Verify the current app and data root |
| List/read teams | team_list, team_get | Read live state, do not infer it from a prompt |
| Save a team draft | team_create | Supply current expectedContext, runtimeSelectionVersion: 1; no automatic launch |
| Edit team configuration | team_update | Only when capability is available, team is draft/stopped; use fresh configuration revision |
| Move a team to Trash | team_trash | Only when capability is available, reversible; no permanent delete |
The management interface does not grant external clients automatic team launch, stop, task execution, shell access, unrestricted file modification, restoration or permanent deletion. Use the current capability snapshot rather than assuming every optional tool exists. The app also offers Run in Codex or Run in Claude Code in its desktop prompt dialog if the native client is ready; that is an app-owned local one-shot run, not a public API.
For task/board coordination inside a launched team, see the separate built-in board MCP tools.
Failure and security cases
- Cloud-only agent: it cannot call the app's loopback URL without a local executor with access to the running desktop. Copying text into a web chat does not create the connection.
- Endpoint changed or app restarted: get new connection details and re-register if the old URL no longer works. Never reuse stale app/root identity for writes.
- MCP tool absent: check the CLI's MCP registration and session reload first; a successful
mcp addcommand alone does not establish a connected client. - Write times out: read the original team by its canonical name before retrying; do not blindly create duplicates.
- Renderer CDP: optional and off by default. It provides powerful full renderer/preload access, unlike scoped MCP tools. Do not enable it merely to create drafts, and do not expose the loopback listener publicly.
- Provider secrets: authenticate with the provider's native CLI/config. Never put keys or tokens in team prompts, links, or public MCP registration snippets.