mcp-use + Scalekit MCP Auth

MCP-сервер для mcp-use, который аутентифицируется через Scalekit OAuth 2.1.

У коллег один и тот же URL сервера. Каждый пользователь входит в систему. Инструменты видят его идентичность (ctx.auth.user.id), а не общий ключ API.

Этот пример не использует @scalekit-sdk/node и не требует client id или client secret от Scalekit. Ресурсный сервер проверяет JWT против JWKS Scalekit.

Пошаговое руководство (cookbook) находится в docs/v2/typescript/server/authentication/providers/scalekit.mdx. Этот README — инструкция по запуску для этого репозитория.

[!IMPORTANT] Используйте своё окружение Scalekit. В этом репозитории только заглушки. Никогда не коммитьте .env.

Что вы получаете

• Streamable HTTP MCP на /mcp

• 401 + WWW-Authenticate, указывающий на метаданные защищённого ресурса RFC 9728

• Scalekit как сервер авторизации (DCR и CIMD)

• whoami — аутентифицированный пользователь, области (scopes) и 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, passwordless или корпоративный SSO)

1. Зарегистрируйте MCP-сервер в Scalekit

Следуйте краткому руководству по MCP Auth со следующими значениями:

1. Откройте панель управления Scalekit → MCP servers → Add MCP server.

2. Дайте ему имя. Это имя появится на экране согласия.

3. Включите динамическую регистрацию клиентов и Client ID Metadata Document (CIMD). Публичным клиентам, таким как Inspector, Claude и Cursor, нужен хотя бы один из этих параметров; оставьте оба включёнными.

4. В дополнительных настройках установите Server URL на:

   http://localhost:3000/mcp

   Без завершающего слэша. Если этот URL задан, Scalekit записывает его в утверждение aud access-токена вместе с res_… id. Если оставить поле пустым, aud будет только res_… — пример всё равно работает.

5. Сохраните. Скопируйте со страницы сервера:

   • Environment URL — https://<ваше-окружение>.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", области (scopes) типа openid / profile, а также:

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

iss также может быть https://ваше-окружение.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 — публичный URL MCP. mcp-use помещает resource в метаданные защищённого ресурса RFC 9728. Это не вторая проверка аудитории.

resourceId — это граница безопасности каждого сервера. Токен, выпущенный для другого MCP-сервера в том же окружении Scalekit, должен отклоняться.

Авторизация должна жить рядом с инструментом:

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. Установите Server URL в Scalekit как origin + /mcp (без завершающего слэша).

2. Установите MCP_URL в ту же строку.

3. Перезапустите процесс.

Верификатор не меняется. resourceId остаётся проверкой аудитории.

Устранение неполадок

Scalekit также публикует руководство по устранению неполадок MCP Auth.

Безопасность

• Не храните клиентские секреты, ключи API или личные URL окружений в этом репозитории.

• .env игнорируется через git. Коммитьте только .env.example.

• Этот процесс никогда не обращается к Scalekit с клиентским секретом. Он только проверяет bearer-токены.

• MCP_USE_OAUTH_DEBUG=1 декодирует полезную нагрузку JWT для iss / aud / sub. Он не печатает сам токен.

Документация

• Аутентификация сервера mcp-use с Scalekit

• Краткое руководство по MCP Auth в Scalekit

• Обзор MCP в Scalekit

• mcp-use

• Спецификация авторизации MCP