Troubleshooting
Start here, then follow the link to the page that covers your specific case. Most problems fall into four buckets: setup won't complete, users can't sign in, tools don't appear, or calls fail.
Start with the most common one
"Connected, but no tools appear" is by far the most frequent report, and it's almost never a fault. Check in this order:
| Check | Where |
|---|---|
| Connection status is Active | Connections → the connection |
| Tools are Published | Tool Catalog |
| A role the user holds has access to those tools | Assigning Tool Access |
| The user actually holds a role | Members & Access |
Workspace admins usually see every tool regardless of role access. So it can work perfectly for you while your whole team sees nothing. Always verify as a non-admin member.
Setup won't complete
| Message or symptom | Cause | Go to |
|---|---|---|
Verify the connection's domain before provisioning | Step 2 hasn't passed | Create a Connection |
| Domain verification never turns green | DNS propagation, or a doubled record name | Create a Connection |
Configure the JWKS URI and Issuer URI before provisioning | Token Exchange Step 3 incomplete | Token Exchange Config |
Configure the login/exchange/validate URLs and generate an HMAC key first | Tenant Delegated Step 3 incomplete | Tenant Delegated |
A checkName: message list | Endpoint certification failed | Tenant Delegated Troubleshooting |
| Provisioning succeeded but sign-in doesn't work | Token Exchange IdP registration is non-fatal — it can fail silently | Token Exchange Troubleshooting |
Users can't sign in
| Message | Meaning | Go to |
|---|---|---|
user not found — please log in to the Dashboard first | No member record yet. Expected on first use with Token Exchange | Inviting Members |
token has expired | Normal expiry — reconnect. Persistent means clock skew | — |
issuer not recognized | Token was issued for a different connection | Check the endpoint URL |
unable to resolve signing key | Usually a stale token, or an IdP token sent directly | Token Exchange Auth Flow |
identity provider unreachable | Transient — retry | — |
Session has been revoked or expired | Your app returned valid: false (Tenant Delegated) | Tenant Delegated Troubleshooting |
| Invitation email never arrived | Check spam, then Resend | Inviting Members |
An AI client won't connect
| Symptom | Cause |
|---|---|
| Client reports server unreachable | Connection isn't Active |
| Claude Desktop / ChatGPT / Cursor rejected | Expected on Token Exchange — those clients need interactive browser login, which that model disables. Use Identity Brokering, or integrate programmatically |
| Client asks for an API key | It's pointed at something other than the MCP Server URL |
| Wrong workspace's tools appear | Wrong endpoint — each connection has its own |
| Sign-in works, still disconnected | Stale cached credentials — remove and re-add the connector |
Tool calls fail
Authentication is working; the problem is downstream.
| Symptom | Likely cause |
|---|---|
| Calls return 4xx | The AI is constructing calls your API rejects — usually a vague tool description or an under-specified schema. Fix in Tool Studio |
| Calls return 5xx | Your API is erroring. Check its logs |
| Calls time out | Upstream latency. Check Metrics |
| Returns data but not what was wanted | A parameter is mapped wrong. Use Preview request in Tool Studio |
| AI picks the wrong tool | Description problem, not a platform problem. Rewrite it |
| AI asks for a parameter it should derive | The description doesn't say where the value comes from |
Tools or specs behave oddly
| Symptom | Cause |
|---|---|
| Nothing generated after uploading a spec | The spec failed to parse — check API Specs |
| Tool changes not reflected | Saving creates a version; you must Make active. See Tool Studio |
| Tool list looks stale in the client | Some clients cache for the session — reconnect |
| A tool vanished | Unpublished, or role access was removed |
Still stuck
Narrow it down before digging in:
- Does it affect everyone, or one person? One person → roles and membership. Everyone → publishing, access, or connection state.
- Did it ever work? Never → setup. Used to → something changed; check the Audit Log.
- Is it one tool or all of them? One → that tool's config. All → authentication or connection state.
- What does the error actually say? Most messages here name their own cause.
Per-model pages carry the detail: