Authorize mcp-use tools with Scalekit scopes

Sign a user in with Scalekit, grant todo:read and todo:write, and prove allow and deny in the mcp-use Inspector.

An mcp-use server is one URL that many hosts share. Scalekit login tells you who called. It does not decide which tools that person may run.

Without a scope check, list_todos and add_todo are both open to every signed-in user. mcp-use still lists the write tool when the write scope is missing. The handler must refuse.

By the end of this recipe, you sign in with todo:read only, list todos, and see add_todo return Missing scope todo:write. That deny path is the test.

This is for an mcp-use v2 resource server over Streamable HTTP. If you use FastMCP instead, see the FastMCP quickstart. That guide uses the same todo:read / todo:write scopes.

A valid token only proves Scalekit issued it for this MCP server. Every tool still runs unless you check a scope.

Login proves	A scope check proves
The caller signed in with Scalekit	This caller may run this tool
The token `aud` includes this `res_…`	The grant string matches the handler

Four other facts make the deny path easy to miss:

mcp-use still lists the tool. A missing scope does not hide add_todo in Inspector.
Scopes live in two places. You create todo:read and todo:write on the Scalekit MCP server. You check the same strings in ctx.auth.scopes. A mismatch looks like a random 403.
Consent is sticky. If you add a scope after the first login, the existing token does not gain it. The user must sign in again.
resource is not aud. resourceId is the JWT audience (res_…). resource (MCP_URL) is the public MCP URL. mcp-use puts resource in RFC 9728 protected-resource metadata.

Who this recipe is for

Use this recipe when:

You run mcp-use over Streamable HTTP
Users must sign in with Scalekit before they call tools
Some tools are read-only and some tools write

Skip this recipe when you only need a shared machine credential and no user identity. For Scalekit M2M JWT verification on a regular API, see M2M JWT verification with JWKS and OAuth scopes.

Two tools, two scopes

Scalekit issues an OAuth 2.1 access token that lists the scopes the user granted. mcp-use verifies that token with oauthScalekitProvider. Each tool then checks ctx.auth.scopes before it runs.

Use two tools and two scopes, the same pair as the FastMCP todo app:

Tool	Required scope	What it does
`list_todos`	`todo:read`	Lists todos owned by `ctx.auth.user.id`
`add_todo`	`todo:write`	Creates a todo for that user

mcp-use does not enforce those scopes for you. The check belongs next to the tool.

Four checks in Inspector

The recipe succeeds when all of this is true:

You sign in and grant todo:read only.
whoami shows a usr_… id, subjectType: "user", and todo:read.
list_todos succeeds.
add_todo is visible and returns Missing scope todo:write.

A green whoami is not enough.

Register the MCP server and add scopes

Scalekit issues the token. Your process only verifies it. There is no Scalekit client id or secret on the resource server.

Prerequisites: Node.js 22.22.2 or newer, a Scalekit account, and at least one auth method enabled.

Add the MCP server
Section titled “Add the MCP server”

Open Scalekit Dashboard → MCP servers → Add MCP server. Give it a name. That name appears on the consent screen.
Enable DCR and CIMD
Section titled “Enable DCR and CIMD”

Turn on dynamic client registration and Client ID Metadata Document (CIMD). Inspector needs at least one of these. Keep both on.

Reconnect the MCP client after you change DCR or CIMD. Inspector and other clients cache authorization-server metadata. This process does not.
Set the Server URL with no trailing slash
Section titled “Set the Server URL with no trailing slash”

Under advanced settings, set Server URL to:
```
1
http://localhost:3000/mcp
```
Do not add a trailing slash. mcp-use requires the resource path to equal the server base path. A deployed origin uses https://mcp.example.com/mcp.
Create the two scopes
Section titled “Create the two scopes”

Create or link these scopes on the same MCP server, then save:

Scope Description
todo:read List todos
todo:write Create todos

These strings must match the checks in your tools exactly.

Scope	Description
`todo:read`	List todos
`todo:write`	Create todos

Copy the three values

Value	Where it appears
Environment URL	Dashboard → API credentials → `https://<your-env>.scalekit.cloud`
Resource ID	This MCP server page → `res_…`
Public MCP URL	The same string as Server URL (no trailing slash)

resourceId is the audience check. A token minted for a different MCP server in the same environment must fail.

Authenticate the mcp-use server

1
# Never hard-code secrets. Use environment variables.
2
npm install mcp-use zod

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

Pass those three values into the published factory. Advertise the same scopes Scalekit offers, so Inspector can request them:

1
import { MCPServer } from 'mcp-use'
2
import { oauthScalekitProvider } from 'mcp-use/oauth/scalekit'
3
import { z } from 'zod'
4

5
function requiredEnv(name: string): string {
6
  const value = process.env[name]?.trim()
7
  if (!value) {
8
    throw new TypeError(
9
      `${name} is missing. Copy .env.example to .env and fill in values from your Scalekit dashboard.`,
10
    )
11
  }
12
  return value
13
}
14

15
const server = new MCPServer({
16
  name: 'todo-mcp',
17
  version: '1.0.0',
18
  oauth: oauthScalekitProvider({
19
    environmentUrl: requiredEnv('SCALEKIT_ENVIRONMENT_URL'),
20
    resourceId: requiredEnv('SCALEKIT_RESOURCE_ID'),
21
    resource: requiredEnv('MCP_URL'),
22
    scopesSupported: ['todo:read', 'todo:write'],
23
  }),
24
  publicLandingPage: true,
25
})

resource must match the Scalekit Server URL exactly. It is not a second aud check.

publicLandingPage: true keeps the HTML page public. /mcp stays bearer-gated. The tool checks below still apply if a client requests fewer scopes than you advertise.

Guard each tool with a scope

Store todos per user. Check the scope first. A missing scope returns an error. It does not throw an HTTP 401. The user is already authenticated.

1
type Todo = { id: string; title: string; ownerId: string }
2

3
const todos = new Map<string, Todo[]>()
4

5
function requireScope(ctx: { auth: { scopes: string[] } }, scope: string) {
6
  if (!ctx.auth.scopes.includes(scope)) {
7
    return {
8
      isError: true,
9
      content: [{ type: 'text', text: `Missing scope ${scope}` }],
10
    }
11
  }
12
  return undefined
13
}
14

15
server.tool(
16
  {
17
    name: 'list_todos',
18
    description: 'List todos for the signed-in user. Requires todo:read.',
19
    outputSchema: z.object({
20
      todos: z.array(
21
        z.object({
22
          id: z.string(),
23
          title: z.string(),
24
        }),
25
      ),
26
    }),
27
  },
28
  async (_args, ctx) => {
29
    const denied = requireScope(ctx, 'todo:read')
30
    if (denied) return denied
31

32
    const items = todos.get(ctx.auth.user.id) ?? []
33
    return {
34
      content: [{ type: 'text', text: JSON.stringify(items) }],
35
      structuredContent: {
36
        todos: items.map(({ id, title }) => ({ id, title })),
37
      },
38
    }
39
  },
40
)
41

42
server.tool(
43
  {
44
    name: 'add_todo',
45
    description: 'Create a todo for the signed-in user. Requires todo:write.',
46
    inputSchema: z.object({
47
      title: z.string().min(1),
48
    }),
49
    outputSchema: z.object({
50
      id: z.string(),
51
      title: z.string(),
52
    }),
53
  },
54
  async (args, ctx) => {
55
    const denied = requireScope(ctx, 'todo:write')
56
    if (denied) return denied
57

58
    const item = {
59
      id: crypto.randomUUID(),
60
      title: args.title,
61
      ownerId: ctx.auth.user.id,
62
    }
63
    const items = todos.get(ctx.auth.user.id) ?? []
64
    items.push(item)
65
    todos.set(ctx.auth.user.id, items)
66
    return {
67
      content: [{ type: 'text', text: JSON.stringify(item) }],
68
      structuredContent: { id: item.id, title: item.title },
69
    }
70
  },
71
)
72

73
export default server

ctx.auth.user.id is the token sub. Use it as the owner key. Do not treat a subjectType: "machine" caller as a person if your product is user-only.

Add a whoami tool so Inspector can show the signed-in user and the granted scopes before you test writes:

1
server.tool(
2
  {
3
    name: 'whoami',
4
    description: 'Return the signed-in Scalekit user and granted scopes',
5
  },
6
  async (_args, ctx) => {
7
    const data = {
8
      user: ctx.auth.user,
9
      scopes: ctx.auth.scopes,
10
    }
11
    return {
12
      content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
13
    }
14
  },
15
)

Prove allow and deny in Inspector

1
npm run dev

Endpoint	URL
MCP	`http://localhost:3000/mcp`
Inspector	`http://localhost:3000/mcp/inspector`

Leave Inspector’s client-id fields empty. This flow uses DCR or CIMD.

Sign in with read only
Section titled “Sign in with read only”

Open Inspector. Connect to http://localhost:3000/mcp. The first call returns 401. Inspector starts Scalekit login. Complete consent. Grant todo:read only on the first pass.
Confirm identity
Section titled “Confirm identity”

Call whoami. You should see a usr_… id, subjectType: "user", and scopes that include todo:read. Do not paste live ids into docs or tickets.
Prove the allow path
Section titled “Prove the allow path”

Call list_todos. The call succeeds. The list may be empty.
Prove the deny path
Section titled “Prove the deny path”

Call add_todo with { "title": "Ship scopes" }. The tool is visible. The handler returns Missing scope todo:write. That is the test.
Grant write and retry
Section titled “Grant write and retry”

Sign out. Sign in again and grant todo:write as well. Call add_todo. The todo appears. Call list_todos. You see only your items.

A public URL change is two matching updates: Scalekit Server URL and MCP_URL. Restart the process. resourceId stays the audience check.

Troubleshooting

Symptom	Fix
Inspector never starts login	If DCR and CIMD are both off, turn at least one on and save. If they are already on, reconnect Inspector. Clients cache authorization-server metadata.
`add_todo` is visible but returns `Missing scope todo:write`	mcp-use does not hide tools by scope. This is the deny path. Grant `todo:write` and sign in again.
Scope is on the dashboard but not on the token	Consent is sticky. Disconnect Inspector and sign in again.
Every call returns `Missing scope todo:read`	Dashboard string does not match the code. Use `todo:read` and `todo:write` in both places.
Login works, every tool is 401	Scalekit Server URL does not match `MCP_URL`. Check trailing slash, port, and `http` vs `https`.
`Cannot find module 'mcp-use/oauth/scalekit'`	The factory is not in the installed mcp-use release yet. Wait for the release that includes mcp-use#2272, or run the example.
Need claim details on a 401	Set `MCP_USE_OAUTH_DEBUG=1`. Logs print `iss`, `aud`, and `sub`. Logs never print the raw token.

What to do next

Clone scalekit-mcpuse-example if the published import is not on npm yet.
Compare the same scopes on FastMCP in the FastMCP quickstart.
Register more MCP servers in the MCP Auth quickstart.
Replace the in-memory Map with a database keyed by ctx.auth.user.id.
Refuse subjectType: "machine" on user-only tools.

Authorize mcp-use tools with Scalekit scopes

Login is not authorization

Who this recipe is for

Two tools, two scopes

Four checks in Inspector

Register the MCP server and add scopes

Add the MCP server

Enable DCR and CIMD

Set the Server URL with no trailing slash

Create the two scopes

Copy the three values

Authenticate the mcp-use server

Guard each tool with a scope

Prove allow and deny in Inspector

Sign in with read only

Confirm identity

Prove the allow path

Prove the deny path

Grant write and retry

Troubleshooting

What to do next