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. Clients use a refresh token to obtain replacements, so a working connection keeps working without you re-approving. If a token can no longer be refreshed or 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
Every member can manage their own OAuth agent sessions under Settings › Account. It lists that member's live tokens across the workspaces they can access. Owners and Admins can additionally use Connect › Active sessions to review and revoke organization-wide connections for the current workspace.
- Revoke your own token. Open Settings › Account and click Revoke on its row. The client loses access immediately.
- Administratively revoke one token. Owners and Admins can click Revoke on a row under Connect › Active sessions.
- Administratively revoke everything for a client. Owners and Admins can 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.
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" |
API access isn't enabled for the workspace | Ask the workspace owner or contact support |
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.