feat(server): scope challenges for resources, prompts, completions (stacked on #1624)

[SamMorrowDrums]

Stacked on top of #1624. Until that merges, the diff in this PR will include those commits; once #1624 merges this PR will rebase cleanly against main.

Summary

Extends the pre-execution scope challenge check from tools/call to the rest of the MCP operation surface: resources/read, prompts/get, and completion/complete.

Same architecture, same opinions on per-operation scopes, AND/OR semantics, and SEP-2350 alignment, just generalised across primitives.

What's new

Resources

registerResource() now accepts scopes in its config. For templated resources, scopes can also be a function that receives the concrete URI and matched template variables, so the required scope can depend on path parameters (for example, public vs private repositories).

// Static URI, static scope
server.registerResource(
  'config',
  'config://settings',
  { scopes: ['config:read'], mimeType: 'text/plain' },
  readCallback,
);

// Templated URI, dynamic per-request scope resolution
server.registerResource(
  'repo',
  new ResourceTemplate('github://{owner}/{repo}', { list: undefined }),
  { scopes: (_uri, vars) => vars.owner === 'private-org' ? ['repo'] : ['public_repo'] },
  readCallback,
);

Prompts

registerPrompt() accepts scopes in its config. Exact-name lookup like tools.

server.registerPrompt(
  'summarise_repo',
  { description: 'Summarise a repo', scopes: ['repo:read'], argsSchema: ... },
  handler,
);

Completions

Completions get an explicit, separate scope domain. No inheritance from the referenced prompt or resource by design: search and read are typically distinct capabilities (repo:list is not implied by repo:read). If you genuinely want them identical, pass the same scopes array to both registerPrompt and setCompletionScopes.

server.setCompletionScopes(
  { type: 'ref/prompt', name: 'summarise_repo' },
  'repository',   // or '*' for any argument of this ref
  ['repo:list'],
);

Central overrides

For decoupled or centralised scope configuration: setPromptScopes(name, scopes), setResourceScopes(uriOrTemplateName, scopes), setCompletionScopes(ref, arg, scopes). All take precedence over registration-time scopes.

Architecture

• ScopeResolver widens from (toolName) => ToolScopeConfig to (request: JSONRPCRequest) => ScopeResolution | Promise<...>. Breaking for any alpha consumer of setScopeResolver; no external consumers yet.
• New ScopeResolution = { operationName: string; scopes: ToolScopeConfig }. The operationName (e.g. tool:get_repo, resource:github://octo/hello, prompt:summarise, completion:prompt:summarise/repository) is used in the default 403 error description and is passed to buildErrorDescription.
• _checkScopeChallenge becomes async to support async resource resolvers.
• McpServer.connect() auto-wires an operation-aware router that dispatches on JSON-RPC method.

What's NOT in scope

• */list scope filtering (SEP-1881). When tools, resources, or prompts declare scopes, tools/list, resources/list, prompts/list, and resources/templates/list could automatically filter their results to items the current token can satisfy. Intentionally out of scope for this PR but worth a follow-up.
• Mid-handler scope challenges. Same constraint as feat(server): OAuth scope challenge support (step-up auth) #1624: HTTP status codes are committed before handlers run.

Testing

14 new behaviour tests in scopeChallengePrimitives.test.ts covering:

• Static and templated resources: 403, pass, no-scopes passthrough, template URI matching, dynamic per-request resolution.
• Prompts: 403, pass, no-scopes passthrough.
• Completions: 403, no-inheritance contract, '*' argument wildcard.
• Override registries: setResourceScopes, setPromptScopes.
• Mixed JSON-RPC batch with a prompt and a resource read; the first failing operation surfaces a 403.

The 17 tool tests in scopeChallenge.test.ts continue to pass unchanged. All 96 tests in @modelcontextprotocol/server pass; typecheck and lint clean.

Notes for review

• Completion's "no inheritance" was the considered choice; it matches typical OAuth scope shapes where listing capabilities are distinct from reading. Inheritance can be added later as an opt-in ({ inherit: true } flag) if real-world usage shows it's wanted.
• accepted (OR escape hatch) extends to all primitives because it lives on ToolScopeConfig. Dynamic resource resolvers can return ToolScopeConfig directly to use accepted per-URI.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3bcf533

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@modelcontextprotocol/server	Minor
@modelcontextprotocol/node	Major
@modelcontextprotocol/express	Major
@modelcontextprotocol/fastify	Major
@modelcontextprotocol/hono	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR