scoped-mcp Skill 技能

scoped-mcp — 多 Agent MCP 工具隔离代理

技能简介

scoped-mcp 是由开发者 TadMSTR 开源的 Python 工具，专为多 Agent 环境下的 MCP 工具隔离而设计。在实际生产中，Claude Code 的多 Agent 协作（子 Agent、并行 Worker、基于角色的 Agent）往往共享同一个 MCP 服务器，导致一个 Agent 能看到并调用所有其他 Agent 的工具和凭据——这既是安全风险，也是维护噩梦。scoped-mcp 通过为每个 Agent 运行独立的代理进程来解决这个问题：它基于 Agent 身份（AGENT_ID + AGENT_TYPE）加载对应的工具清单（Manifest），仅注册该 Agent 被允许使用的工具模块，凭据对 Agent 完全隔离，每次工具调用均有结构化审计日志。该项目专为 Claude Code 多 Agent 场景构建，已在生产环境的 homelab-agent 平台中实际运行，MIT 许可证开源。

核心能力

1. 每 Agent 独立进程：每个 Agent 拥有独立的 scoped-mcp 进程进程，加载独立的工具清单，进程级隔离。
2. 工具过滤（Tool Filtering）：通过 Manifest 文件定义每个 Agent 类型允许使用的工具模块，Agent 只能看到并调用白名单内的工具。
3. 凭据注入隔离：凭据在工具执行时由 scoped-mcp 进程注入到工具模块，Agent 进程本身不持有任何凭据，真正实现凭据对 Agent 不可见。
4. 资源作用域（Resource Scoping）：每个 Agent 的工具调用被限制在特定资源范围内（如只读写 agents/research-01/ 目录下的文件）。
5. 结构化审计日志：每次工具调用均写入 JSONL 格式审计日志，记录调用者身份、工具名、参数、时间和结果。
6. 双传输模式：支持 stdio（每次新建子进程，适合 Claude Code 标准集成）和 HTTP Streamable（长驻进程，适合 PM2 管理的高可用场景）。
7. MCP 协议原生：完全兼容 Model Context Protocol，与 Claude Code、MCP 客户端开箱即用。
8. Bearer Token 认证（HTTP 模式）：HTTP 传输模式下使用恒定时间比较的 Bearer Token 认证，防止时序攻击。
9. Session ID 映射：HTTP 长驻模式下，将 MCP session id 映射为稳定 UUID，防止审计日志串线。
10. 健康状态检查：内置 scoped_mcp_status 工具，Manifest 文件变更后自动标记 manifest_stale: true。

安装配置

基础安装

pip install scoped-mcp

配置文件准备 创建 manifests/research-agent.yml（按 Agent 类型定义工具清单）：

agent_type: research
tools:
  - module: filesystem
    scope:
      base_path: agents/research-01/
  - module: database
    scope:
      db_path: agent_research-01.db
credentials:
  - name: OPENAI_API_KEY
    source: env

Claude Code settings.json 配置（stdio 模式）

{
  "mcpServers": {
    "tools": {
      "command": "scoped-mcp",
      "args": ["--manifest", "manifests/research-agent.yml"],
      "env": {
        "AGENT_ID": "research-01",
        "AGENT_TYPE": "research"
      }
    }
  }
}

HTTP 模式（PM2 长驻）

export AGENT_ID="research-01"
export AGENT_TYPE="research"
export SCOPED_MCP_BEARER_TOKEN="$(openssl rand -hex 32)"
scoped-mcp run --manifest manifests/research-agent.yml --transport http --port 9200 --path /mcp

使用步骤

第一步：确定 Agent 身份和类型

export AGENT_ID="research-01"
export AGENT_TYPE="research"

第二步：准备工具模块 每个工具域对应一个 Python 文件，在模块中声明工具函数和所需凭据。

第三步：启动 scoped-mcp 代理

scoped-mcp --manifest manifests/research-agent.yml

第四步：在 Claude Code 中使用 Claude Code 根据 settings.json 中的 AGENT_ID 和 AGENT_TYPE 自动连接到对应的 scoped-mcp 代理。

第五步：审计日志分析 JSONL 格式审计日志示例：

{"timestamp":"2026-09-08T14:00:00Z","agent_id":"research-01","tool":"read_file","status":"success"}

适用场景

1. Claude Code 多 Agent 平台：自托管 Claude Code 平台，同时运行研究 Agent、代码 Agent、写作 Agent，每个 Agent 访问不同的工具和数据。
2. 企业 AI Agent 安全隔离：防止恶意或误操作的 Agent 访问不该访问的工具和凭据，实现最小权限原则。
3. 多租户 AI Agent 服务：多个租户的 Agent 共享基础设施，通过 scoped-mcp 实现租户间工具和凭据的严格隔离。
4. AI Agent 合规审计：金融、医疗等受监管行业，需要记录每次 AI 工具调用的详细审计轨迹。
5. AI Agent 开发调试：在开发阶段限制 Agent 可用工具，快速定位 Agent 用了什么工具出了什么问题。
6. 隐私敏感数据保护：确保 Agent 只能访问当前任务所需的最少数据，最大限度降低数据泄露风险。

适用人群

• Claude Code 平台管理员：自建 Claude Code 多 Agent 环境的运维人员。
• AI 安全工程师：关注 Agent 间隔离和凭据安全的开发者。
• 企业 AI 平台架构师：设计多租户 AI Agent 系统的技术负责人。
• 合规团队：需要 AI Agent 操作审计轨迹的合规/风控人员。

工作原理

scoped-mcp 运行在 MCP 客户端（Claude Code）和 MCP 服务器（真实后端服务）之间，形成代理层。当 Agent 启动时，scoped-mcp 根据 AGENT_ID（Agent 实例唯一标识）和 AGENT_TYPE（Agent 角色类型）从 Manifest 文件加载该 Agent 类型允许的工具模块列表。工具调用请求到达 scoped-mcp 后，依次经过：资源范围校验 → 凭据注入 → 工具执行 → 审计日志写入 → 结果返回 Agent。每次调用均在独立进程中完成（stdio 模式）或独立 HTTP 连接中完成（HTTP 模式），进程/连接隔离确保 Agent 间无共享状态。

官方链接

• PyPI：https://pypi.org/project/scoped-mcp/
• GitHub：https://github.com/TadMSTR/scoped-mcp
• homelab-agent 生产案例：https://github.com/TadMSTR/homelab-agent