---
title: "Name every missing scope in one challenge · Agent Wranglers"
url: https://agentwranglers.se/playbook/agents-as-users/delegated-access-and-consent/scope-challenge
id: AGT-32
level: Recommended
applies: public-api
updated: 2026-10-27
build: a2a6bdfed830
tokens: 1210
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Name every missing scope in one challenge

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Delegated access and consent](https://agentwranglers.se/playbook/agents-as-users/delegated-access-and-consent.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: AGT-32
- Level: Recommended
- Chapter: [Delegated access and consent](https://agentwranglers.se/playbook/agents-as-users/delegated-access-and-consent.md)
- Rule: When a token lacks a scope a call needs, answer 403 with `error="insufficient_scope"`, every scope the call needs in `scope`, and the `resource_metadata` address.
- Check: Call a tool that needs `files:read files:write` with a token that holds only `files:read`. The answer is 403 with `error="insufficient_scope"`, a `scope` value holding both scopes, and a `resource_metadata` URL that answers 200.
- Applies when: The project offers an API to others.
- Spec version: MCP 2026-07-28
- Review by: 2027-04-30
- How: An agent can only ask its person for more access when it knows which scopes to ask for. A bare 403 leaves it guessing. A challenge that names one missing scope at a time sends the person through consent again and again. Work out every scope the call needs from its arguments, then list them all in one `WWW-Authenticate` header. Treat a broader scope as covering the narrower ones it implies. Keep `offline_access` out of the list, because refresh tokens are not a resource requirement. The 401 for a missing token is in [describe how to get access](https://agentwranglers.se/playbook/website/standard-addresses/oauth-authorization-server.md). The person then sees [the agent named on the consent screen](https://agentwranglers.se/playbook/agents-as-users/delegated-access-and-consent/agent-on-consent-screen.md).

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### HTTP example

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

### JavaScript example

```js
const RESOURCE_METADATA = 'https://mcp.example.com/.well-known/oauth-protected-resource';

export function scopeChallenge(neededScopes, grantedScopes) {
  if (neededScopes.every(scope => grantedScopes.includes(scope))) return null;
  return { status: 403, header: `Bearer error="insufficient_scope", scope="${neededScopes.join(' ')}", resource_metadata="${RESOURCE_METADATA}"` };
}
```

### Python example

```python
RESOURCE_METADATA = "https://mcp.example.com/.well-known/oauth-protected-resource"

def scope_challenge(needed_scopes: list[str], granted_scopes: set[str]) -> dict | None:
    if all(scope in granted_scopes for scope in needed_scopes):
        return None
    scopes = " ".join(needed_scopes)
    return {"status": 403, "header": f'Bearer error="insufficient_scope", scope="{scopes}", resource_metadata="{RESOURCE_METADATA}"'}
```

## Sources

- [MCP authorization, scope challenge handling](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization)
- [RFC 6750 (Bearer tokens, insufficient_scope)](https://www.rfc-editor.org/rfc/rfc6750#section-3.1)

## Related rules

- WEB-173 [Publish your sign-in server settings](https://agentwranglers.se/playbook/website/standard-addresses/oauth-authorization-server.md) in Website
- AGT-8 [Name the agent on the consent screen](https://agentwranglers.se/playbook/agents-as-users/delegated-access-and-consent/agent-on-consent-screen.md) in Agents as users
- AGT-37 [Publish protected resource metadata for every MCP server that needs sign-in](https://agentwranglers.se/playbook/agents-as-users/delegated-access-and-consent/mcp-protected-resource-metadata.md) in Agents as users

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/agents-as-users/delegated-access-and-consent/scope-challenge">Agent Wranglers agents as users playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Give agent grants short lives](https://agentwranglers.se/playbook/agents-as-users/delegated-access-and-consent/short-agent-grants.md)
- Next: [Send the issuer with every authorization response](https://agentwranglers.se/playbook/agents-as-users/delegated-access-and-consent/issuer-in-authorization-response.md)
- [Delegated access and consent](https://agentwranglers.se/playbook/agents-as-users/delegated-access-and-consent.md)