MCP 401 and 403 errors: isolate identity before touching the prompt.

Start with the distinction

401 Unauthorized usually means the resource did not accept the request as authenticated: the token may be absent, expired, malformed, issued by the wrong authority, or intended for a different audience. 403 Forbidden usually means the identity was recognized but lacks permission for that resource or action.

Do not rely on the label alone. Capture the final URL, status, authentication challenge headers, response body, and request identifier after redacting credentials.

1. Remove the model from the test

Make the smallest authorized discovery or tool request directly from the same deployed environment. If that request fails, tool descriptions and agent prompts cannot fix it. Compare a failing production request with a working local request using non-secret facts only:

• HTTP method and canonical URL
• Final hostname after redirects
• Token issuer, audience, scopes, and expiry
• Deployed client or service-account identity
• Response status and request ID

2. Inspect every redirect

A 301, 302, 307, or 308 can move the request to a different hostname or path. Clients and proxies may remove an Authorization header when the host changes. Test the canonical endpoint directly and inspect the redirect chain without printing the token.

3. Verify the token is for this resource

A validly signed token can still be wrong for the MCP resource. Check issuer, audience or resource indicator, scopes, expiry, and the client identity that obtained it. Confirm the deployed runtime is not silently using a local-development credential, stale cached token, or a token issued for another API.

4. Separate authentication from authorization

If a minimal request authenticates but a specific tool returns 403, compare the permission required by that tool with the granted role or scope. Test a read-only, low-risk action first. Avoid broadening permissions until the missing permission is proven.

5. Recheck deployment-only differences

Confirm secret presence without exposing values, callback URLs, runtime version, proxy behavior, region, clock skew, and service-account selection. A local success is not evidence that production received the same configuration.

6. Restore the agent last

Once a raw request succeeds from production, verify tool discovery, schema, selection, and result handling. Preserve the direct request as a smoke test so future auth regressions fail before the full agent run.