Workos MCP Gateway

MCP运维云端

提供方 ragieai · 包名 @ragieai/mcp-gateway

运维云端 stdio · 本地进程 OAuth 授权 社区 / 第三方 Claude
查看接入方式

Ragie MCP网关是一个基于WorkOS实现JWT令牌验证的多租户模型上下文协议网关,用于安全、组织化的访问Ragie MCP服务。

一句话选型结论

按资料字段整理

Workos MCP Gateway 属于运维云端类 MCP 服务器,stdio · 本地进程,OAuth 授权,可直接接入 Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类运维云端 传输方式stdio · 本地进程 鉴权OAuth 授权 部署方式本地部署
GitHub 星标 12 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

运维云端
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

多租户TypeScript本地部署认证网关JWT验证组织路由角色访问控制

安装与配置

stdio · 本地进程 OAuth 授权
客户端在本机拉起子进程,数据不出本机
npx @ragieai/mcp-gateway

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
云资源查询

查实例、存储、账单等云上资源状态。

部署与发布

把部署、重启、回滚这类操作接进对话。

监控与告警

拉取监控指标,异常时让模型帮你判断。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好OAuth 授权对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在运维云端场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Workos MCP Gateway当前 未标注 stdio · 本地进程 本地部署 有 2026-05-17
lobehub 未标注 stdio · 本地进程 本地部署 有 2026-04-11
TrendRadar 未标注 stdio · 本地进程 本地部署 有 2026-04-13
Ui Tars Desktop 8a825770 未标注 stdio · 本地进程 本地部署 有 2026-05-17
ruflo 未标注 stdio · 本地进程 本地部署 有 2026-04-13
FastGPT 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

运维云端
字段来自项目仓库与公开索引,中文说明由本站标注
提供方ragieai上游标注的维护方 ragieai
分类运维云端本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式OAuth 授权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时@ragieai/mcp-gateway · Node.js本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

13.7 KB
来自项目仓库与上游目录的原文,未做删改

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(推荐)

直接运行网关,无需安装:```bash
npx @ragieai/mcp-gateway


### 全球安装

全局安装以实现全系统访问:```bash
npm install -g @ragieai/mcp-gateway

然后从任何地方运行它:```bash
mcp-gateway


### 本地安装

在项目中作为依赖项安装:```bash
npm install @ragieai/mcp-gateway

然后运行它:```bash
npx mcp-gateway


或者将其添加到您的 `package.json` 脚本:```json
{
"scripts": {
"start:gateway": "mcp-gateway"
}
}

开发设置

如果您想贡献或自定义网关:```bash

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` 文件```bash
# 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/

用法

基本用法

使用默认设置运行网关:```bash
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` 在数据库中创建集合的脚本:```bash
# 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 对于所有选项。

示例:使用环境变量运行```bash

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承载令牌
1. **持有者令牌**:客户端将令牌包含在 `Authorization: Bearer ` 头球
1. **令牌验证**:网关使用WorkOS JWKS验证JWT签名
1. **会员验证**:网关验证用户是否是所请求组织的活动成员
1. **角色验证**:网关验证用户是否至少有一个角色与集合的角色匹配 `allowedRoles`
1. **收集验证**:网关检查数据库中是否存在组织/集合组合
1. **请求代理**:通过身份验证的请求使用数据库中解密的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令牌
1. 在 `Authorization` 所有请求的标头
1. 在URL路径中指定组织ID和集合: `POST /{organizationId}/mcp/{collection}`
1. 使用WWW-Authenticate标头处理401响应以查找身份验证错误
1. 处理未映射组织/集合组合的404响应
1. 通过以下方式发现OAuth端点 `/.well-known/oauth-protected-resource` 如有需要

### 示例请求

网关代理MCP JSON-RPC请求。下面是一个使用 `retrieve` 工具:```bash
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镜像:```bash
docker build -t mcp-gateway .


您还可以指定带有版本的标记:```bash
docker build -t mcp-gateway:latest -t mcp-gateway:0.0.2 .

运行容器

使用所需的环境变量运行容器:```bash
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文件:```bash
docker run -d \
--name mcp-gateway \
-p 3000:3000 \
--env-file .env \
mcp-gateway

可选配置

根据需要包括可选的环境变量:```bash
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`:```yaml
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

然后运行:bash docker-compose up -d

许可证

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

贡献

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

支持

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

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Workos MCP Gateway 怎么安装?

在客户端按下面的安装命令接入:npx @ragieai/mcp-gateway。对应的包名是 @ragieai/mcp-gateway。装完在客户端配置里引用同一个包或端点。

Workos MCP Gateway 怎么在 Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Workos MCP Gateway 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Workos MCP Gateway 需要 API Key 吗?

资料标注需要OAuth 授权认证,使用前准备好对应凭据,并按最小权限配置。

Workos MCP Gateway 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Workos MCP Gateway 能提供哪些能力?

资料显示能力标签包括 多租户、TypeScript、Claude。具体工具清单以官方文档为准。

Workos MCP Gateway 需要什么运行环境?

运行时为 Node.js;属于本地进程,需要在本机装好运行环境。

Workos MCP Gateway 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。