Troubleshooting connections
Most connection issues come down to a missing token, an expired one, or a stale grant. Here's how to check and fix each.
Test your connection
Every card on Connect › Configure agents has a read-only "Test your connection" line. It shows your own latest live token for that client family — for example, "Connected via Claude Desktop · 3 hours ago" — or "No connection yet" if you haven't authorized. It's scoped to you, so it reflects your session, not a teammate's. If it says you're not connected, re-run the install steps for your agent and approve the consent screen.
Token expiry
Tokens have finite lifetimes, and how you recover depends on how you connected:
- OAuth (plugins and generic MCP clients). Access tokens expire two hours after they're issued and refresh automatically using a longer-lived refresh token, so a working connection keeps working without you re-approving. If the refresh token itself lapses (it lasts 30 days), or the token is revoked, your client will prompt you through the consent screen again on its next call.
- API keys. API keys don't expire — there's no refresh step. They're a static secret, so treat them like any credential and revoke one from the API Keys page if it leaks.
A token_expired error from the API or MCP endpoint means an OAuth token lapsed; reconnect and your client will get a fresh one.
Revoke and reconnect
To cut off a connection or force a clean re-auth, use Connect › Active sessions. It lists every OAuth access token issued to people in your organization — by client, user, when it was issued, and when it expires.
- Revoke one token. Click Revoke on its row. The client loses access immediately.
- Revoke everything for a client. Use Revoke all tokens in the danger footer to cut every token for a registered client at once.
To reconnect after revoking, just use the agent again — its next call re-runs the OAuth consent and issues a new token. (Reviewing or revoking tokens on Active sessions is an Owner-level view of the org's connections; your own personal browser sign-ins live under Settings › Account instead.)
Common errors
| What you see | What it means | Fix |
|---|---|---|
401 / not connected |
No valid token was sent | Re-run the install steps and approve the consent |
token_expired |
An OAuth token lapsed | Use the agent again to refresh, or reconnect |
invalid_token |
The token was revoked, or its client was revoked | Reconnect from the agent to get a new token |
insufficient_scope |
The token lacks the scope a tool needs | Reconnect and approve the required scopes; check your role |
403 "forbidden" |
The workspace plan doesn't include API access | Upgrade the plan on the billing screen |
Still stuck?
The MCP server reference documents the endpoint, scopes, and discovery documents in full, and the API overview covers the shared error format and rate limits.