<p align="left"> <a href="https://scalekit.com" target="_blank" rel="noopener noreferrer"> <img src="https://cdn.scalekit.cloud/v1/scalekit-logo-dark.svg" height="64" alt="Scalekit"> </a> </p>

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.

[!IMPORTANT] Use your own Scalekit environment. This repository ships placeholders only. Never commit .env.

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

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_…

[!CAUTION] If you toggle DCR or CIMD later, restart this example. Some MCP clients cache authorization-server metadata.

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

Variable	Where it comes from
SCALEKIT_ENVIRONMENT_URL	Dashboard → API credentials → Environment URL
SCALEKIT_RESOURCE_ID	Dashboard → MCP servers → this server → res_…
MCP_URL	Must match Server URL exactly (no trailing slash)

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

MCP endpoint	http://localhost:3000/mcp
Inspector	http://localhost:3000/mcp/inspector

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!,
}),

Check	Source
Signature	JWKS at {environmentUrl}/keys (from live AS metadata — not a guessed path)
iss	Environment root or {environmentUrl}/resources/{resourceId}
aud	Must include resourceId (res_…)
Identity	ctx.auth.user.id is the token sub

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

Path	Role
index.ts	mcp-use server, OAuth wiring, whoami and greet
oauth/scalekit.ts	JWT + JWKS provider
docs/v2/.../scalekit.mdx	Cookbook: authenticate an mcp-use server with Scalekit
.env.example	Placeholders only

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

Symptom	Likely cause
Server throws on boot about SCALEKIT_* or MCP_URL	.env is missing or a value is empty
Inspector never starts login	DCR/CIMD off, or you did not restart after toggling them
Login works, every tool is 401	Server URL does not match MCP_URL (trailing slash, wrong port, http vs https)
whoami aud has only res_…	Server URL was left empty in the dashboard — still valid; this example binds on resourceId
Need claim details on a 401	Set MCP_USE_OAUTH_DEBUG=1 and retry. Logs print iss, aud, sub — never the raw token

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