MCP Re-Auth: What ChatGPT Needs When Tokens Expire
Your token expires mid-session. ChatGPT tells the user to “please re-authenticate” in plain text instead of opening the OAuth flow. The user pastes the message into your support channel, and you explain that they need to reconnect. The same flow works in Claude Desktop.
Your token handling is fine. The signal format is the problem.
This is what we saw in March 2026 while building the MCP endpoint on our gateway. ChatGPT’s behavior can change, so test it against your own connector.
A bare 401 did not work
The obvious fix is to return an HTTP 401. It did nothing for ChatGPT. Neither did a JSON-RPC error code such as -32001. Both tell the client something went wrong. Neither tells it to start OAuth again.
What worked was a JSON-RPC success response with a tool result flagged as an error and a _meta field:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [{ "type": "text", "text": "Authentication required." }],
"isError": true,
"_meta": {
"mcp/www_authenticate": "Bearer resource_metadata=\"https://api.example.com/.well-known/oauth-protected-resource\""
}
}
}
The key is _meta["mcp/www_authenticate"]. It says the token is invalid and points to where to find out how to get a new one. ChatGPT fetches the resource_metadata URL, reads the authorization_servers list, and walks the OAuth discovery chain again. Without the field, ChatGPT shows the error text and stops. No popup.
Two layers of auth
An MCP gateway has two separate auth boundaries.
Gateway auth is between the MCP client and your gateway. The client holds an OAuth token that says who the user is. ChatGPT issued that flow, so ChatGPT can restart it when you send the _meta signal.
Integration auth is between your gateway and downstream APIs such as Jira, Salesforce, GitHub or Google. The user granted those tokens in a separate flow, usually through your dashboard. ChatGPT has no relationship with those providers and cannot refresh their tokens.
If a Jira token expires, ChatGPT cannot fix it. The right answer is a clear message telling the user to reconnect Jira in the dashboard. A re-auth signal would send them into the wrong flow.
| Layer | Who owns the token | Can the MCP client fix it? | Response |
|---|---|---|---|
| Gateway auth | The MCP client (ChatGPT) | Yes | _meta re-auth signal |
| Integration auth | The user, via the dashboard | No | isError with a reconnect message |
How our gateway sends it
When authentication fails for a reason a new login can fix (missing bearer token, invalid token, failed verification, missing subject claim), the gateway returns the _meta signal:
const reauthable = ["missing_bearer", "invalid_token", "auth_failed", "missing_sub"];
if (code && reauthable.includes(code)) {
res.json(mcpReauthResult(id, req, e?.message ?? "Authentication required."));
} else {
// Non-reauthable failures (bad API key, no tenant) stay as JSON-RPC errors
res.json(err(id, -32001, "Unauthorized", e?.message));
}
mcpReauthResult builds the resource_metadata URL from the request’s forwarded headers. That covers single-tenant setups, where the resource sits at the service root, and multi-tenant setups, where it is scoped to the tenant slug.
A bad API key or a missing tenant still gets a normal JSON-RPC error. No OAuth flow fixes a bad API key. The user needs a new one.
How it handles integration failures
For downstream APIs, the pattern is to refresh the token and retry once. If the retry fails too, throw a typed error. Simplified:
let resp = await doFetch();
if (resp.status === 401) {
try {
await withRefreshMutex(key, () => refreshOAuthToken(tenantId, uid, provider, config));
} catch {
throw new IntegrationAuthError(provider, 401);
}
resp = await doFetch();
if (resp.status === 401) throw new IntegrationAuthError(provider, 401);
}
withRefreshMutex makes concurrent refreshes share one request. If three tool calls hit a 401 at once, only one refresh goes to the provider.
The MCP handler catches IntegrationAuthError and returns a tool result with isError: true and no _meta:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [{
"type": "text",
"text": "Jira authentication failed (HTTP 401). Please reconnect Jira via the dashboard."
}],
"isError": true
}
}
With no _meta, ChatGPT shows the message as text, which is what you want. The user has to act in the dashboard, not in ChatGPT. Providers without refresh tokens (GitHub, Slack, Notion) skip the retry and fail on the first 401.
Not in the MCP spec
This _meta["mcp/www_authenticate"] field is not in the core MCP specification. We took it from ChatGPT’s behavior and a thread on OpenAI’s developer community. Other MCP clients may ignore it, so treat it as a ChatGPT-specific signal and check your own clients.
A gateway is the right place to handle it. Individual tool servers should not need to know how one client asks for a new login. The gateway already verifies tokens, so it can answer in whatever form the connected client understands. If the spec later standardizes this, you change it in one place.
Running coding agents? ACP records each tool call its hook sees and makes the dangerous shell commands (a force-push, destructive SQL, curl | sh) wait for you. One command, free up to 5 agents:
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
irm https://agenticcontrolplane.com/install.ps1 | iex