统一的 MCP 运行时，将多个上游 MCP 服务器聚合为单一入口，提供 CLI、stdio 代理和原生 HTTP 接入能力。
1MCP Agent 是一个基于 TypeScript 构建的统一 Model Context Protocol (MCP) 运行时，旨在解决多客户端环境下 MCP 服务器配置碎片化与生命周期管理复杂的问题。该项目将多个上游 MCP 服务器聚合到一个 1mcp serve 进程后，提供四种接入模式：为 AI 代理设计的渐进式 CLI 模式（通过 instructions/inspect/run 收窄工具面）、最大兼容性的 stdio 代理模式、原生 Streamable HTTP 直连模式，以及自定义代理模式。
在核心聚合能力上，1MCP Agent 区分了静态服务器与基于项目上下文（.1mcprc）动态创建的模板服务器，并支持异步加载与工具级懒加载。运行时内置了跨服务器的指令聚合、可切换的预设系统以及按客户端/项目维度的过滤系统。为满足生产级需求，该运行时集成了 OAuth 认证、速率限制以及基于 tiktoken 的 Token 统计。项目支持 Docker 容器化部署及 Node.js SEA 单文件二进制编译，具备完善的跨平台（含 ARM64）运行能力。
架构概述#
采用两层结构：底层为长生命周期的聚合运行时（1mcp serve），负责配置加载、客户端路由和后端服务器管理；上层为CLI 渐进式代理接口，与运行时交互实现工具发现与执行。
核心组件包括：
- Aggregated Runtime：核心长驻进程，管理配置、路由、传输层及后端服务器。
- Server Manager：跟踪出站服务器连接与入站客户端会话。
- Instruction Aggregation：实现跨静态/模板服务器的指令合并。
- Template Server Manager：读取上下文配置（
.1mcprc）动态实例化 MCP 服务器，支持共享或独立会话作用域。 - Preset Manager：处理工具集预设的初始化及运行时变更通知。
CLI 命令集#
1mcp serve：启动聚合运行时1mcp proxy：启动 stdio 到 HTTP 的代理1mcp instructions：获取当前运行时状态与推荐流程1mcp inspect <server>[/<tool>]：发现服务器或查看工具 Schema1mcp run <server>/<tool> --args '<json>'：执行指定工具1mcp mcp add <name> -- <cmd>：添加上游 MCP 服务器1mcp cli-setup --codex|--claude：快速配置 AI 代理环境
配置文件体系#
config.toml：核心配置，定义静态服务器、模板及预设.1mcprc：项目级上下文配置，用于模板服务器动态渲染.env：环境变量与密钥配置mcp.json：MCP 服务器连接定义
快速开始#
npm install -g @1mcp/agent
1mcp mcp add context7 -- npx -y @upstash/context7-mcp
1mcp serve
连接代理（另开终端）：
1mcp cli-setup --codex
# 或
1mcp cli-setup --claude --scope repo --repo-root .
验证工作流：
1mcp instructions
1mcp inspect context7
1mcp run context7/query-docs --args '{"libraryId":"/mongodb/docs","query":"aggregation pipeline"}'
典型场景#
- 编码代理统一工具入口：给 Codex、Claude Code、Cursor 等代理一个稳定的运行时，同时通过 CLI 模式收窄工作面
- 多客户端共享 MCP 配置：同一套 MCP 服务器清单跨 Cursor、Claude Code、Codex 和内部工具共享
- 按仓库/分支/会话暴露上下文工具：通过模板服务器为不同项目动态创建 MCP 服务器
- 集中化认证与生命周期管理：统一处理 auth、过滤、预设和运行时生命周期
- 团队/生产部署：支持认证、Docker 部署、速率限制等运维特性
生态集成#
- 基于
@modelcontextprotocol/sdk ^1.25.1构建，可直接聚合任意兼容 MCP 的上游服务 - 原生适配 OpenAI Codex、Anthropic Claude Code、Cursor 等主流编码代理
- 仓库内含
smithery.yaml，支持通过 Smithery 平台进行部署集成
当前版本 v0.31.0（68 releases），采用 Apache-2.0 许可证，主要语言为 TypeScript（98%），支持 Node.js 18+。