managed-agent-control-mcp

# managed-agent-control-mcp **Start, observe, and interact with [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents) from any MCP client** (Claude.ai, Claude Code, Cursor, `mcp-remote`, your own agent, …). [](https://github.com/modus-agendi/managed-agent-control-mcp/actions/workflows/ci.yml) [](https://pypi.org/project/managed-agent-control-mcp/) [](pyproject.toml) [](LICENSE) Claude Managed Agents run on Anthropic's platform — each is an agent definition (model, system prompt, tools, skills) that executes inside a sandbox environment. This MCP server puts a **remote control** on those agents: connect it to **any MCP client** and you can launch an agent, watch what it does, reply to it, approve the tools it wants to run, and stop it. Claude.ai is the showcase client (do it all from a normal conversation), but the same tools work from Claude Code, Cursor, `mcp-remote`, the MCP Inspector, or a custom MCP client. It is the runtime companion to the [Terraform provider](https://github.com/modus-agendi/terraform-provider-anthropic-claude-managed-agents) that *defines* agents declaratively. It runs as a local **stdio** server, a generic **HTTP container**, or on **AWS Lambda**, with pluggable inbound auth (static **bearer**, generic **OIDC**, or an AWS **Cognito** preset). > [!NOTE] > This is a community project. It is not maintained by, endorsed by, or affiliated > with Anthropic. The Managed Agents API is a beta API (`managed-agents-2026-04-01`). ## How it works ``` MCP client ──MCP──▶ managed-agent-control-mcp ──HTTPS (x-api-key)──▶ Managed Agents API (Claude.ai, (this server: tools + auth) (agents run here) Claude Code, …) ``` You drive a loop: **discover** an agent → **start** a session → **observe** by polling events → **interact** (reply / interrupt / approve tools) → **end**. Because MCP tool calls are request/response, observation is by polling (`session_events` / `session_get`) — there is no live stream into the chat. ## Quickstart (local, <2 min) You need an `ANTHROPIC_API_KEY` with Managed Agents access and [uv](https://docs.astral.sh/uv/). ```bash git clone https://github.com/modus-agendi/managed-agent-control-mcp cd managed-agent-control-mcp uv sync # Run the server over stdio: ANTHROPIC_API_KEY=sk-ant-... uv run python -m managed_agents_mcp ``` Explore the tools interactively with the MCP Inspector: ```bash ANTHROPIC_API_KEY=sk-ant-... npx @modelcontextprotocol/inspector \ uv run python -m managed_agents_mcp ``` Register it with **Claude Code** (a project-scoped `.mcp.json` is included): ```bash claude mcp add managed-agent-control -- uv run python -m managed_agents_mcp ``` Once published to PyPI, you can skip the clone: `uvx managed-agent-control-mcp`. ## Tools | Tier | Tool | Does | |------|------|------| | Discover | `agent_list` / `agent_get` | Find an agent and inspect its config | | | `environment_list` / `environment_get` | Find a sandbox environment | | | `vault_list` / `vault_get` | Find a credential vault to attach at `session_start` | | | `memory_store_list` / `memory_store_get` | Find a persistent memory store | | Start | `session_start` | Create a session and (optionally) send the first instruction | | Observe | `session_get` | Status (`idle`/`running`/…) + token usage | | | `session_list` | List sessions | | | `session_events` | Poll the agent's output/activity (cursor + type filter) | | Interact | `session_message` | Send a message / continue a turn | | | `session_interrupt` | Stop or redirect a running agent | | | `session_respond` | Approve/deny a tool the agent is waiting on | | Destructive 🔒 | `session_archive` / `session_delete` | Archive (keep history) or delete | See [`docs/tools.md`](docs/tools.md) for every argument and return shape. ## Configuration Only `ANTHROPIC_API_KEY` is required for local use. Full reference in [`docs/configuration.md`](docs/configuration.md). | Env var | Purpose | |---|---| | `ANTHROPIC_API_KEY` | **Required.** Operator key the server acts with. | | `ANTHROPIC_BASE_URL` | Override the API base URL (gateways/testing). | | `MCP_AUTH_MODE` | Inbound auth for HTTP: `bearer`, `oidc`, `cognito` (comma-separated to combine). | | `MCP_BEARER_TOKEN` | Shared token for `bearer` mode. | | `MCP_OIDC_ISSUER` / `MCP_OIDC_JWKS_URL` / `MCP_OIDC_AUDIENCE` | JWT verification for `oidc`/`cognito`. | | `MCP_ALLOWLIST_AGENTS_ACTIVE` | `true` activates the agent allowlist (default off → all agents allowed). | | `MCP_ALLOWED_AGENT_IDS` | Agents `session_start` may launch when the allowlist is active. | | `MCP_ALLOW_DESTRUCTIVE` | `false` disables archive/delete. | ## Authentication There are **two** auth layers (kept separate by design): - **Outbound** — how this server calls Anthropic: your `ANTHROPIC_API_KEY`. - **Inbound** — how MCP clients authenticate *to this server*. Pluggable and required for any HTTP deployment: - **bearer** — a shared static token. Simplest; works with Claude.ai connectors and `mcp-remote`. - **oidc** — verify JWTs from any OIDC provider (Auth0, Okta, Keycloak, Entra, Cognito). - **cognito** — the OIDC verifier plus the hosted-UI OAuth facade Cognito needs. Setup and Claude.ai connector onboarding: [`docs/authentication.md`](docs/authentication.md). > [!WARNING] > Never expose an HTTP deployment without an inbound auth mode set. Anyone who > passes inbound auth can drive your Anthropic key — scope the key and use the > [guardrails](docs/configuration.md#guardrails). ## Deployment | Target | How | |---|---| | Local (stdio) | `uv run python -m managed_agents_mcp` | | Container (HTTP) | `docker build -f deploy/Dockerfile -t macmcp . && docker run -p 8000:8000 …` | | AWS Lambda | Self-contained Terraform module in [`deploy/aws-lambda/`](deploy/aws-lambda/) | Details: [`docs/deployment.md`](docs/deployment.md). ## Documentation - [Configuration](docs/configuration.md) — every env var + guardrails - [Authentication](docs/authentication.md) — bearer / OIDC / Cognito + Claude.ai setup - [Deployment](docs/deployment.md) — local, container, Lambda - [Architecture](docs/architecture.md) — module map, the two auth layers, the polling model - [Tools](docs/tools.md) — full tool reference - [Examples](examples/) — end-to-end deployment walkthroughs (host + OAuth provider) ## Contributing Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md). Found a security issue? See [SECURITY.md](SECURITY.md). ## License MIT — see [LICENSE](LICENSE). Maintained by Andrei Svirida.