Repository navigation
SEP-1489: Tool Error Responses for Triggering OAuth Flows #1489
Description
SEP: Tool Error Responses for Triggering OAuth Flows
Authors: Duke Kim ([email protected]), Thiago Hirai ([email protected])
Status: Draft
Sponsor: Nick Cooper ([email protected])
Type: Standards Track
Created: 2025-09-17
Summary
When a tool requires authentication at runtime, it can return an error that tells clients to start an OAuth flow. The signal is carried in the tool’s _meta field under mcp/www_authenticate, which contains one or more WWW-Authenticate header values (per RFC 9278).
Clients that understand this convention will:
- Parse the WWW-Authenticate challenge
- Extract the resource_metadata URI
- Fetch authorization server metadata
- Run the OAuth flow as defined in MCP
Motivation
Even with static securitySchemes, clients sometimes hit runtime failures (e.g. scope mismatched tokens). This mechanism provides a clear, machine-readable signal that authentication is needed, plus enough metadata for clients to resolve which auth server to use.
Design
Error Response Shape
A tool signals “auth required” by sending a ToolResponse with:
- isError: true
- _meta.mcp/www_authenticate: a string or array of strings containing RFC-compliant WWW-Authenticate header values
- content: still required by the MCP spec, but mainly for human-readable display and old client compatibility
Example
"jsonrpc": "2.0",
"id": 4,
"result": {
"content": [
{
"type": "text",
"text": "Authentication required: no access token provided."
}
],
"_meta": {
"mcp/www_authenticate": [
"Bearer error=\"invalid_request\" error_description=\"No access token was provided\" resource_metadata=\"https://auth.openai.com\""
]
},
"isError": true
}
}
Client Behavior
- Detect isError: true.
- Display content if needed for the user.
- If _meta.mcp/www_authenticate is present:
- Parse challenge(s)
- Extract resource_metadata
- Fetch metadata and locate the authorization server
- Trigger the OAuth flow (per MCP spec)
- Retry the tool call if a token is obtained
Server Behavior
- Always include content (for spec compliance and old clients
- Return a standards-compliant WWW-Authenticate header value inside _meta.mcp/www_authenticate
- Ensure resource_metadata points to a valid metadata document
- Leave actual token enforcement to the authorization server
Compatibility
- Optional mechanism: servers can choose to implement or not.
- Backward-compatible: old clients ignore the field in _meta and just display the error.
Security Notes
- Clients must validate resource_metadata documents before trusting them
- Servers should not return misleading or incorrect metadata URIs
- This only advertises auth needs; token enforcement remains the same
Activity
[-]SEP: Tool Error Responses for Triggering OAuth Flows[/-][+]SEP-1489: Tool Error Responses for Triggering OAuth Flows[/+]ggoodman commentedon Sep 18, 2025
Here's a slightly different approach that tried to generalize and solve the same issue: https://github.com/orgs/modelcontextprotocol/discussions/405
max-stytch commentedon Sep 18, 2025
Check out #835 which is extremely similar in terms of letting the MCP Server drive OAuth flows at tool-call time using
WWW-Authenticateheaders. One potential point of discussion is that (835) today binds the authorization tightly to the HTTP transport - yours is transport independent.localden commentedon Sep 18, 2025
I second what @max-stytch suggested - #835 covers the bulk of the scenarios here, it seems. I am not so sure about transport-agnosticism here, TBH, mainly because a local (STDIO)-based server can do a lot of things directly within the environment without having to rely on transport logic.
It also may be a personal preference speaking here, but feels a bit odd to start embedding HTTP header logic into
_meta.pcarleton commentedon Sep 19, 2025
I think transport agnostic auth is interesting, but would require more than just this proposal to work. As in, the token would need to be passed somehow in the
stdiomessage negotiation. I'd be in favor of closing this in favor of #835 and discussing transport agnostic auth separately.github-actions commentedon Jan 16, 2026
Maintainer Activity Check
Hi @nickcoai!
You're assigned to this SEP but there hasn't been any activity from you in 119 days.
Please provide an update on:
If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.
This is an automated message from the SEP lifecycle bot.
sep-automation-bot commentedon Feb 2, 2026
Maintainer Activity Check
Hi @nickcoai!
You're assigned to this SEP but there hasn't been any activity from you in 16 days.
Please provide an update on:
If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.
This is an automated message from the SEP lifecycle bot.
sep-automation-bot commentedon Feb 16, 2026
Maintainer Activity Check
Hi @nickcoai!
You're assigned to this SEP but there hasn't been any activity from you in 14 days.
Please provide an update on:
If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.
This is an automated message from the SEP lifecycle bot.
sep-automation-bot commentedon Mar 9, 2026
Maintainer Activity Check
Hi @nickcoai!
You're assigned to this SEP but there hasn't been any activity from you in 20 days.
Please provide an update on:
If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.
This is an automated message from the SEP lifecycle bot.
sep-automation-bot commentedon Mar 23, 2026
Maintainer Activity Check
Hi @nickcoai!
You're assigned to this SEP but there hasn't been any activity from you in 14 days.
Please provide an update on:
If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.
This is an automated message from the SEP lifecycle bot.
sep-automation-bot commentedon Apr 6, 2026
Maintainer Activity Check
Hi @nickcoai!
You're assigned to this SEP but there hasn't been any activity from you in 14 days.
Please provide an update on:
If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.
This is an automated message from the SEP lifecycle bot.
sep-automation-bot commentedon Apr 20, 2026
Maintainer Activity Check
Hi @nickcoai!
You're assigned to this SEP but there hasn't been any activity from you in 14 days.
Please provide an update on:
If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.
This is an automated message from the SEP lifecycle bot.
sep-automation-bot commentedon May 4, 2026
Maintainer Activity Check
Hi @nickcoai!
You're assigned to this SEP but there hasn't been any activity from you in 14 days.
Please provide an update on:
If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.
This is an automated message from the SEP lifecycle bot.
sep-automation-bot commentedon May 18, 2026
Maintainer Activity Check
Hi @nickcoai!
You're assigned to this SEP but there hasn't been any activity from you in 14 days.
Please provide an update on:
If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.
This is an automated message from the SEP lifecycle bot.
sep-automation-bot commentedon Jun 1, 2026
Maintainer Activity Check
Hi @nickcoai!
You're assigned to this SEP but there hasn't been any activity from you in 14 days.
Please provide an update on:
If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.
This is an automated message from the SEP lifecycle bot.
sep-automation-bot commentedon Jun 15, 2026
Maintainer Activity Check
Hi @nickcoai!
You're assigned to this SEP but there hasn't been any activity from you in 14 days.
Please provide an update on:
If you're no longer able to sponsor this SEP, please let us know so we can find another maintainer.
This is an automated message from the SEP lifecycle bot.
Add Haikus for Mona HTML content
localden commentedon Jun 26, 2026
Closing as #835 landed for step-up auth. Thank you for the contribution, @thiago-openai!