SEP: Tool Error Responses for Triggering OAuth Flows

Authors: Duke Kim (duke@openai.com), Thiago Hirai (thiago@openai.com)
Status: Draft
Sponsor: Nick Cooper (nickc@openai.com)
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