mcp-use + Scalekit MCP Auth

一个通过 Scalekit OAuth 2.1 进行身份验证的 mcp-use MCP 服务器。

团队成员共享同一个服务器 URL。每个人单独登录。工具看到的是他们自己的身份（ctx.auth.user.id），而不是共享的 API 密钥。

此示例不使用 @scalekit-sdk/node，也不需要 Scalekit 客户端 ID 或密钥。资源服务器会对照 Scalekit JWKS 验证 JWT。

菜谱式操作指南位于 docs/v2/typescript/server/authentication/providers/scalekit.mdx。本 README 是本仓库的运行手册。

[!IMPORTANT] 使用你自己的 Scalekit 环境。本仓库仅附带占位符。切勿提交 .env。

你将获得

• 位于 /mcp 的 Streamable HTTP MCP

• 401 + WWW-Authenticate，指向 RFC 9728 protected-resource 元数据

• Scalekit 作为授权服务器（DCR 和 CIMD）

• whoami — 已认证用户、作用域以及令牌的 iss / aud

• greet — 一个以 ctx.auth.user.id 为键控依据的工具

Related MCP server: Access Self-Hosted MCP Server

客户端如何登录

sequenceDiagram
  participant Client as MCP client
  participant Server as This server
  participant SK as Your Scalekit env

  Client->>Server: POST /mcp (no token)
  Server-->>Client: 401 + WWW-Authenticate
  Client->>Server: GET /.well-known/oauth-protected-resource/mcp
  Server-->>Client: authorization_servers = Scalekit resource issuer
  Client->>SK: Discover AS metadata, register via DCR or CIMD
  Client->>SK: User signs in and consents
  SK-->>Client: Access token (aud includes res_…)
  Client->>Server: POST /mcp Authorization: Bearer …
  Server-->>Client: Tool result scoped to ctx.auth.user.id

前提条件

• Node.js 22.22.2 或更高版本

• 一个 Scalekit 账户（如果没有，请注册）

• 至少启用一种认证方式（Google、GitHub、无密码或企业 SSO）

1. 在 Scalekit 中注册 MCP 服务器

按照 MCP Auth 快速入门 操作，并使用以下值：

1. 打开 Scalekit Dashboard → MCP servers → Add MCP server。

2. 为它命名。该名称会显示在同意页面上。

3. 启用 dynamic client registration 和 Client ID Metadata Document (CIMD)。Inspector、Claude 和 Cursor 等公共客户端至少需要其中一项；请保持两项都开启。

4. 在高级设置中，将 Server URL 设置为：

   http://localhost:3000/mcp

   不要带末尾斜杠。设置后，Scalekit 会将该 URL 与 res_… id 一起写入访问令牌的 aud 声明中。如果留空，aud 将只有 res_… —— 本示例仍能正常验证。

5. 保存。从服务器页面复制：

   • Environment URL — https://<your-env>.scalekit.cloud

   • Resource ID — res_…

[!CAUTION] 如果之后切换 DCR 或 CIMD，请重新连接 MCP 客户端。Inspector 和其他客户端会缓存授权服务器元数据。本进程不会缓存。

2. 配置本仓库

git clone git@github.com:scalekit-developers/scalekit-mcpuse-example.git
cd scalekit-mcpuse-example
npm install
cp .env.example .env

使用你自己的值编辑 .env。本仓库不包含任何示例凭据。

SCALEKIT_ENVIRONMENT_URL=https://your-env.scalekit.cloud
SCALEKIT_RESOURCE_ID=res_xxxxxxxx
MCP_URL=http://localhost:3000/mcp

这里没有 SCALEKIT_CLIENT_ID 或 SCALEKIT_CLIENT_SECRET。资源服务器只验证 Scalekit 已签发的令牌。

3. 运行并登录

npm run dev

1. 打开 Inspector。

2. 连接到 http://localhost:3000/mcp。第一次调用会返回 401；Inspector 会启动 Scalekit 登录。

3. 在浏览器中完成同意授权。

4. 调用 whoami。

你应该会看到一个 usr_… id、subjectType: "user"、诸如 openid / profile 的作用域，以及：

{
  "iss": "https://your-env.scalekit.cloud",
  "aud": ["http://localhost:3000/mcp", "res_xxxxxxxx"]
}

iss 也可能是 https://your-env.scalekit.cloud/resources/res_xxxxxxxx。在 Scalekit 迁移 issuer 值期间，本示例接受这两种格式。

然后调用 greet。问候语会使用来自已验证令牌的 ctx.auth.user.id —— 这就是按用户限定工具数据范围的模式。

验证的工作原理

oauth: oauthScalekitProvider({
  environmentUrl: process.env.SCALEKIT_ENVIRONMENT_URL!,
  resourceId: process.env.SCALEKIT_RESOURCE_ID!,
  resource: process.env.MCP_URL!,
}),

resourceId 是 JWT 的 aud（res_…）。resource 是公共 MCP URL。mcp-use 将 resource 放入 RFC 9728 protected-resource 元数据中。它不是第二次受众检查。

resourceId 是每台服务器的安全边界。为同一 Scalekit 环境中另一台 MCP 服务器签发的令牌必须验证失败。

授权应放在工具旁边：

async (_args, ctx) => {
  // ctx.auth.user.id is this caller — scope your data to it
  if (!ctx.auth.scopes.includes("todos:write")) {
    return { isError: true, content: [{ type: "text", text: "Missing scope" }] };
  }
};

oauth/scalekit.ts 是一流 mcp-use/oauth/scalekit 适配器的原型。它尚未发布到 npm。

项目结构

更改公共 URL

如果你要暴露服务器（隧道、部署、自定义主机）：

1. 在 Scalekit 中将 Server URL 设置为该 origin + /mcp（无末尾斜杠）。

2. 将 MCP_URL 设置为相同的字符串。

3. 重启此进程。

验证器无需更改。resourceId 仍然是受众检查。

故障排查

Scalekit 还发布了一份 MCP Auth 故障排查 指南。

安全

• 不要将客户端密钥、API 密钥或个人环境 URL 放入本仓库。

• .env 已加入 gitignore。只提交 .env.example。

• 此进程绝不会使用客户端密钥调用 Scalekit。它只验证 Bearer 令牌。

• MCP_USE_OAUTH_DEBUG=1 会解码 JWT payload 中的 iss / aud / sub。它不会打印令牌。

文档

• 使用 Scalekit 认证 mcp-use 服务器

• Scalekit MCP Auth 快速入门

• Scalekit MCP 概述

• mcp-use

• MCP 授权规范