A 403 insufficient_scope from a person's own MCP server is the sign_in_required answer with the scope it named, and the person's next sign-in asks for it on top of what was granted, at the same authorization server; signing out revokes the refresh token at the provider when it can be told, and forgets it whether or not¶
Decision 872 · accepted · 2026-10-11 · issue #586
Superseded in part
In part by 875.
The step-up (#586).
- The answer. The MCP client returns a
403whose challenge saysinsufficient_scopeas{:insufficient_scope, header}; any other403is the refusal it was. Listing the tools that way makes the session's serversign_in, saying the scope. One that names no scope leaves a sign-in nothing to ask for, and stays the refusal it was, described as such. - The scope asked for is the union of what the next sign-in would ask anyway (the
entry's, the
401's, the metadata's), what was granted (the token endpoint'sscope, or what was asked when it said none) and what the server named, withoffline_accessas before.mcp.sign_inanswersscopes, what the person is asked to grant, and the TUI's notice says it. - Where the sign-in goes. Only the scope is read from the
403. Itsresource_metadatais not followed: the sign-in is discovered as any is, from the server's own401and protected-resource metadata, so a403cannot send the person to another authorization server. - Who decides. Nothing signs in on its own. The step-up is a note the model relays and
a line on the page; a sign-in starts only when the person asks for one (
s,/mcp sign-in, Sign in), and the provider's consent page names the scopes. - The tokens held are kept and used until the new sign-in lands, whose entry replaces
the old one and drops
step_up. A step-up the person refuses at the provider keeps the sign-in as it was, with the refusal as its last error. - Not chosen: starting a sign-in from the
403(a server could then open a consent page on the person's screen with any call), or following the403'sresource_metadata(an issuer change belongs to the server's metadata, which a fresh sign-in reads anyway).
Revocation on sign-out (#587).
- What is revoked. The refresh token, with
token_type_hint=refresh_tokenand the client id (a public client authenticates with its id, RFC 7009 §2.1), at therevocation_endpointthe authorization server's metadata named at the sign-in, kept in the entry. An entry kept before this has the endpoint looked up from its issuer's metadata at sign-out. With no refresh token, the access token. - Forgotten first, then told.
Tokens.take/1removes the entry and answers it, and the revocation is sent outside that process. The issue's order was revoke then forget; taking first means no refresh can spend the token and keep a new one while the provider is asked, and the person waits no longer for the store. The outcome is the same: the sign-in is gone here whatever the provider says. - Where the token may go. The revocation endpoint is held to what the token endpoint is
(
OAuth.outbound/2):https, orhttpon loopback, and not at an address on Decision 856's list (Reach.refusal/1) — link-local, a cloud metadata address, the unspecified address — loopback kept, assecure/2has it. The token endpoint is now held to the same check, since both are sent the refresh token. A name is not resolved for the check, as for the token endpoint before. - When it cannot be told. A refusal, a non-2xx answer, or no answer in five seconds
(connect and receive) is
failedwith the reason; the tokens are forgotten anyway and the answer says the provider was not told. Metadata with norevocation_endpointisunsupported. Nothing held isnone. troupe logout.mcp.sign_outwithall: truesigns out of every entry in the store, by whatever name and in whatever workspace it was signed in from.troupe logoutwithout a plane named, and--all, ask the daemon for it after the plane sign-out and print a line per server that held a sign-in. Naming a plane signs out of that plane alone: these sign-ins are no plane's, and signing out of a second plane should not end them. A daemon that is not running is not started (Decision 766 does not start one for the plane token either); the CLI reads the daemon'smcp-oauth.jsonfor how many sign-ins it holds, never using what is in them, and says they were kept and why. A daemon that refuses the call (one from before this, which wants aname) is said to have kept them.
Governs: apps/troupe_core/lib/troupe/mcp/oauth.ex, apps/troupe_core/lib/troupe/mcp/oauth/sign_in.ex, apps/troupe_core/lib/troupe/mcp/tool.ex, apps/troupe_core/lib/troupe/session/mcp.ex