Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
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 response—not an MCP tool result. Check the WWW-Authenticate header for authorization details, then follow the server’s authorization flow and retry with a valid Bearer token.
What an MCP 401 tells you
The MCP authorization specification assigns HTTP 401 to requests that need authorization or use an invalid token. Invalid or expired access tokens should receive 401. The response’s WWW-Authenticate header is the key diagnostic: it can point to the server’s Protected Resource Metadata document and may state the scope required for the operation.
This explanation applies to HTTP-based MCP transports. Authorization is optional for MCP implementations overall, and the specification’s OAuth flow is for HTTP transports. STDIO implementations use a different credential approach; they should retrieve credentials from the environment rather than apply this HTTP challenge flow. See the MCP Authorization specification, version 2026-07-28.
How to recover from a 401
- Inspect the response. Confirm that it is HTTP 401 and check whether the request omitted a token or sent one that may be invalid or expired.
- Read
WWW-Authenticate. MCP clients must be able to parse this header and respond appropriately to a 401. The Bearer challenge may include aresource_metadataURL and ascopevalue. - Discover the authorization details. Fetch the Protected Resource Metadata document identified by the challenge, then use its authorization-server information. The broader flow includes authorization-server metadata discovery, identifying or registering the client, and completing the applicable authorization flow.
- Request the appropriate scope. If the initial challenge specifies
scope, use it. Otherwise, usescopes_supportedfrom Protected Resource Metadata if that field is defined; if it is not, omit the scope parameter. Request only the permissions needed for the operation. - Retry with the access token. Send the token in the HTTP header
Authorization: Bearer <access-token>. Include authorization on every HTTP request. Never put an access token in a URI query string. - Stop if authorization still fails. If a newly authorized or refreshed request continues to fail, report the authorization error instead of retrying indefinitely. The specification recommends limits on retries for scope upgrades.
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 values are illustrative; use the metadata URI and scope returned by the server you are connecting to.
401 vs. 403 vs. 400 in MCP
| HTTP status | MCP authorization meaning | What to check |
|---|---|---|
401 Unauthorized |
Authorization is required, or the token is invalid or expired. | Check the Bearer challenge and complete authorization or replace the rejected credential. |
403 Forbidden |
The token may be valid, but it lacks the permission or scope required. For runtime insufficient-scope errors, the server should return 403 and identify the needed scope. | Check whether the identity has access and whether the token includes the needed scope. |
400 Bad Request |
The authorization request is malformed. | Correct the request format rather than treating the response as a rejected token. |
These distinctions come from the MCP specification’s error-handling and insufficient-scope guidance. A 401 and a 403 are not interchangeable: the former points to missing or rejected authorization, while the latter indicates inadequate permission for the requested operation.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Token and transport details that prevent repeat failures
- Use a token for the right server. The MCP server validates that a token is valid for its own resource or audience. Do not send a token issued for a different MCP server.
- Keep the token in the header. Use the Bearer authorization header on each HTTP request, not a URL query parameter.
- Do not assume a particular login screen. The protocol describes discovery and authorization steps, but exact screens and provider-specific procedures are not guaranteed.
- Check the transport. An HTTP 401 challenge applies to HTTP-based MCP requests; STDIO uses a separate credential acquisition approach.
For a fuller explanation of the authorization flow, see the official Understanding Authorization in MCP documentation.
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.
