For an HTTP-based Model Context Protocol (MCP) client, 401 Unauthorized means the server requires authorization or rejected the supplied access token. It is an HTTP authorization challenge—not an MCP tool result. Check the response’s WWW-Authenticate header for authorization metadata and any required scope, complete the applicable authorization flow, then retry with a Bearer token.
What a 401 means in MCP
The MCP authorization specification assigns HTTP 401 to requests that need authorization or carry an invalid token. Invalid or expired access tokens should receive this response. The client should treat the response as a signal to inspect the authorization challenge, not as a successful MCP response or a result returned by a tool.
As an Amazon Associate I earn from qualifying purchases.
This guidance applies to HTTP-based MCP transports. MCP authorization is optional overall, and the specification’s OAuth flow is for HTTP transports; for STDIO, it directs implementations to obtain credentials from the environment instead. See the MCP authorization specification, version 2026-07-28.
What to do when an MCP server returns 401
- Read the HTTP response. Confirm that the status is 401 and inspect the response headers before retrying.
- Parse
WWW-Authenticate. MCP clients must be able to parse this header and respond appropriately to 401 responses. A Bearer challenge may include aresource_metadataURI pointing to the server’s Protected Resource Metadata document, and may specify ascopeneeded for the operation. - Discover the authorization details. Fetch the indicated Protected Resource Metadata document and use its authorization-server information. The applicable flow then includes discovering authorization-server metadata, identifying or registering the client as needed, and completing authorization. The exact screens and provider-specific steps are not guaranteed by the protocol.
- Request only the appropriate scope. If the 401 challenge supplies a
scope, use it. If it does not, the specification directs the client to usescopes_supportedfrom Protected Resource Metadata when that field is defined; otherwise, omit the scope parameter. - Retry with the access token. Send the token in the HTTP
Authorization: Bearer <access-token>header. Include authorization on every HTTP request, and never put an access token in a URL query string. - Handle another failure without looping. If authorization or a refreshed token still fails, surface the error. The specification recommends limiting retries for scope upgrades rather than retrying indefinitely.
A challenge can look like this: WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource", scope="files:read". The example illustrates the header’s possible fields; the actual metadata URI and scope depend on the server.
How 401 differs from 403 and 400
| HTTP status | MCP authorization meaning | What it tells the client |
|---|---|---|
| 401 Unauthorized | Authorization is required, or the token is invalid or expired. | Authorize or correct the credential, using the challenge to guide the next step. |
| 403 Forbidden | The token has invalid scopes or the identity lacks sufficient permission. For runtime insufficient-scope errors, the server should return 403 and identify the needed scope. | The request may be authenticated, but the current identity or token cannot perform this operation. |
| 400 Bad Request | The authorization request is malformed. | Correct the request format rather than treating the response as a token challenge. |
These meanings come from the specification’s error-handling guidance. A 401 and a 403 are not interchangeable: the former points to authorization being absent or rejected, while the latter points to insufficient permission or scope.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Token and transport details that prevent common mistakes
- Use a token meant for this server. The server validates that the token is valid for its own resource or audience. Do not send a token issued for a different MCP server.
- Keep the token out of the URL. Send it only in the Bearer authorization header, not as a query parameter.
- Do not apply the HTTP flow to STDIO. The authorization specification’s HTTP challenge and OAuth sequence does not describe STDIO credential handling; it calls for credentials to be retrieved from the environment.
For the full protocol sequence and requirements, consult the versioned MCP authorization specification and the project’s authorization tutorial.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
