mcp-use + Scalekit MCP Auth

An mcp-use MCP server that authenticates with Scalekit OAuth 2.1.

Teammates share one server URL. Each person signs in. Tools see their identity (ctx.auth.user.id), not a shared API key.

This example does not use @scalekit-sdk/node and does not need a Scalekit client id or secret. The resource server verifies JWTs against Scalekit JWKS.

The cookbook-style how-to lives in docs/v2/typescript/server/authentication/providers/scalekit.mdx. This README is the runbook for this repository.

What you get

• Streamable HTTP MCP at /mcp

• 401 + WWW-Authenticate pointing at RFC 9728 protected-resource metadata

• Scalekit as the authorization server (DCR and CIMD)

• whoami — authenticated user, scopes, and token iss / aud

• greet — a tool that keys off ctx.auth.user.id

Related MCP server: Access Self-Hosted MCP Server

How a client signs in

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

Prerequisites

• Node.js 22.22.2 or newer

• A Scalekit account (sign up if you do not have one)

• At least one auth method enabled (Google, GitHub, passwordless, or enterprise SSO)

1. Register an MCP server in Scalekit

Follow the MCP Auth quickstart with these values:

1. Open Scalekit Dashboard → MCP servers → Add MCP server.

2. Give it a name. That name appears on the consent screen.

3. Enable dynamic client registration and Client ID Metadata Document (CIMD). Public clients such as Inspector, Claude, and Cursor need at least one of these; keep both on.

4. Under advanced settings, set Server URL to:

   http://localhost:3000/mcp

   No trailing slash. When set, Scalekit writes this URL into the access-token aud claim alongside the res_… id. If you leave it empty, aud is only res_… — this example still verifies.

5. Save. Copy from the server page:

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

   • Resource ID — res_…

2. Configure this repo

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

Edit .env with your values. There are no sample credentials in this repo.

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

There is no SCALEKIT_CLIENT_ID or SCALEKIT_CLIENT_SECRET. The resource server only verifies tokens that Scalekit already issued.

3. Run and sign in

npm run dev

1. Open Inspector.

2. Connect to http://localhost:3000/mcp. The first call returns 401; Inspector starts Scalekit login.

3. Complete consent in the browser.

4. Call whoami.

You should see a usr_… id, subjectType: "user", scopes such as openid / profile, and:

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

iss may also be https://your-env.scalekit.cloud/resources/res_xxxxxxxx. This example accepts both while Scalekit migrates issuer values.

Then call greet. The greeting uses ctx.auth.user.id from the verified token — that is the pattern for scoping tool data per user.

How verification works

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

resourceId is the per-server security boundary. A token minted for a different MCP server in the same Scalekit environment must fail.

Authorization belongs next to the tool:

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 is a prototype of a first-class mcp-use/oauth/scalekit adapter. It is not published on npm yet.

Project structure

Changing the public URL

If you expose the server (tunnel, deploy, custom host):

1. Set Server URL in Scalekit to that origin + /mcp (no trailing slash).

2. Set MCP_URL to the same string.

3. Restart this process.

The verifier does not change. resourceId stays the audience check.

Troubleshooting

Scalekit also publishes a MCP auth troubleshooting guide.

Security

• Do not put client secrets, API keys, or personal environment URLs in this repository.

• .env is gitignored. Commit only .env.example.

• This process never calls Scalekit with a client secret. It only verifies bearer tokens.

• MCP_USE_OAUTH_DEBUG=1 decodes the JWT payload for iss / aud / sub. It does not print the token.

Docs

• Authenticate an mcp-use server with Scalekit

• Scalekit MCP Auth quickstart

• Scalekit MCP overview

• mcp-use

• MCP authorization spec