cortex-gateway

# Cortex 网关 [](https://github.com/wellknownmcp/cortex-gateway/actions/workflows/ci.yml) [](https://github.com/wellknownmcp/cortex-gateway/actions/workflows/docker.yml) [](LICENSE) **一个联邦式 MCP 网关：一个符合规范、受 OAuth 保护的 MCP 服务器，位于 N 个纯 HTTP 后端之前。** 您的业务应用程序保持为普通的 Web 服务。每个应用程序都暴露一个单独的 `POST /api/cortex/backend` 端点（一个约 120 行的合约，无 MCP 库，无标准输入/输出）。网关发现他们的工具，将它们合并成一个 MCP 目录，强制执行 OAuth 2.1 + 范围，路由 `tools/call` 到所属后端，并保持一个匿名审计轨迹。 为一个需求而构建：公司中的每个人都应该能够将他们自己的代理人交给他们 - 使用该人的确切权限，不多不少。而当代理人成为自主助手时，答案保持不变：代理人借用该人的身份，应用程序继续执行该人的权限。网关不会做出任何决定，因此没有什么新的东西需要信任。 换句话说：**AI 代理的零信任原则** - 连接您的身份和访问管理（IAM，您的用户是谁，他们可以做什么）和 MCP 生态系统（代理如何调用工具）。不是一个完整的 ZTNA 产品；代理的身份和访问层。 一个**后端**是一个专用的 MCP，简化为其实质：一个工具目录加上工具调用（和可选的提示/资源）通过纯 HTTP JSON-RPC - 传输和生命周期机制（初始化，会话，SSE，版本协商）一次生活在网关中。因为合约是 MCP 的语义子集，所以本地 MCP 服务器也可以通过内置的 MCP→后端代理适配器（[docs/mcp-adapter.md](docs/mcp-adapter.md)）进行联合。 ``` [MCP 代理：Claude Desktop / claude.ai 自定义连接器 / 任何 MCP 客户端] │ HTTPS + OAuth 2.1 JWT（Bearer） ▼ [cortex-gateway] ←— 薄网关，无业务逻辑 │ HTTPS + 相同的 JWT 传播（RFC 8707） ▼ [您的后端] ←— 域所有者，纯 HTTP，他们拥有自己的 ACL ``` ## 为什么 - **权限与底层应用程序匹配，自动，在用户级别。** 网关从不复制或镜像权限 - 它传播真正的用户身份（您的 JWT 到第一方后端，用户自己的链接令牌到代理的第三方 MCP 服务器），因此每个应用程序的本地权限模型按用户应用，没有任何同步和服务帐户扁平化。像托管工具聚合器一样，令牌保险库和审计轨迹保留在您的基础设施上。 - **一个周界，而不是 N 个连接器。** 将每个应用程序作为其自己的 MCP 连接器也保留原生权限 - 并为您留下 N 个同意，N 个令牌存储，没有共享审计，没有跨应用程序权限，以及一个泛滥的工具列表。网关将这些合并为一个 OAuth 接口，而不放弃按用户模型：聚合而没有权限损失。 - **应用程序中没有 MCP 锁定。** 后端通过纯 HTTP 讲一个最小的 JSON-RPC 合约。删除网关，您仍然可以直接调用它们（测试，批处理作业，其他集成）。 - **一个 JWT，N 个后端。** 代理一次验证；网关传播令牌；每个后端重新验证它并应用自己的权限。授权服务器的撤销将影响所有操作。 - **故障隔离。** 一个无法访问的后端只是从 `tools/list` 中消失；其余部分继续工作。 - **上下文感知联合。** 后端过滤和紧凑的“搜索”模式使工具目录不会淹没代理的上下文（[docs/tool-search-mode.md](docs/tool-search-mode.md)）。 - **代理反馈循环。** 代理可以提交 `report_missing_capability` 票据，当工具缺失或不足时 - 去重，分类， 可选地推送到 Webhook。 ## 用例 **公司范围的代理界面。** 一个组织运行 N 个内部应用程序（CRM，质量文档，计费，分析...）。每个应用程序添加约 120 行的后端端点；网关将它们暴露为一个受公司 SSO 保护的 MCP 连接器。员工将一个 URL 插入 Claude Desktop / claude.ai 并获得他们令牌范围允许的工具，具有中央审计轨迹。这是网关诞生的设置。 **产品构建器。** 您发布多个产品，并希望代理（您的或客户的）来操作它们。每个产品实现后端合约，网关是您的单个，版本化，受 OAuth 保护的代理 API。向代理界面添加产品是一个环境变量。 **主题中心/精选注册表。** 将网关运行为一个*主题*端点 - 例如“域 X 的所有开放数据工具” - 在一个 URL 后联合多个提供商，具有一个令牌。范围模型为您提供每个提供商的按需选择，`get_help`/`get_snapshot` 为代理提供自描述发现，审计轨迹告诉您实际使用的内容。提供商要么原生地讲（故意很小的）后端合约，要么 - 对于现成的 MCP 服务器 - 通过内置的 MCP→后端代理适配器（[docs/mcp-adapter.md](docs/mcp-adapter.md)）进行前端。 **免费/付费工具层。** 范围是权限。让您的授权服务器授予 `mcp:yourapp:basic` 给免费用户和 `mcp:yourapp:pro` 给付费用户（您的计费 Webhook 更新授予）：网关然后显示和允许每个调用者确切的计划工具 - 网关或后端中没有付费逻辑，工具只需声明其范围。撤销和降级通过正常的 OAuth 链传播。 ## 联邦原生 MCP 服务器（适配器，测试中） 内置的 **MCP→后端代理适配器** 允许捆绑混合合约后端和现成使用的原生 MCP 服务器（Canva，Figma，...）：适配器是 MCP 客户端下游（初始化，会话，SSE 分帧）和纯后端上游，因此网关核心不会改变。按用户下游 OAuth 由 **令牌保险库** （静息时使用 AES-256-GCM）和 **链接流程** （RFC 9728 发现，动态客户端注册，PKCE）处理；每个用户只需为每个提供商同意一次，然后代理在整个捆绑中使用单个 Cortex 令牌。参见 [docs/mcp-adapter.md](docs/mcp-adapter.md) 以获取一个工作“设计捆绑”示例（Canva + Figma + 您自己的后端）。 ## 路线图 - **用于发现的机器身份** - 用 `client_credentials` 流替换静态技术令牌，一旦您的 AS 支持它。 - **共享事件总线/速率限制存储** - 用于多实例部署。 ## 功能 - MCP 规范 **2025-06-18** （可流式传输的 HTTP 传输：POST JSON-RPC，GET SSE 用于 `listChanged` 通知，DELETE 会话终止） - 原语：**工具**，**资源** （包括 URI 模板），**提示** - **OAuth 2.1 资源服务器**：JWKS 验证，每个资源的受众（RFC 8707），受保护资源元数据（RFC 9728），可选的 RFC 7662 内省用于撤销 - **基于范围的可见性**：代理仅看到（并且可以调用）令牌范围允许的工具；在发现中，`scopes_supported` 从联合目录中实时派生 - **动态发现**：后端每 60 秒轮询；新工具出现，无需重新部署网关，并使用 SSE `tools/list_changed` 推送 - **内置**: `whoami` （跨后端的聚合身份），`find_tools`，`report_missing_capability`，`list_cortex_tickets`，`list_cortex_resources`，`read_cortex_resource`，以及一个自描述的 `cortex://architecture` 资源实时生成 - **审计轨迹**：stdout 上每个调用的一行 JSON（哈希电子邮件，哈希参数）+ 可选的 PostgreSQL 持久性，具有保留时间 ## 快速入门（不需要 OAuth 服务器） ```bash git clone https://github.com/wellknownmcp/cortex-gateway cd cortex-gateway npm install # 1. 启动演示后端（无依赖） node examples/demo-backend/server.mjs & # 2. 配置网关 cat > .env.local <<'EOF' OAUTH_ISSUER=https://auth.example.com CORTEX_BACKENDS=demo CORTEX_BACKEND_DEMO_URL=http://127.0.0.1:4820 CORTEX_TECHNICAL_TOKEN=demo-technical-token CORTEX_DEV_BYPASS_TOKEN=dev-secret CORTEX_DEV_BYPASS_SCOPES=mcp:demo:read EOF # 3. 运行它 npm run dev # 4. 谈论 MCP（开发绕过本地替换 Bearer JWT） curl -s http://localhost:3213/mcp \ -H 'Content-Type: application/json' \ -H 'X-Dev-Mode: dev-secret' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name' # → whoami, ..., demo_get_help, demo_echo, demo_get_time curl -s http://localhost:3213/mcp \ -H 'Content-Type: application/json' \ -H 'X-Dev-Mode: dev-secret' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"demo_echo","arguments":{"message":"hello"}}}' | jq ``` 在生产环境中，您将 `OAUTH_ISSUER` 指向您的 OAuth 2.1 授权服务器（任何发行 RS256 JWT 且具有 JWKS 端点并支持 `scope` 声明的服务器），MCP 客户端连接到 `https://your-host/mcp` 并带有 Bearer 令牌，其 `aud` 是网关的规范 URI。 ## 添加后端 1. 在您的应用程序中实现合约 - 一个 POST 端点，`list_tools` + 您的工具（[docs/backend-contract.md](docs/backend-contract.md)，`examples/demo-backend/` 中的参考实现）。 2. 声明它： ```bash CORTEX_BACKENDS=demo,docs CORTEX_BACKEND_DOCS_URL=http://127.0.0.1:4001 ``` 3. 完成。网关在 60 秒内发现 `docs_*` 工具并将 `tools/list_changed` 推送给连接的客户端。 ## 配置 所有内容都由环境变量驱动 - 请参见 [.env.example](.env.example) 以获取完整的注释列表。基本内容： | 变量 | 必需 | 目的 | |---|---|---| | `CORTEX_CANONICAL_URI` | 生产环境 | 规范的 MCP 资源 URI（RFC 9728），默认 JWT 受众 | | `OAUTH_ISSUER` | 是 | 您的 OAuth 2.1 授权服务器 | | `CORTEX_BACKENDS` + `CORTEX_BACKEND_<ID>_URL` | 是 | 联邦后端 | | `CORTEX_TECHNICAL_TOKEN` | 是 | 目录发现的静态令牌（仅目录方法） | | `CORTEX_ALLOWED_ORIGINS` | 生产环境 | 允许的 Web 来源（精确或 `*.suffix`） | | `CORTEX_DATABASE_URL` | 否 | PostgreSQL 用于审计持久性和网关票据 | | `CORTEX_TICKET_WEBHOOK_URL` | 否 | 用于阻止缺失功能票据的 Webhook | | `CORTEX_WEBSITE_URL` | 否 | MCP 客户端显示的 `websiteUrl`（默认：网关来源）。服务器图标：替换 `public/icon-{light,dark}.png` | ## 安全模型 代理访问从构造上讲是安全的，而不是由网关策略决定的。以下是您将任何 MCP 工具连接到 AI 应用程序时所需的要求： - **OAuth 2.1，而不是共享 API 密钥** - 每个调用者都以自己的身份进行身份验证；令牌是按用户、范围和可撤销的。 - **无权限扁平化** - 真实的用户身份被传播到每个后端，因此不存在超权限的服务帐户，代理获得用户的确切权限。 - **最小权限** - 工具目录按调用者的令牌范围过滤；代理只能看到其令牌允许的工具。 - **可验证** - 整个 OAuth 发现链可以在没有令牌的情况下遍历，因此您可以（或第三方扫描器）可以在连接前确认姿势。 在后台： - 网关 **不决定**关于业务权限。OAuth 范围是前门（检查两次：网关 + 后端）；应用程序角色和 ACL 存在于每个后端。 - 静态技术令牌只能访问目录方法（[src/contract/static-token.ts](src/contract/static-token.ts)）；每个数据方法都需要最终用户的 JWT。 - 审计设计为匿名（哈希电子邮件，哈希参数）。 - 会话绑定到令牌的 `sub`；外国会话 ID 获取 404。 **合规性。** 这些是审计测试的控件：最小权限范围，按用户身份（无超权限服务帐户），每个调用的可归因审计轨迹和集中撤销。它们映射到 ISO 27001 访问控制和日志记录控件（A.5.15，A.8.15），SOC 2 CC6/CC7，并支持欧盟 AI 法案记录保存（第 12 条）和人工监督（第 14 条）。自我托管意味着审计轨迹和令牌保险库保留在您的周界内 - 在您的 SOC 2 范围内没有额外的子处理器。Cortex 提供控件，而不是认证。 ## 开发 ```bash npm run typecheck # tsc --noEmit npm test # vitest npm run build # prisma generate + next build ``` 每个环境中都可选使用数据库：没有 `CORTEX_DATABASE_URL`，审计保留在 stdout 上，网关本地票据被禁用。 ## 许可证 [MIT](LICENSE)