Most people never touch a session token — the hosted server handles it invisibly. But if you're building custom tooling or debugging an auth issue, it helps to know what's happening under the hood. This article explains the two-credential model.
Two credentials, two lifetimes
MTContext uses two things:
- Your terminal key (
MTMCP-…) — a durable credential that doesn't expire on its own; it only stops working when you revoke or rotate it. - A session token (a JWT) — short-lived, and what actually authorizes each request to the trading gateway.
Your client never sends the terminal key to the gateway directly for every call. Instead, the key is exchanged for a session token, and that token is what's used until it expires and a fresh one is fetched.
The automatic path (what you normally use)
When you connect through a standard MCP client — Claude Desktop, Cursor, or the hosted endpoint via mcp-remote — the hosted server performs the exchange and refreshes the session token transparently on your behalf, before it expires (by default within an hour). You set your terminal key once in the client config and never manage a token again unless the key itself is rotated or revoked.
The manual path (CI/CD and custom tooling)
If you're scripting against the gateway directly and mcp-remote doesn't fit, you can exchange the terminal key for a token yourself:
JWT=$(curl -s -X POST https://gateway.mtcontext.com/api/token \
-H "Authorization: Bearer MTMCP-YOUR-TERMINAL-KEY" | jq -r .token)
In this mode you are responsible for refreshing the token before it expires (default 24h in the direct-exchange flow). That's exactly the bookkeeping the mcp-remote/hosted path does for you, which is why it's the recommended default for everything except automation.
Rotating
You don't rotate a session token directly — you let it expire and a new one is issued. What you rotate is the terminal key it's minted from; see Rotating or revoking a terminal key. After a key is revoked, any session token already issued from it keeps working only until it expires and then fails to refresh.
Next steps
If a client is failing to authenticate, see Auth errors and expired tokens. For the security angle on both credentials, see Keeping your terminal key and JWT safe.