Auth
MCP endpoint returns 401 unauthorized
Fix 401 unauthorized responses from a private Astrail MCP endpoint by checking bearer tokens, server visibility, and client config.
Symptom
The MCP client can reach the endpoint but every initialize, tools/list, or tools/call request returns 401 unauthorized.
First check
Confirm the request sends Authorization: Bearer with an active Astrail API key for the same workspace as the server.
Quick fix
Create a fresh API key in settings, paste it into the MCP client config without quotes or extra spaces, and retry tools/list.
Confirm the endpoint is private
A public demo endpoint can answer without a bearer token. A private endpoint must receive a workspace API key on every JSON-RPC request. If initialize works locally but fails from Claude, Cursor, or an agent runtime, compare the exact URL and headers each client sends.
Check the Authorization header shape
Use one Authorization header with the value Bearer followed by the raw key. Do not send the key as X-API-Key, query parameters, Basic auth, or a JSON-RPC field. A copied newline at the end of the key is enough to make a valid key fail.
Regenerate stale keys
Keys can be deleted, rotated, or scoped to a different account. Generate a new key from the dashboard, update the client config, restart the client process, and retry tools/list before debugging the generated tools themselves.
Separate upstream auth from Astrail auth
Astrail API keys authorize access to the MCP endpoint. Provider credentials authorize the upstream API behind a tool. If the MCP endpoint accepts tools/list but a tool call says auth_required, fix provider credentials instead of rotating the Astrail key.
FAQ
Does 401 mean the generated API tool is broken?
Usually no. A 401 at the MCP boundary means the Astrail endpoint rejected the client request before a generated tool ran.
Should private endpoint keys be placed in the prompt?
No. Store the key in the MCP client or runtime secret manager so it is sent as an HTTP header, not model-visible text.