使用 mcp-use 在 MCP Server 中集成 WorkOS AuthKit OAuth 认证

原创2026-09-09 13:27:021,766 阅读
文章标签:人工智能AI 应用AI Agent交互助手工具调用前端UI组件Agent 框架移动开发后端WebSocket

使用 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 模式设置步骤:

  1. 不设置 MCP_USE_OAUTH_WORKOS_CLIENT_ID
  2. 在 WorkOS Dashboard → Connect → Configuration 中启用 DCR

此后 MCP 客户端(如 Inspector)会在首次连接时自动完成注册。

预注册客户端(备选方案)

如果你需要一个固定的 OAuth 客户端而不是 DCR:

  1. 在 WorkOS Dashboard → Connect → OAuth Applications 中创建 OAuth 应用
  2. 将 MCP_USE_OAUTH_WORKOS_CLIENT_ID 设置为该 Client ID
  3. 在 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 侧登记。解决步骤如下:

  1. 打开 WorkOS Dashboard → Developer → Redirects 标签页
  2. 点击 Edit redirect URIs
  3. 添加上你的 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。

延伸阅读

登录后查看全文
CopilotKit