MCP Errors 401 and 503: Token or Ingress?
MCP 401 means the token is invalid; 503 means ingress is unavailable for a Web connection. Test Local first, then Web, to find the failing layer.
When an MCP connection fails, 401 and 503 identify different causes. In AkiMCP 2.1, /mcp returns 401 when a request has a missing or wrong token; the OAuth endpoints of the Web flow return 503 while no ingress is attached. Reading the status correctly prevents network changes when authentication is the problem, and token changes when ingress is the missing layer.
MCP returns 401: check the token
401 Unauthorized means the request reached Gatekeeper but the token was rejected. Copy the token again from the panel, remove accidental whitespace, and confirm the connector uses the current value.
Do not start changing ingress before the 401 is resolved. This status proves the network path already reached authentication.
MCP returns 503: check ingress
503 Service Unavailable appears when a Web client calls discovery, /authorize, /register, or /token while no ingress is attached; it points at your setup, not at a random network fault. The local core keeps working normally on 127.0.0.1. First confirm the connector belongs to the Web group, then check the ingress and the public address. A newly attached ingress (through the panel, the --tunnel flag, or the PUBLIC_ORIGIN variable) takes effect only after a restart.
The shortest diagnostic sequence
- ◆Try the Local connector on the same machine to verify Gatekeeper and the token.
- ◆If it returns 401, fix the token first; do not touch ingress yet.
- ◆If Local works but Web returns 503, inspect ingress and the Web endpoint.
- ◆Check tools or shell permissions only after connection and authentication succeed.
This error split follows the 2.1 local-first architecture: Local is not blocked because ingress is absent, while Web reports the unavailable layer directly. Read what MCP local-first means to choose the correct connector group.