[BUG] OAuth token refresh never attempted for custom connectors via mcp-proxy.anthropic.com

[ed-rajesh-muraleedharan]

What happened?

What's Wrong?

Custom MCP connectors connected via the claude.ai web UI (mcp-proxy.anthropic.com) never refresh OAuth tokens when they expire. The proxy reconnects the SSE transport and reports success, but never calls /token or /authorize on the upstream server. The expired token is then forwarded on the next tool call, which fails — requiring a full manual reconnect daily.

Note: This was originally filed as anthropics/claude-code#52905 (labeled duplicate there) and anthropics/claude-code#46328. Re-filing here as the root cause is in the claude.ai proxy layer — anthropics/claude-ai-mcp is the correct home for this bug.

---

Environment

• Client: claude.ai web (Team/Enterprise plan)
• Connector: Custom MCP server on Azure App Service
• Auth: Azure Entra ID OBO flow (external IdP)
• Transport: Streamable HTTP

What did you expect to happen?

The proxy should check token expiry before forwarding tool calls and attempt a silent refresh using the stored refresh token before falling back to a re-auth prompt — standard OAuth 2.0 refresh token grant behavior already implemented in the direct HTTP path.

Steps to reproduce

1. Set up a custom MCP server with Azure Entra ID (external IdP) OAuth — server exposes /.well-known/oauth-authorization-server with correct authorization_endpoint, token_endpoint, and grant_types_supported: ["authorization_code", "refresh_token"]
2. Add the server as a custom connector in Claude.ai Settings → Connectors
3. Complete the OAuth flow — connector shows as Connected, tools are available
4. Wait for the access token to expire (~1 hour)
5. Attempt any tool call on the connector
6. Result: Tool call fails — server receives the expired Bearer token with no prior /token refresh attempt. Connector appears disconnected. User must manually reconnect daily.

Area

OAuth / Authentication

MCP Server (if applicable)

Custom server — Azure App Service (Node.js/Express, Streamable HTTP, Azure Entra ID OBO auth)

Error messages or logs

Error in Claude Web UI (Connector page)
Connection issue
Connection has expired. You can reconnect to re-authenticate.


Server logs show zero /token or /authorize requests after initial auth.
On expired token, server returns:
HTTP 401
WWW-Authenticate: Bearer realm="Azure AD", error="invalid_token", error_description="Token validation failed"

Client behavior: SSE transport reconnects successfully but no OAuth refresh is attempted.
Expired token is forwarded on next tool call → tool call fails.

Additional context

Key Observations

1. Fix exists for direct HTTP path — token refresh was fixed for Claude Code direct HTTP connections in ~v2.1.59. The fix has not been ported to the mcp-proxy.anthropic.com proxy path.

2. Server is fully spec-compliant — /.well-known/oauth-authorization-server correctly advertises token_endpoint and grant_types_supported: ["authorization_code", "refresh_token"]. On expired token, server returns 401 with WWW-Authenticate: Bearer error="invalid_token" — a compliant client should use this to trigger a refresh. Zero /token or /authorize requests reach the server after initial auth.

3. External IdP compounds the issue — per Claude.ai ignores authorization_endpoint and token_endpoint from OAuth metadata when MCP server uses external authorization server #82, claude.ai ignores authorization_endpoint/token_endpoint from OAuth metadata for external IdPs. This means both initial auth discovery AND token refresh are broken on the proxy path for Entra ID / Okta / Auth0 setups.

4. First-party connectors unaffected — Slack, Otter etc. remain connected. Bug is specific to custom connectors via mcp-proxy.anthropic.com.

---

Related Issues

• anthropics/claude-code#46328 — same bug, claudeai-proxy transport (original report)
• anthropics/claude-code#52905 — duplicate filed in wrong repo, labeled duplicate by maintainers
• Claude.ai ignores authorization_endpoint and token_endpoint from OAuth metadata when MCP server uses external authorization server #82 — Claude.ai ignores external IdP authorization_endpoint/token_endpoint
• [BUG] claude.ai connector completes OAuth flow but never attaches Bearer token to MCP requests #155 — OAuth completes but Bearer token never attached to MCP requests
• Custom MCP server unreachable after Connections → Customize migration — server confirmed healthy via curl #188 — Custom MCP unreachable after token expiry, failing at proxy layer
• Claude remote MCP connector: Anthropic's internal /tool_result and /attach_resource return 404/400 after successful OAuth #207 — Token issued but never used after OAuth handshake

[ed-rajesh-muraleedharan]

Related issues that shed more light on the root cause:

• Claude.ai connector does case-sensitive match on WWW-Authenticate header, breaking OAuth discovery on any HTTP/2 response #219 — Claude.ai does a case-sensitive match on WWW-Authenticate. HTTP/2 mandates lowercase header names on the wire (RFC 7540 §8.1.2), so any server running behind HTTP/2 (including Azure App Service with HTTP/2 enabled by default) will send www-authenticate lowercase — which claude.ai silently ignores, never triggering OAuth discovery or token refresh.

• [BUG] claude.ai skips OAuth discovery entirely — POST /mcp → 401 × 3 → silent failure, no /register or discovery calls #217 — Claude.ai skips OAuth discovery entirely after receiving 3× 401 responses, with no calls to /.well-known/oauth-protected-resource, /register, or /authorize. Silent failure with no error surfaced to the user.

• [BUG] claude.ai custom connector fails to request server-declared scopes for Google Workspace People API — all tool calls return permission denied #218 — Related variant of the same OAuth discovery bypass.

These three issues together likely explain the token refresh failure reported in #228. Even when the server correctly returns 401 + WWW-Authenticate, if the connection is over HTTP/2 the header arrives lowercase and claude.ai never acts on it — so the refresh flow never starts, and the session expires silently.

Suggested workaround for custom connector operators until this is fixed: Force HTTP/1.1 on your origin server (e.g. Azure App Service → Configuration → General Settings → HTTP version → 1.1). This preserves title-cased header names and allows claude.ai to recognise the WWW-Authenticate header correctly.

[ed-rajesh-muraleedharan]

---

Update: Root cause identified via identity provider sign-in logs

After analyzing non-interactive sign-in logs from the identity provider for a custom Entra-backed connector, the exact failure mechanism is now clear.

What the logs show:

• Initial auth: grant_type=authorization_code → success, scoped token issued ✅
• ~1 hour later (at access token expiry): claude.ai proxy fires a refresh attempt → AADSTS90009 ❌
• Multiple users on the same connector all hit the same pattern independently

AADSTS90009 error message:
"Application is requesting a token for itself. This scenario is supported only if resource is specified using the GUID-based App Identifier."

Root cause:
The claude.ai proxy is sending the refresh token request to Entra's token endpoint without a scope parameter. Microsoft Entra requires scope to be explicitly included on every refresh request — it does not infer it from the refresh token. When scope is omitted, Entra treats the resource as the client app itself and rejects with 90009.

The correct refresh request should be:

POST /oauth2/v2.0/token
grant_type=refresh_token
client_id=<id>
client_secret=<secret>
refresh_token=<token>
scope=api://<client_id>/<custom_scope> offline_access openid profile  ← this is missing

Why it works on initial auth but not refresh:
On initial auth, claude.ai reads scopes_supported from the /.well-known/oauth-authorization-server discovery document and correctly includes the scope in the authorization URL. On refresh, the proxy omits the scope entirely — which works for most OAuth servers (they infer scope from the refresh token) but fails specifically with Microsoft Entra ID, which mandates scope on every token endpoint request per its OAuth implementation.

Environment confirmed not to be a factor:

• HTTP/1.1 enforced, HTTP/2 disabled — rules out Claude.ai connector does case-sensitive match on WWW-Authenticate header, breaking OAuth discovery on any HTTP/2 response #219
• offline_access granted at tenant level
• Both redirect URIs registered
• OAuth Client ID + Secret configured in connector Advanced Settings
• Custom scope correctly defined and consented

Suggested fix:
When constructing refresh token requests, the proxy should re-include the scope granted during the original authorization code exchange. This scope is already stored alongside the tokens — it just needs to be forwarded to the token endpoint on refresh. This would fix the issue for all Entra-backed custom connectors, not just this one.

Related: #217, #218, #219, anthropics/claude-code#46328

[ed-rajesh-muraleedharan]

Workaround: Token Proxy to Inject Missing Scope on Refresh

While waiting for a platform-side fix, here's a server-side workaround that resolves the daily disconnect for Microsoft Entra ID backed custom connectors.

Root cause (confirmed via identity provider logs):
The claude.ai proxy sends refresh_token grant requests to the token endpoint with no scope parameter. Most OAuth servers infer scope from the refresh token, but Entra requires it explicitly on every request — rejecting scopeless refresh requests with AADSTS90009: Application is requesting a token for itself.

Fix: introduce a /token proxy on your MCP server

Instead of pointing token_endpoint in your /.well-known/oauth-authorization-server directly at your identity provider, point it at a lightweight proxy on your own server that injects the missing scope before forwarding:

app.post("/token", express.urlencoded({ extended: false }), async (req, res) => {
  const body = { ...req.body };
  const timestamp = new Date().toISOString();

  if (body.grant_type === "refresh_token" && !body.scope) {
    // NOTE: Verify offline_access is granted in your identity provider's app registration,
    // otherwise the injected scope may be rejected if the user didn't originally consent to it.
    const defaultScope = "openid profile offline_access <your-custom-scope>";
    console.log(`[${timestamp}] TOKEN PROXY: refresh_token missing scope — injecting: ${defaultScope}`);
    body.scope = defaultScope;
  }

  try {
    // Forward safe headers only — exclude host-related headers and Authorization.
    // claude.ai sends a Bearer token on MCP requests which must not leak to the
    // identity provider's token endpoint and could cause unexpected rejections.
    const forwardedHeaders = { "Content-Type": "application/x-www-form-urlencoded" };
    for (const [key, value] of Object.entries(req.headers)) {
      if (!["host", "connection", "content-length", "content-type", "authorization"].includes(key)
          && typeof value === "string") {
        forwardedHeaders[key] = value;
      }
    }

    const upstreamRes = await fetch("<your-identity-provider-token-endpoint>", {
      method: "POST",
      headers: forwardedHeaders,
      body: new URLSearchParams(body).toString(),
    });

    const data = await upstreamRes.json();

    if (!upstreamRes.ok) {
      // Log only error code and description — avoid logging sensitive token data
      const sanitized = { error: data?.error, error_description: data?.error_description };
      console.error(`[${timestamp}] TOKEN PROXY: upstream error ${upstreamRes.status}:`, JSON.stringify(sanitized));
    } else {
      console.log(`[${timestamp}] TOKEN PROXY: success grant_type=${body.grant_type}`);
    }

    res.status(upstreamRes.status).json(data);
  } catch (err) {
    console.error(`[${timestamp}] TOKEN PROXY: fetch failed:`, err?.message);
    res.status(502).json({ error: "server_error", error_description: "Token proxy upstream error" });
  }
});

Then update your discovery document:

{
  "token_endpoint": "https://your-mcp-server.example.com/token"
}

Key implementation details:

• Register /token as a public route — no Bearer token auth on this endpoint since no token exists yet during token exchange
• Authorization header explicitly excluded from forwarding — claude.ai sends a Bearer token on MCP requests that must not leak to the identity provider
• Sanitized error logging — only error and error_description logged on failure, no trace/correlation IDs in plain text
• Scope injection only fires on refresh_token + missing scope — all other grant types (authorization_code etc.) forwarded unchanged
• After deploying, users need to disconnect and reconnect once to pick up the updated token_endpoint from the discovery document

Confirmed working — token auto-refresh verified via App Insights and identity provider sign-in logs over multiple ~1 hour refresh cycles with no manual reconnection required, across multiple users.

Revert token_endpoint back to your identity provider directly once this is fixed upstream.

---

@Philippstf 💡 — might be relevant for #237!

[MHooson]

Confirming this on a custom MCP server we operate (SEAM — a multi-tenant governance proxy on Cloud Run, built on the TypeScript SDK's OAuthServerProvider + mcpAuthRouter()). Symptoms exactly match this report:

• claude.ai integration UI shows "Connection has expired. You can reconnect to re-authenticate." 1-2 times per day for users who happen to be in active tool-call conversations as their access-token expiry passes.
• Users who are idle around the expiry boundary never see it — the proxy's next session resume rotates the token cleanly and they don't notice.
• The same server's Claude Code (direct, non-proxy) connections are unaffected — consistent with the v2.1.59 refresh-rotation fix only shipping to the direct path.
• Server-side logs show 401s on the next tool call after the access-token exp. The proxy's outbound bearer wasn't refreshed; the SSE leg apparently was reconnected (or kept alive) but the token never rotated.

Mitigation we shipped today: bumped our MCP JWT access-token TTL from 1h → 24h. Users now hit this ~once a day instead of every hour. Trade-off is a longer revocation window, which we're accepting because refresh-token rotation per OAuth 2.1 §6.1 still bounds the blast radius of any leaked access token. Not a real fix — just buys our users some breathing room until the proxy path catches up with the direct path.

Happy to share access-token issuance / verification code paths or example request traces if it'd help with repro.

[viniciusmichelutti]

Still happening. Having to extend the lifespan of the Access Token is not ideal

[timothedelion]

Adding server-side evidence, with a sharper diagnosis.

Setup: custom connector on claude.ai web → remote MCP server (FastMCP streamable-HTTP, stateless JSON mode) behind an OAuth proxy (DCR + authorization_code + PKCE). Initial connect completes the full flow and works.

From 7 days of server logs:

• Initial OAuth handshake succeeds exactly once: GET /.well-known/oauth-authorization-server → POST /register (201) → GET /.well-known/oauth-protected-resource/mcp → POST /token (200). Subsequent tool calls return 200/202.
• After that, background POST /mcp requests recur every ~15–25 min and return 401, interleaved with the occasional working session.
• Key detail: our token verifier accepts any non-empty bearer (it doesn't validate the token itself), so auth is rejected pre-dispatch only when the header is absent. A 401 here therefore means the request arrived with no Authorization header at all — not an expired/stale token being forwarded. The reconnect/keepalive probes simply carry no credential.
• Each 401 returns a correct WWW-Authenticate: Bearer error="invalid_token", resource_metadata="…", as_metadata="…". Claude does re-fetch both metadata docs in response — but then never proceeds to /authorize or /token. There is exactly one /token call in the whole window (at first connect).
• The access token is valid for 90 days and still works on demand, so this isn't expiry.

Representative log lines (redacted; hostnames/IPs/ports removed):

# Day 0 — connect: full OAuth flow, exactly once
08:55:53  GET  /.well-known/oauth-authorization-server      200
08:55:54  POST /oauth/register                              201
08:56:59  GET  /.well-known/oauth-protected-resource/mcp    200
08:57:00  POST /oauth/token                                 200   ← only /token call in 7 days

# Day 1 — works on demand (authenticated session: initialize / tools-list / resources-list)
06:56:44  POST /mcp                                         200
06:56:45  POST /mcp                                         202

# Day 1 — background probes: recurring 401s (no Authorization header)
07:11:29  POST /mcp                                         401
07:22:56  POST /mcp                                         401
11:25:34  POST /mcp                                         401

# Day 1 — after a 401: re-discovers metadata, then stops; never re-auths
11:52:08  GET  /.well-known/oauth-protected-resource/mcp    200
11:52:08  GET  /.well-known/oauth-authorization-server      200
          (no /authorize, no /token follows)

Net: claude.ai's background/reconnect path to POST /mcp omits the Authorization header, and the post-401 discovery is never followed by a token exchange — so the connector shows "disconnected" while the stored token is still valid. Re-clicking Connect restores it until the next background probe.