内容
# 受管代理控制 - MCP
**从任何MCP客户端启动、观察和与Claude受管代理交互** (Claude.ai, Claude Code, Cursor, `mcp-remote`, 您的自定义代理等).
[](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 受管代理在Anthropic的平台上运行 - 每个代理定义（模型、系统提示、工具、技能）都在沙盒环境中执行。
这个MCP服务器为这些代理提供了**远程控制**：将其连接到**任何MCP客户端**，即可启动代理、观察其操作、回复、批准其要运行的工具并停止它。Claude.ai是一个展示客户端（在普通对话中执行所有操作），但相同的工具也适用于Claude Code、Cursor、`mcp-remote`、MCP Inspector或自定义MCP客户端。 它是Terraform提供程序的运行时配套程序，**声明式**定义代理。
它作为本地 **stdio** 服务器、通用 **HTTP容器** 或在 **AWS Lambda** 上运行，具有可插拔的入站身份验证（静态 **bearer**、通用 **OIDC** 或AWS **Cognito**预设）。
> [!NOTE]
> 这是一个社区项目。它不是由Anthropic维护、支持或附属的。受管代理API是一个测试版API（`managed-agents-2026-04-01`）。
## 工作原理
```
MCP客户端 ──MCP──▶ 受管代理控制 - MCP ──HTTPS (x-api-key)──▶ 受管代理API
(Claude.ai, (此服务器：工具 + 身份验证) (代理在此处运行)
Claude Code, …)
```
您驱动一个循环：**发现** 代理 → **启动** 会话 → **观察** 通过轮询事件 → **交互** （回复 / 中断 / 批准工具）→ **结束**。
由于MCP工具调用是请求/响应，因此观察是通过轮询（`session_events` / `session_get`）进行的 - 没有实时流进入聊天。
## 快速入门（本地，<2分钟）
您需要具有受管代理访问权限的`ANTHROPIC_API_KEY`和 [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
# 通过stdio运行服务器：
ANTHROPIC_API_KEY=sk-ant-... uv run python -m managed_agents_mcp
```
使用MCP Inspector交互式地探索工具：
```bash
ANTHROPIC_API_KEY=sk-ant-... npx @modelcontextprotocol/inspector \
uv run python -m managed_agents_mcp
```
在 **Claude Code** 中注册它（包含了一个项目范围的 `.mcp.json`）：
```bash
claude mcp add managed-agent-control -- uv run python -m managed_agents_mcp
```
一旦发布到PyPI，您就可以跳过克隆：`uvx managed-agent-control-mcp`。
## 工具
| 层级 | 工具 | 功能 |
|------|------|------|
| Discover | `agent_list` / `agent_get` | 查找代理并检查其配置 |
| | `environment_list` / `environment_get` | 查找沙盒环境 |
| | `vault_list` / `vault_get` | 查找凭证保险库以在 `session_start` 时附加 |
| | `memory_store_list` / `memory_store_get` | 查找持久内存存储 |
| 启动 | `session_start` | 创建会话并（可选）发送第一个指令 |
| 观察 | `session_get` | 状态（`idle`/`running`/…）+ token使用情况 |
| | `session_list` | 列出会话 |
| | `session_events` | 轮询代理的输出/活动（光标 + 类型过滤） |
| 交互 | `session_message` | 发送消息 / 继续一轮 |
| | `session_interrupt` | 停止或重定向正在运行的代理 |
| | `session_respond` | 批准/拒绝代理正在等待的工具 |
| 破坏 🔒 | `session_archive` / `session_delete` | 存档（保留历史）或删除 |
参见 [`docs/tools.md`](docs/tools.md) 以获取每个参数和返回形状。
## 配置
仅 `ANTHROPIC_API_KEY` 是本地使用所必需的。完整参考参见 [`docs/configuration.md`](docs/configuration.md)。
| 环境变量 | 目的 |
|---|---|
| `ANTHROPIC_API_KEY` | **必填**。服务器操作的运算符密钥。 |
| `ANTHROPIC_BASE_URL` | 覆盖API基本URL（网关/测试）。 |
| `MCP_AUTH_MODE` | HTTP的入站身份验证：`bearer`、`oidc`、`cognito`（逗号分隔以组合）。 |
| `MCP_BEARER_TOKEN` | `bearer`模式的共享令牌。 |
| `MCP_OIDC_ISSUER` / `MCP_OIDC_JWKS_URL` / `MCP_OIDC_AUDIENCE` | `oidc`/`cognito`的JWT验证。 |
| `MCP_ALLOWLIST_AGENTS_ACTIVE` | `true`激活代理允许列表（默认关闭 → 允许所有代理）。 |
| `MCP_ALLOWED_AGENT_IDS` | 允许列表激活时，会话启动允许启动的代理。 |
| `MCP_ALLOW_DESTRUCTIVE` | `false`禁用存档/删除。 |
## 身份验证
有两个**独立**的身份验证层（设计上保持独立）：
- **出站** - 此服务器如何调用Anthropic：您的 `ANTHROPIC_API_KEY`。
- **入站** - MCP客户端如何向 **此服务器** 进行身份验证。可插拔且适用于任何HTTP部署：
- **bearer** - 共享静态令牌。最简单；适用于Claude.ai连接器和 `mcp-remote`。
- **oidc** - 验证任何OIDC提供者的JWT（Auth0、Okta、Keycloak、Entra、Cognito）。
- **cognito** - OIDC验证器加上Cognito需要的托管UI OAuth facade。
设置和Claude.ai连接器入站： [`docs/authentication.md`](docs/authentication.md).
> [!WARNING]
> 在设置入站身份验证模式之前，请勿公开HTTP部署。任何通过入站身份验证的人都可以驱动您的Anthropic密钥 - 请限定密钥范围并使用 [防护措施](docs/configuration.md#guardrails).
## 部署
| 目标 | 方法 |
|---|---|
| 本地（stdio） | `uv run python -m managed_agents_mcp` |
| 容器（HTTP） | `docker build -f deploy/Dockerfile -t macmcp . && docker run -p 8000:8000 …` |
| AWS Lambda | [`deploy/aws-lambda/`](deploy/aws-lambda/)中的自包含Terraform模块 |
详情： [`docs/deployment.md`](docs/deployment.md).
## 文档
- [配置](docs/configuration.md) — 每个环境变量 + 防护措施
- [身份验证](docs/authentication.md) — bearer / OIDC / Cognito + Claude.ai 设置
- [部署](docs/deployment.md) — 本地、容器、Lambda
- [架构](docs/architecture.md) — 模块映射、两个身份验证层、轮询模型
- [工具](docs/tools.md) — 完整的工具参考
- [示例](examples/) — 端到端部署演练（主机 + OAuth提供者）
## 贡献
欢迎贡献 - 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [行为准则](CODE_OF_CONDUCT.md)。发现安全问题？参见 [SECURITY.md](SECURITY.md).
## 许可证
MIT - 参见 [LICENSE](LICENSE). 由Andrei Svirida维护。
