1MCP - One MCP Server for All

1MCP

1MCP 是统一的 MCP 运行时。1mcp serve 可聚合你的 MCP 服务，而 CLI 模式则为 Codex、Claude、Cursor 以及类似的工具调用型 Agent 提供更轻量的面向 Agent 工作流。

为什么选择 1MCP

大多数 MCP 配置最终都会面临两类扩张问题：

• 配置扩张：每个客户端都需要单独配置 MCP、选择身份验证方式并设置筛选规则。
• Agent 扩张：自主会话一开始就将过多工具和架构带入上下文。

1MCP 可同时解决这两个问题：

• 1mcp serve 可在多个 MCP 服务前提供一个聚合运行时。
• CLI 模式让 Agent 通过 instructions、inspect 和 run 逐步发现工具。
• 静态服务可在启动时加载，而模板服务则根据每个客户端或会话的上下文创建。
• 预设、筛选器和指令聚合让同一运行时能够适配不同的客户端和项目。

方案	最适合	权衡
1MCP CLI 模式	Codex、Claude、Agent 循环	需要运行中的 1mcp serve 实例
1MCP stdio 代理	在不同客户端之间实现最大兼容性	仍依赖 serve，且支持身份验证的 HTTP 客户端有更直接的接入方式
直接使用 streamable HTTP	MCP 原生 HTTP 客户端	没有项目上下文、不支持 .1mcprc，且会直接暴露更多工具
自定义代理	一次性兼容性垫片	你需要自行负责发现、筛选、身份验证和运行时生命周期

面向 Agent 用户的快速入门

本页面针对 AI Agent 用户进行了优化。5 分钟即可完成：启动真正的 1mcp serve 运行时，通过 cli-setup 连接 Agent，然后验证 instructions -> inspect -> run 工作流。

**你 — 设置：**安装 1MCP，添加一个上游服务并启动运行时：

npm install -g @1mcp/agent
1mcp mcp add context7 -- npx -y @upstash/context7-mcp
1mcp serve

**你 — 客户端设置：**在另一个 Shell 中，将 Agent 连接到 CLI 模式：

1mcp cli-setup --codex
# or
1mcp cli-setup --claude --scope repo --repo-root .

**AI Agent — 启动后：**遵循此工作流；如果钩子已传递当前指令，则跳过 instructions。保持上方的运行时继续运行；你无需手动重复执行这些 Agent 命令。请确认启动过程已传递指导信息并建立会话所有权。对于已命名或自动发现的本地运行时，受支持的 Codex 会话会自动解析其所有者和分配的项目。Claude 以及不支持自动查找所有者的宿主需要在下方命令中添加各自的引导参数 --project-owner <own-file>；每个工作进程使用自己的凭据。

# Only if current target guidance is missing or needs refreshing:
1mcp instructions
1mcp inspect context7
1mcp inspect context7/query-docs
1mcp run context7/query-docs --args '{"libraryId":"/mongodb/docs","query":"aggregation pipeline"}'

如需查看完整演练（含成功标准和退出选项），请使用快速入门指南。

对于指定的 Agent，只选择一种模式。如果将该 Agent 切换到 CLI 模式，请先移除其旧的直接 MCP 配置。

跨项目和工作树工作

在多个仓库和 Git 工作树之间使用同一个本地运行时。使用 mcp setup 配置已安装的后端后，Agent 会在每次调用时选择一个检出目录：

1mcp inspect codegraph --project /absolute/checkout

对于会话分配的检出目录，请省略 --project；显式覆盖不会更改该默认值。有关设置、项目集、独立工作器、可选准备和安全清理，请参阅跨项目和工作树工作（中文）。

CLI 模式的用途

CLI 模式是 Agent 风格会话的主要工作流。它保留 MCP 作为后端协议，同时缩小 Agent 在每个步骤中看到的范围：

• instructions 用于说明当前运行时和推荐的工作流
• inspect 让 Agent 仅发现所需的服务或工具
• run 在检查架构后执行选定的工具

这样，Agent 循环就能缩小工作范围，同时仍使用 1mcp serve 背后的统一运行时。

选择其他方式

Stdio 代理

如果你希望获得最广泛的客户端兼容性，同时保留项目上下文，请使用 1mcp proxy。

CLI 模式之后，建议优先选择此备用方式，因为它：

• 使用大多数 AI 客户端已支持的 stdio 传输
• 通过 .1mcprc 保留项目上下文
• 支持根据项目或会话上下文解析的模板 MCP 服务
• 通过一次性全局设置和逐项目配置，更易于推广

不建议使用直接 stdio 模式。它主要适用于调试，因为 1MCP 的启动速度比精简的独立 stdio 设置慢。

直接连接 MCP

仍支持直接连接 MCP，以便客户端通过可流式 HTTP 与聚合运行时通信。

示例：

{
  "mcpServers": {
    "1mcp": {
      "url": "http://127.0.0.1:3050/mcp?app=cursor"
    }
  }
}

claude mcp add -t http 1mcp "http://127.0.0.1:3050/mcp?app=claude-code"

如果你的客户端原生支持 MCP、无需项目上下文即可工作，且你不想使用 CLI 模式，请选择此方式。对于 Codex、Claude、Cursor 等 Agent 循环，建议优先使用 CLI 模式，其次使用 proxy。

运行时运维人员

如果你要配置或部署运行时本身，请参阅更深入的文档：

• 配置
• 身份验证
• 架构

贡献者

• 开发指南
• CONTRIBUTING.md

工作原理

flowchart LR
    A[User or Agent] --> B[1mcp serve]
    B --> C[Static servers loaded at startup]
    B --> D[Template servers resolved from client or session context]
    A --> E[CLI mode: instructions -> inspect -> run]
    E --> B
    F[Direct streamable HTTP client] --> B
    G[stdio-compatible client] --> H[1mcp proxy]
    H --> B

1MCP 作为聚合运行时，在 1mcp serve 后运行。静态服务根据启动配置准备；模板服务则在客户端上下文已知时实例化；运行时还可以使用异步加载，以便尽早启动 HTTP 监听器，并使用延迟加载来保持稳定的工具界面。指令聚合、预设和通知都与该运行时并行工作，而非置于其外部。

延迟加载是一种选择启用的稳定工具界面兼容模式。它将后端发现和调用界面限制为 tool_list、tool_schema 和 tool_invoke，让具备相应能力的 Agent 可以逐步发现工具，同时不替换其 MCP 工具表。任何显式启用的内部管理工具仍会直接公开。延迟加载可减少初始架构载荷，但不会减少后端连接或进程，不会让同步启动时更早绑定，也无法修复孤立的代理进程。有关异步模式下服务器延迟可见性的约定，请参阅 #392。

核心能力

• 通过一个 serve 进程，为多个 MCP 服务提供统一运行时
• 命令行模式支持渐进式发现，可使用 1mcp instructions、1mcp inspect <server>、1mcp inspect <server>/<tool> 和 1mcp run <server>/<tool> --args '<json>'
• 模板服务可按客户端或会话解析
• 可选择启用异步加载，让 HTTP 监听器尽早启动，适用于能够协调能力变更的客户端
• 可选择启用延迟加载，提供稳定的渐进式发现工具界面，并缩小初始模式
• 可选择为自有 stdio 后端启用自动恢复，并提供健康状况／状态可见性和运维人员重启控制
• 聚合静态服务和由模板提供的服务中的指令
• 预设、过滤器和预设变更通知
• proxy 可实现最高兼容性，并支持项目上下文和模板服务
• 为无需项目上下文的原生 HTTP 客户端提供直接的可流式 HTTP MCP 访问

常见用例

• 为编码 Agent 提供一个稳定的运行时，同时缩小其工作界面。
• 在 Cursor、Claude Code、Codex 和内部工具之间共享同一套 MCP 清单。
• 按仓库、分支或会话公开特定上下文的模板服务。
• 集中管理身份验证、过滤器、预设和运行时生命周期，而不是用临时脚本重复构建。

贡献／许可证

欢迎贡献。开发工作流请参阅 CONTRIBUTING.md，Apache 2.0 许可证请参阅 LICENSE。