Workos MCP Gateway

Ragie MCP网关

Ragie模型上下文协议服务器的多租户MCP（模型上下文协议）网关，使用WorkOS实现承载令牌身份验证。该网关通过JWT令牌验证和组织成员身份验证，实现了对Ragie MCP服务的安全、基于组织的访问。

概述

该网关充当AI客户端（如Claude、OpenAI或Anthropic）和Ragie MCP服务器之间的安全代理。它提供：

• 承载令牌身份验证：通过WorkOS JWKS验证JWT令牌
• 基于组织的路由：具有组织范围端点的多租户路由
• 组织成员身份验证：通过WorkOS验证用户在组织中的成员资格
• 基于角色的访问控制：根据WorkOS组织角色限制集合访问
• 基于集合的映射：使用per-organization/collection API键将组织ID和集合映射到Ragie分区
• 收集筛选器：可选筛选器自动应用于检索范围数据访问请求
• 代理功能：将经过身份验证的请求透明转发到Ragie MCP服务
• OAuth发现端点：OAuth元数据发现的知名端点

先决条件

• Node.js 18+
• 带集合表的PostgreSQL数据库
• WorkOS帐户和应用程序设置
• 组织/集合的Ragie API密钥（加密存储在数据库中）

安装

使用npx（推荐）

直接运行网关，无需安装：

npx @ragieai/mcp-gateway

全球安装

全局安装以实现全系统访问：

npm install -g @ragieai/mcp-gateway

然后从任何地方运行它：

mcp-gateway

本地安装

在项目中作为依赖项安装：

npm install @ragieai/mcp-gateway

然后运行它：

npx mcp-gateway

或者将其添加到您的 package.json 脚本：

{
  "scripts": {
    "start:gateway": "mcp-gateway"
  }
}

开发设置

如果您想贡献或自定义网关：

# Clone the repository
git clone 
cd mcp-gateway

# Install dependencies
npm install

# Copy the environment template
cp .env.example .env

# Configure your environment variables in .env (see Configuration section)

# Build the project
npm run build

配置

网关需要配置多个环境变量。您可以通过以下方式设置这些：

• shell中的环境变量
• A. .env 当前目录中的文件（自动加载）
• 部署平台的环境配置

必需变量

• DATABASE_URL：集合数据库的PostgreSQL连接URL
• ENCRYPTION_KEY：用于解密存储在数据库中的API密钥的加密密钥（至少32个字符）
• WORKOS_API_KEY：您的WorkOS API密钥
• WORKOS_AUTHORIZATION_SERVER_URL：您的WorkOS AuthKit授权服务器URL
• WORKOS_CLIENT_ID：您的WorkOS应用程序客户端ID

可选变量

• BASE_URL：网关服务器的公共URL（默认为 http://localhost:{PORT} 哪里 {PORT} 是配置的端口）
• PORT：服务器端口（默认为3000）
• LOG_LEVEL：日志记录级别-调试、信息、警告或错误（默认为信息）
• LOG_FORMAT：日志格式-json或漂亮（默认为漂亮）
• NODE_ENV：环境模式-在开发模式下，SIGINT立即关闭；在生产模式下，SIGINT触发优雅关机
• RAGIE_BASE_URL：Ragie API基本URL（默认为 https://api.ragie.ai/)

示例 .env 文件

# Required: Database connection
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/mcp-gateway

# Required: Encryption key for API keys (min 32 characters)
ENCRYPTION_KEY=your-encryption-key-at-least-32-characters

# Required: WorkOS Configuration
WORKOS_API_KEY=your_workos_api_key_here
WORKOS_AUTHORIZATION_SERVER_URL=https://api.workos.com/auth/v1
WORKOS_CLIENT_ID=your_workos_client_id_here

# Optional: Base URL (defaults to http://localhost:{PORT} where {PORT} is the configured port)
# BASE_URL=http://localhost:3000

PORT=3000
LOG_LEVEL=info
LOG_FORMAT=pretty
NODE_ENV=production
# Optional: Ragie API base URL (defaults to https://api.ragie.ai/)
# RAGIE_BASE_URL=https://api.ragie.ai/

用法

基本用法

使用默认设置运行网关：

npx @ragieai/mcp-gateway

网关将从端口3000（或中指定的端口）启动 PORT 环境变量）。

收藏数据库

网关从PostgreSQL数据库读取集合配置。每条收款记录包括：

• name：URL路径中使用的集合标识符
• organization_id：WorkOS组织ID
• partition：要路由到的Ragie分区名称
• ragie_api_key：此集合的加密Ragie API密钥
• allowed_roles：角色名称数组（例如。， ["admin", "member"])或 "*" 允许所有角色
• filters：可选的JSON过滤器对象，适用于此集合的所有检索请求

基于角色的访问控制： 网关使用WorkOS组织成员角色实施基于角色的访问控制。用户必须至少有一个角色与 allowedRoles 他们试图访问的集合的配置。使用 "*" 允许任何角色访问。

API密钥加密： API密钥使用AES-256-GCM加密存储在数据库中。这 ENCRYPTION_KEY 环境变量必须与用于加密API密钥的密钥匹配（通常由管理器应用程序加密）。

收集筛选器： 每个集合都可以有可选的过滤器，这些过滤器会自动应用于所有 retrieve 工具调用。这些筛选器将与请求中的任何筛选器合并，集合筛选器优先。这允许您将集合范围限定到特定文档，而不需要客户端筛选器配置。

网关只允许访问数据库中存在的组织/集合组合。对不存在的集合的请求将返回404错误。

创建收藏

使用 db:create-collection 在数据库中创建集合的脚本：

# Interactive mode
npm run db:create-collection

# Non-interactive mode
npm run db:create-collection -- \
  --name "my-collection" \
  --organization-id "org_123" \
  --partition "my-partition" \
  --ragie-api-key "tnt_xxx" \
  --allowed-roles "admin,member"

# With filters
npm run db:create-collection -- \
  --name "docs" \
  --organization-id "org_123" \
  --partition "production" \
  --ragie-api-key "tnt_xxx" \
  --allowed-roles "*" \
  --filters '{"department": "engineering"}'

跑 npm run db:create-collection -- --help 对于所有选项。

示例：使用环境变量运行

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/mcp-gateway \
ENCRYPTION_KEY=your-encryption-key-at-least-32-characters \
WORKOS_API_KEY=your_workos_key \
WORKOS_AUTHORIZATION_SERVER_URL=https://api.workos.com/auth/v1 \
WORKOS_CLIENT_ID=your_client_id \
LOG_FORMAT=json \
npx @ragieai/mcp-gateway

API终点

公共端点

• GET /welcome -返回欢迎页面（用于验证网关是否正在运行）
• GET /.well-known/oauth-protected-resource -返回OAuth保护的资源元数据
• GET /.well-known/oauth-authorization-server -返回OAuth授权服务器元数据（从WorkOS代理）

受保护的端点

• POST /:organizationId/mcp/:collection -将MCP JSON-RPC请求代理到Ragie MCP服务器（需要承载令牌）

路径重写

当代理到Ragie MCP服务器时，网关会根据集合的分区重写路径：

• POST /org_123/mcp/my-collection → POST /mcp/soc2/ （如果集合映射到分区 soc2，添加了尾随斜线）

网关通过组合来构造目标URL RAGIE_BASE_URL 用重写的路径。例如，如果 RAGIE_BASE_URL 是 https://api.ragie.ai/ 并且路径被重写为 /mcp/soc2/，最终的URL将是 https://api.ragie.ai/mcp/soc2/.

收集API密钥

数据库中的每个集合都有自己的加密API密钥。这允许不同的组织和集合使用不同的Ragie API密钥。网关在代理请求时自动解密并使用适当的API密钥。

身份验证流程

1. 客户获得JWT：客户端使用WorkOS进行身份验证并接收JWT承载令牌
2. 持有者令牌：客户端将令牌包含在 Authorization: Bearer 头球
3. 令牌验证：网关使用WorkOS JWKS验证JWT签名
4. 会员验证：网关验证用户是否是所请求组织的活动成员
5. 角色验证：网关验证用户是否至少有一个角色与集合的角色匹配 allowedRoles
6. 收集验证：网关检查数据库中是否存在组织/集合组合
7. 请求代理：通过身份验证的请求使用数据库中解密的API密钥代理到Ragie MCP服务器

安全特性

• JWT验证：所有承载令牌都使用WorkOS JWKS进行加密验证
• 组织成员：用户必须是他们正在访问的组织的活跃成员
• 基于角色的访问控制：用户必须至少有一个角色与集合的角色匹配 allowedRoles 配置
• 收集验证：只有数据库中存在的组织/集合组合是可访问的
• 加密的API密钥：Ragie API密钥存储加密（AES-256-GCM），仅在需要时解密
• 收集筛选器：服务器端筛选器确保用户只能访问作用域数据，而不管客户端提供的筛选器如何
• 错误处理：正确的HTTP状态码（401、403、404）和WWW-Authenticate标头用于身份验证失败
• 收集隔离：每个组织/集合组合都使用自己的API密钥和分区

发展

项目结构

• 网关类：主要应用程序逻辑和Express服务器设置
• 配置：基于环境的配置管理与Zod验证
• 日志记录器：具有可配置级别和格式的结构化日志记录（JSON或漂亮）
• 测试：具有模拟依赖关系的全面测试覆盖率

可用脚本

• npm run build -将TypeScript编译为JavaScript
• npm run dev -通过热重新加载启动开发服务器
• npm start -启动生产服务器（构建后）
• npm run clean -清理构建工件
• npm run typecheck -运行类型检查
• npm run lint -运行ESLint
• npm run lint:fix -修复ESLint问题
• npm run format -使用Prettier格式化代码
• npm test -运行测试套件
• npm run test:watch -在监视模式下运行测试
• npm run test:coverage -使用覆盖率报告运行测试
• npm run db:init -初始化数据库架构
• npm run db:create-collection -创建新集合（交互式或CLI）

与AI客户端集成

此网关旨在与支持承载令牌身份验证的AI客户端配合使用。客户应当：

1. 使用WorkOS对用户进行身份验证以获取JWT令牌
2. 在 Authorization 所有请求的标头
3. 在URL路径中指定组织ID和集合： POST /{organizationId}/mcp/{collection}
4. 使用WWW-Authenticate标头处理401响应以查找身份验证错误
5. 处理未映射组织/集合组合的404响应
6. 通过以下方式发现OAuth端点 /.well-known/oauth-protected-resource 如有需要

示例请求

网关代理MCP JSON-RPC请求。下面是一个使用 retrieve 工具：

curl -X POST \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "retrieve",
      "arguments": {
        "query": "example query"
      }
    },
    "id": 1
  }' \
  https://gateway.example.com/org_123/mcp/my-collection

多租户架构

网关通过基于组织和集合的路由支持多租户访问：

• 每个组织可以有多个集合，每个集合都有自己的端点路径
• 用户必须是组织的成员才能访问其端点
• 每个集合都映射到一个特定的Ragie分区
• 每个集合都使用自己的加密API密钥
• 每个集合都可以有可选的筛选器来限定数据访问范围
• 只有数据库中存在的集合才可访问

部署

网关可以部署到任何支持Node.js的平台：

Docker部署

该项目包括一个生产就绪的Dockerfile，具有多阶段构建，可实现最佳的映像大小和安全性。

构建Docker镜像

从项目根目录构建Docker镜像：

docker build -t mcp-gateway .

您还可以指定带有版本的标记：

docker build -t mcp-gateway:latest -t mcp-gateway:0.0.2 .

运行容器

使用所需的环境变量运行容器：

docker run -d \
  --name mcp-gateway \
  -p 3000:3000 \
  -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/mcp-gateway \
  -e ENCRYPTION_KEY=your-encryption-key-at-least-32-characters \
  -e WORKOS_API_KEY=your_workos_api_key_here \
  -e WORKOS_AUTHORIZATION_SERVER_URL=https://api.workos.com/auth/v1 \
  -e WORKOS_CLIENT_ID=your_workos_client_id_here \
  mcp-gateway

使用环境文件

为了便于管理，您可以使用 .env Docker文件：

docker run -d \
  --name mcp-gateway \
  -p 3000:3000 \
  --env-file .env \
  mcp-gateway

可选配置

根据需要包括可选的环境变量：

docker run -d \
  --name mcp-gateway \
  -p 3000:3000 \
  -e DATABASE_URL=postgresql://postgres:postgres@host.docker.internal:5432/mcp-gateway \
  -e ENCRYPTION_KEY=your-encryption-key-at-least-32-characters \
  -e WORKOS_API_KEY=your_workos_api_key_here \
  -e WORKOS_AUTHORIZATION_SERVER_URL=https://api.workos.com/auth/v1 \
  -e WORKOS_CLIENT_ID=your_workos_client_id_here \
  -e BASE_URL=https://gateway.example.com \
  -e PORT=3000 \
  -e LOG_LEVEL=info \
  -e LOG_FORMAT=json \
  mcp-gateway

Docker Compose

为了更容易部署，您可以使用Docker Compose。创建一个 docker-compose.yml:

version: '3.8'

services:
  mcp-gateway:
    build: .
    container_name: mcp-gateway
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - WORKOS_API_KEY=${WORKOS_API_KEY}
      - WORKOS_AUTHORIZATION_SERVER_URL=${WORKOS_AUTHORIZATION_SERVER_URL}
      - WORKOS_CLIENT_ID=${WORKOS_CLIENT_ID}
      - BASE_URL=${BASE_URL:-http://localhost:3000}
      - PORT=3000
      - LOG_LEVEL=${LOG_LEVEL:-info}
      - LOG_FORMAT=${LOG_FORMAT:-pretty}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/.well-known/oauth-protected-resource"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 5s

然后运行：

docker-compose up -d

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加新功能的测试
5. 确保所有测试通过
6. 提交拉取请求

支持

有关问题和疑问，请参阅项目的问题跟踪器或文档。