createmcps.com

MCP-AUT-007

Insufficient scope returns 403 with error="insufficient_scope"

“The server SHOULD respond with HTTP 403 Forbidden and a WWW-Authenticate header with error="insufficient_scope".” — spec anchor

How to fix this

When a request carries a valid token that lacks the scope it needs, respond with 403 Forbidden and a `WWW-Authenticate` header carrying `error="insufficient_scope"` and the scope actually required (RFC 6750 §3.1) — that is what lets the client step up its authorization instead of failing silently.

Example: failing and passing

A valid token that lacks the files:write scope gets a bare 403, so the client cannot tell which scope to ask for.
Violates MCP-AUT-007 · HTTP
POST /mcp HTTP/1.1
Host: mcp.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Mcp-Method: tools/call
Mcp-Name: write_file
...

HTTP/1.1 403 Forbidden
The server answers 403 with error="insufficient_scope" and the scope the operation needs, so the client can step up.
Complies with MCP-AUT-007 · HTTP
POST /mcp HTTP/1.1
Host: mcp.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Mcp-Method: tools/call
Mcp-Name: write_file
...

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
                         scope="files:write",
                         resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource"

How the validator checks this

Probe P8.1, against a streamable-http server on the modern protocol. What it reports:

skip
No authorization, so insufficient-scope handling does not apply

Quoted from the probe that runs this check, so it cannot drift from what the validator actually reports.

This rule is checked heuristically: a fail is inferred rather than certain, so it bumps the overall grade up one level instead of being treated as certain non-compliance.

Checked in the same request as MCP-AUT-001, MCP-AUT-006, MCP-AUT-008, MCP-SEC-007.

Check your own server against MCP-AUT-007

Probe P8.1 checks MCP-AUT-007 in the same request as 4 other rules, so one run shows your server's result for this rule next to the rest. Validate a server or read how the validator works.

Background on this topic: how to add OAuth to an MCP server.

Other Authorization rules

  • MCP-AUT-001Unauthenticated request returns 401 with WWW-Authenticate resource_metadata
  • MCP-AUT-002RFC 9728 Protected Resource Metadata is served and valid
  • MCP-AUT-003PRM resource equals the canonical server URI
  • MCP-AUT-004Each listed authorization server exposes RFC 8414 or OIDC discovery metadata
  • MCP-AUT-005AS advertises authorization_response_iss_parameter_supported: true
  • MCP-AUT-006WWW-Authenticate includes a scope parameter
  • MCP-AUT-008Tokens with a foreign audience are rejected
  • MCP-AUT-009offline_access absent from scopes_supported / challenge scope
  • MCP-AUT-010AS advertises S256 in code_challenge_methods_supported
  • MCP-AUT-011AS supports Client ID Metadata Documents, not DCR alone