企业官网建设流程全解析

Skybridge 认证体系指南：如何为 MCP App 接入 OAuth 并安全验证用户身份

【免费下载链接】skybridgeSkybridge is a full-stack TypeScript framework for MCP Apps and ChatGPT Apps. Type-safe. React-powered. Platform-agnostic.项目地址: https://gitcode.com/gh_mirrors/skybr/skybridge

Skybridge 是一个全栈 TypeScript 框架，用于构建运行在 ChatGPT 和 Claude 等宿主中的 MCP Apps。它的认证体系基于 OAuth 2.0：只需几行配置即可接入 Auth0、Clerk 等身份提供商，并让每一个工具调用都携带经过验证的用户身份，从而安全地实现个性化体验。

为什么 MCP App 必须接入 OAuth？

默认情况下，MCP 工具调用是匿名的——协议本身不会告诉你的服务器"是谁在调用"。如果你的 App 需要按用户展示收藏、订单或个性化内容，就必须先确认调用者身份。

好消息是：宿主替你做了最难的活。当 ChatGPT 或 Claude 调用你的工具时，它会负责：

1. 发现你的授权服务器（通过标准元数据文档，RFC 9728）
2. 引导用户登录并同意授权
3. 刷新过期的 token
4. 在每个请求上附加 Bearer token

你的服务器只需要做好三件事：

• 📢发布发现元数据：告诉宿主"去哪里登录"
• 🔍验证 token：确认每个请求携带的 token 真实有效
• 👤读取用户：在处理器中拿到已认证用户的信息

完整流程文档见 docs/build/auth.mdx。

六选一：如何快速接入 OAuth 提供商

Skybridge 内置了六个"品牌化"提供商，每个都只需在Skybridge配置里写一行oauth字段。下面以配置最简单的 Clerk 为例，其余提供商的完整步骤见 docs/guides/auth-providers.mdx：

import { Skybridge, clerkProvider } from "skybridge/server"; export const app = new Skybridge({ name: "auth-coffee", version: "0.0.1", oauth: clerkProvider({ domain: process.env.CLERK_FRONTEND_API, // 你的 Frontend API 域名 }), handler, // 你的工具注册逻辑 });

支持的提供商速查表

💡其他提供商怎么办？只要它支持动态客户端注册（DCR）、签发 JWT access token，并能把 audience 写进 token，就可以用customProvider({ issuer, audience })三行接上。每个可运行的示例源码都在 examples/ 目录下，Clerk 示例的完整服务端代码见 examples/auth-clerk/src/server.ts。

两步安全验证：requireBearerAuth 与 optionalBearerAuth

接入提供商后，Skybridge 自动挂载了验证中间件。手动接线时则有两个中间件可选（挂载在/mcp路径上）：

模式一：全站强制登录（requireBearerAuth）

requireBearerAuth把整个服务器"锁"在登录后面：没有 token、token 无效或过期的请求，在任何工具运行之前就会被 401 拒绝；token 缺少所需 scope 则返回 403。这是个人数据类工具（订单、收藏、账户）的默认选择。

• 参考文档：docs/api-reference/require-bearer-auth.mdx

模式二：混合公开与私有工具（optionalBearerAuth）

如果一部分工具可以匿名使用（比如浏览商品目录），另一部分需要登录（比如下单结算），换用optionalBearerAuth即可：

• 请求没带token → 放行，处理器里authInfo为空
• 请求带了token → 正常验证，无效同样 401

然后为每个工具声明securitySchemes来控制可见性：

• 参考文档：docs/api-reference/optional-bearer-auth.mdx

在提供商路径下（oauth配置字段），这些规则会进一步简化为工具级声明，例如auth: { allowsAnonymous: true }或auth: { scopes: ["checkout"] }，由 Skybridge 在处理器运行前强制执行，无需手写守卫。

如何在处理器中安全读取已登录用户

token 验证通过后，认证信息会出现在每个工具处理器的第二个参数里：

async ({ query }, extra) => { const subject = extra.http?.authInfo?.extra?.subject; // 用户标识 const scopes = extra.http?.authInfo?.scopes; // 已授予的权限 return { structuredContent: { results: search(query, subject) } }; }

两条安全准则，务必遵守：

1. 永远不要信任客户端传入的用户 ID——只认extra.http?.authInfo里的内容，因为它是你亲手验证过的 token 解析结果。
2. token 只证明"他是谁"——"他能做什么"（scope 检查）和数据归属（按用户过滤查询）仍要在处理器里处理。

需要读取自定义 claims（如email、tenant）时，可以给提供商传入类型参数，例如workosProvider<{ tenant: string }>({ domain, audience })，类型会一路安全地流进处理器。验证器契约详见 docs/api-reference/verifier.mdx，发现元数据的路由器（mcpAuthMetadataRouter）见 docs/api-reference/mcp-auth-metadata-router.mdx。

如何本地测试 OAuth 流程：用隧道一步打通

OAuth 流程涉及宿主的真实登录行为，localhost无法完成跳转。Skybridge 的隧道功能可以一键把本地服务暴露为公网 URL：

skybridge dev --tunnel

把输出的隧道地址配置到提供商（WorkOS 场景下需把它也注册为 Resource Indicator，并传入audience: [SERVER_URL, TUNNEL_URL]），就能在 ChatGPT / Claude 里走完完整的登录闭环。多 URL 场景的处理方式见 docs/guides/auth-providers.mdx 的 WorkOS 章节。

参考资料：核心文件清单

总结

为 MCP App 接入 OAuth 并安全验证用户身份，在 Skybridge 中只需三步：选一个提供商用一行oauth配置接上（Auth0、Clerk、WorkOS 等六选一，或customProvider自定义）、用requireBearerAuth或optionalBearerAuth声明你的鉴权策略、在处理器里通过extra.http?.authInfo读取可信用户。整个过程中，登录、token 刷新等复杂流程都由宿主托管，你只需专注业务逻辑，即可为 ChatGPT 和 Claude 里的 App 加上既简单又安全的大门。🔐

【免费下载链接】skybridgeSkybridge is a full-stack TypeScript framework for MCP Apps and ChatGPT Apps. Type-safe. React-powered. Platform-agnostic.项目地址: https://gitcode.com/gh_mirrors/skybr/skybridge