MCP Errors 401 and 503: Token or Ingress?
MCP 401 means the token is invalid, while 503 means ingress is unavailable for a Web connection. Test Local first and Web second to identify the failing layer.
When an MCP connection fails, 401 and 503 identify different causes. In AkiMCP 2.1, 401 explicitly means an invalid token; 503 means a Web connection needs ingress but ingress is unavailable. Reading the status correctly prevents network changes when credentials are wrong, or 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 in the Web flow means the required ingress is unavailable. The local core may still work on 127.0.0.1; first confirm the connector belongs to the Web group, then check ingress status and the public address.
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.