Auth errors and expired tokens
Authentication errors almost always come down to two numbers: 401 and 403. They mean different things, and telling them
apart is most of the fix. This article covers both, plus the "it worked an hour ago and now it doesn't" case.
401 Unauthorized — the key isn't accepted
A 401 means the credential itself was rejected. Check, in order:
- The key starts with MTMCP- and has no trailing spaces (a copy-paste space is the single most common cause).
- Your client sends it as Authorization: Bearer MTMCP-YOUR-TERMINAL-KEY, exactly.
- The key hasn't been revoked or rotated. If you rotated recently, update the client to the new key.
- The key has been bound — a brand-new key must connect a terminal once before it authenticates anywhere. See
Activating your license key.
403 Forbidden — the key is fine, the tool isn't allowed
A 403 means you authenticated successfully but the key lacks the capability for that specific tool. This is a tier gate,
not a key problem — for example, trying to place a trade on the free tier, or calling an analytics tool below the Team
tier. The fix is a plan change, not a key change; see Choosing a plan and subscribing.
"It worked, then suddenly stopped"
If a session ran fine and then began failing, the usual cause is a session token that couldn't refresh. Session tokens
(JWTs) are short-lived and normally refreshed automatically. Refresh fails — and you start seeing 401s — when:
- the underlying terminal key was revoked or rotated mid-session, or
- you're managing the token manually and let it expire without minting a new one.
Restarting the client forces a fresh exchange from your terminal key. If it still fails, the key itself is the problem —
rotate it and retry. See Session tokens: getting and rotating your JWT.
Other auth-adjacent errors
- Terminal mismatch — the key is valid but bound to a different terminal than the request expects. Confirm the online
terminal is the one your key is bound to.
- Works in the dashboard but not the client — usually a stale client config or the wrong profile file loaded. Restart
the client to force a config reload.
Quick checklist
1. Key starts with MTMCP-, no trailing space.
2. Sent as a Bearer token.
3. Not revoked; bound at least once.
4. Restart the client to force a token refresh.
5. Still failing? Rotate the key and test with a read-only prompt.
Next steps
If tools authenticate but report no terminal, that's a different problem — see "No terminal connected" in your AI
client.
Manage keys at mtcontext.com/dashboard.