使用 mcp-use 在 MCP Server 中集成 WorkOS AuthKit OAuth 认证
使用 mcp-use 在 MCP Server 中集成 WorkOS AuthKit OAuth 认证
本文基于 CopilotKit 仓库中 open-mcp-client 示例项目所附带的 mcp-apps-builder 技能文档,讲解如何在基于 mcp-use 构建的 MCP Server 中接入 WorkOS AuthKit OAuth 认证。读完本文,你将掌握 oauthWorkOSProvider 的零配置接入方式、DCR(动态客户端注册)模式与预注册客户端模式的区别、ctx.auth.user 用户上下文的完整字段语义,以及在工具处理器中做基于角色的访问控制和调用 WorkOS 管理 API 的实战写法。
背景:为什么需要给 MCP Server 加认证
MCP Server 暴露的 /mcp/* 路由是任何人都可以调用的工具入口。在公开部署场景下,必须保护这些工具不被未授权访问,同时让工具处理器能拿到"当前是谁在调用"的用户身份。mcp-use 的解决方案是:在 new MCPServer({...}) 时传入一个 oauth 选项,之后由框架自动完成全部认证编排。
在该示例项目中,MCP Server 的入口文件位于 apps/mcp-use-server/index.ts,默认监听 3109 端口,本地可用 npm run dev 启动,并通过 http://localhost:3000/inspector 使用 MCP Inspector 测试(见 apps/mcp-use-server/README.md)。下面的接入代码正是在这个 Server 配置上叠加认证能力。
传入 oauth 这一个属性后,框架会自动完成以下工作(依据 认证总览文档):
- 使用 Bearer Token 认证保护所有
/mcp/*路由; - 通过提供商的 JWKS 端点验证 JWT;
- 自动搭建 OAuth 发现端点(
/.well-known/oauth-authorization-server、/.well-known/oauth-protected-resource); - 为浏览器客户端搭建
/authorize与/token代理端点; - 在所有的 tool / resource / prompt 处理器中填充
ctx.auth用户上下文。
Quick Start:五分钟接入 WorkOS AuthKit
mcp-use 内置了 WorkOS 专用的 oauthWorkOSProvider 工厂函数,默认采用零配置模式:不传参数时自动从 MCP_USE_OAUTH_WORKOS_* 环境变量读取配置。
import { MCPServer, oauthWorkOSProvider, object } from "mcp-use/server";
const server = new MCPServer({
name: "my-server",
version: "1.0.0",
oauth: oauthWorkOSProvider(),
});
server.tool(
{ name: "whoami", description: "Get authenticated user info" },
async (_args, ctx) =>
object({
userId: ctx.auth.user.userId,
email: ctx.auth.user.email,
name: ctx.auth.user.name,
}),
);
server.listen();
对应的 .env 文件只需一行关键配置:
MCP_USE_OAUTH_WORKOS_SUBDOMAIN=your-company.authkit.app
JWT 校验、OAuth 发现端点与 Token 代理均由框架自动处理,无需手写任何认证逻辑。
环境变量说明
| 变量 | 是否必填 | 说明 |
|---|---|---|
MCP_USE_OAUTH_WORKOS_SUBDOMAIN |
是 | 完整的 AuthKit 域名(例如 my-company.authkit.app) |
MCP_USE_OAUTH_WORKOS_CLIENT_ID |
否 | 预注册的 OAuth Client ID,省略时走 DCR 模式 |
MCP_USE_OAUTH_WORKOS_API_KEY |
否 | 用于调用 WorkOS 管理 API 的 API Key |
如何找到你的 Subdomain
WorkOS Dashboard → Domains 标签页 → AuthKit Domain。
务必使用包含 .authkit.app 的完整域名。例如你的 AuthKit 域是 my-company.authkit.app,就应完整设置为 my-company.authkit.app,而不是只写 my-company。
配置选项:零配置与显式配置
零配置(自动从环境变量读取):
oauth: oauthWorkOSProvider();
显式配置(覆盖环境变量,适合需要编程式传入配置的场景):
oauth: oauthWorkOSProvider({
subdomain: "my-company.authkit.app",
clientId: "client_01KB5DRXBDDY1VGCBKY108SKJW", // optional
apiKey: "sk_test_...", // optional
verifyJwt: false, // development only
});
| 选项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
subdomain |
string |
环境变量 | 完整的 AuthKit 域名(如 my-company.authkit.app) |
clientId |
string? |
环境变量 | 预注册的 Client ID,省略则使用 DCR |
apiKey |
string? |
环境变量 | WorkOS API Key |
verifyJwt |
boolean? |
true |
设为 false 可跳过 JWT 校验(仅限开发环境) |
动态客户端注册(DCR)
DCR 允许 MCP 客户端在首次连接时自动向 WorkOS 注册自己,这是官方推荐的 MCP Server 接入模式。
使用 MCP Inspector 测试时的关键提示:请务必使用 DCR 模式,即不要设置
MCP_USE_OAUTH_WORKOS_CLIENT_ID。Inspector 依赖 DCR 完成自我注册——如果没有 DCR,Inspector 没有预配置的client_id,OAuth 流程会卡住(静默停滞)。
DCR 模式设置步骤:
- 不设置
MCP_USE_OAUTH_WORKOS_CLIENT_ID - 在 WorkOS Dashboard → Connect → Configuration 中启用 DCR
此后 MCP 客户端(如 Inspector)会在首次连接时自动完成注册。
预注册客户端(备选方案)
如果你需要一个固定的 OAuth 客户端而不是 DCR:
- 在 WorkOS Dashboard → Connect → OAuth Applications 中创建 OAuth 应用
- 将
MCP_USE_OAUTH_WORKOS_CLIENT_ID设置为该 Client ID - 在 Dashboard 中配置与你的 MCP 客户端匹配的回调(redirect URI)
选择哪种模式可以从 认证总览 得到进一步的参考:总览明确指出 WorkOS 与 Supabase 已经过 MCP Inspector 的完整测试并开箱即用地支持 DCR,因此优先推荐从这两者开始;而 oauthCustomProvider 虽可对接任意 OIDC 兼容提供商,但多数提供商(如 Asana、Google、Okta)不支持 DCR,Inspector 无法自我注册,OAuth 流程会静默卡住。
用户上下文(ctx.auth.user)
WorkOS 会在认证通过后向 ctx.auth.user 填充以下字段:
| 字段 | 类型 | 来源 |
|---|---|---|
userId |
string |
sub claim |
email |
string? |
email claim |
name |
string? |
name claim |
username |
string? |
preferred_username claim |
picture |
string? |
picture claim |
roles |
string[] |
roles claim |
permissions |
string[] |
permissions claim |
scopes |
string[] |
从 scope claim 解析 |
email_verified |
boolean? |
email_verified claim |
organization_id |
string? |
org_id claim |
sid |
string? |
会话 ID |
关于 ctx.auth 的完整形状,认证总览文档 补充了以下几点关键约定:
ctx.auth.accessToken是原始 Bearer Token 字符串,ctx.auth.payload是原始 JWT 载荷(Record<string, unknown>,所有值需要显式类型断言);- 用户信息是嵌套结构:应当访问
ctx.auth.user.email,而不是ctx.auth.email; - 优先使用类型化的访问器(
ctx.auth.user.*、ctx.auth.scopes、ctx.auth.permissions),避免在每个工具处理器里对payload做类型断言;提供商特有的非标准 claim 应通过getUserInfo映射成类型化字段(WorkOS 额外提供的organization_id就是一个例子,可直接通过ctx.auth.user.organization_id访问)。
基于角色的访问控制(RBAC)
结合 roles 字段,可以非常自然地实现按角色授权:
server.tool(
{ name: "admin-action", description: "Admin-only operation" },
async (_args, ctx) => {
if (!ctx.auth.user.roles?.includes("admin")) {
return error("Forbidden: admin role required");
}
// ... admin logic
return text("Done");
},
);
注意这里返回的是 error() 响应辅助函数而非抛异常——总览文档 将"抛错而非返回 error()"列入了常见错误清单。更多响应辅助函数可参考 server/tools.md。
调用 WorkOS 管理 API
当你的工具需要按用户身份查询 WorkOS 侧的数据时,请使用 WorkOS API Key(而不是用户的访问令牌)发起管理 API 调用:
const WORKOS_API_KEY = process.env.MCP_USE_OAUTH_WORKOS_API_KEY;
server.tool(
{ name: "get-workos-user", description: "Fetch user profile from WorkOS" },
async (_args, ctx) => {
if (!WORKOS_API_KEY) {
return error("WorkOS API key not configured");
}
const res = await fetch(
`https://api.workos.com/user_management/users/${ctx.auth.user.userId}`,
{
headers: {
Authorization: `Bearer ${WORKOS_API_KEY}`,
"Content-Type": "application/json",
},
},
);
if (!res.ok) {
return error(`WorkOS API failed: ${res.status} ${res.statusText}`);
}
return object(await res.json());
},
);
如果你的工具需要以用户身份调用其他业务 API(而非 WorkOS 管理 API),则改用 ctx.auth.accessToken 作为 Bearer Token 即可,认证总览 给出了这一标准写法。
完整的示例 .env
# Required: Full AuthKit domain (WorkOS Dashboard → Domains → AuthKit Domain)
MCP_USE_OAUTH_WORKOS_SUBDOMAIN=my-company.authkit.app
# Optional: Pre-registered OAuth client ID (omit for DCR mode)
# MCP_USE_OAUTH_WORKOS_CLIENT_ID=client_01KB5DRXBDDY1VGCBKY108SKJW
# Optional: WorkOS API key for management API calls
MCP_USE_OAUTH_WORKOS_API_KEY=sk_test_...
Troubleshooting:Redirect URI 不匹配
如果在 OAuth 流程中遇到重定向 URI 报错,说明 MCP 客户端期望的回调地址没有在 WorkOS 侧登记。解决步骤如下:
- 打开 WorkOS Dashboard → Developer → Redirects 标签页
- 点击 Edit redirect URIs
- 添加上你的 MCP 客户端期望的回调 URI
例如本地使用 MCP Inspector 且端口为 3000 时,需要添加:
http://localhost:3000/oauth/callback
确切的重定向地址取决于你的客户端和端口——请以报错信息中提示的期望值为准。
注意: WorkOS 侧对 Redirect URI 的修改可能需要几分钟才能生效。
排查思路与常见错误汇总
结合 认证总览 与本文档,调试 WorkOS 认证时可重点检查以下几点:
ctx.auth结构用错:用户信息是嵌套的,正确写法是ctx.auth.user.email,而非ctx.auth.email;- 凭据硬编码:使用环境变量或显式配置传参,切勿把密钥提交进版本库;
- 生产环境跳过 JWT 校验:
verifyJwt: false(对应 Supabase 的skipVerification: true)仅限开发环境使用; - DCR 未启用导致 Inspector 卡住:不要设置
MCP_USE_OAUTH_WORKOS_CLIENT_ID,并确认 WorkOS Dashboard 的 Connect → Configuration 已启用 DCR。
延伸阅读
- Auth 总览 → references/authentication/overview.md
- Supabase 接入 → references/authentication/supabase.md
- 自定义 OIDC 提供商 → references/authentication/custom.md
- 构建工具 → references/server/tools.md
- 通用模式示例 → references/patterns/common-patterns.md
- 项目实际入口与运行方式 → apps/mcp-use-server/index.ts 与 apps/mcp-use-server/README.md