AI assistants (MCP)
Troubleshooting
What an error, a missing tool or a cut-off answer from a connected AI assistant means, and how to fix it.
Most problems come from the key: its roles, purposes, sensitive data level or status. Check the key under Settings → Access → API keys first, and the connection's status on the Connected AI apps tab.
| Symptom | Cause and fix |
|---|---|
| No MCP server address on the Connected AI apps tab | The MCP server is not set up for your instance. Ask your Optima operator. |
| The sign-in page says the key cannot be used | The key is wrong, disabled, or can reach more than one environment. Use a dedicated key for this environment. After five failed attempts in a minute the page refuses further tries for a minute. |
The assistant says it is disconnected or asks you to sign in again (401) | The connection was revoked, it went unused too long, or the key was disabled, deleted or rotated. Connect again, with a new key if needed. On the Connected AI apps tab the status shows which: Revoked, Expired or Key rejected. |
| A tool you expect is missing | The key's roles do not allow it, or it is one of the actions never available to assistants (see Tools). Role changes take effect within about a minute; start a new chat so the assistant loads the tool list again. |
A refusal mentioning a purpose or permission (403) | The key lacks the role or the purpose grant for that request. Grant the purpose to the key, or ask the assistant to use one the key already holds. |
| A refusal saying the origin is not allowed | A browser-based assistant your operator has not allowed. Ask your operator to allow it. |
Too many requests (429) | The assistant made too many requests in a minute. Wait a moment and try again, or ask for fewer, larger steps. |
| The assistant says some attributes were withheld | They are above the key's PII level. Raise the level only if the job needs that data. |
| An answer says rows were left out | The result was larger than the size limit. Ask for a smaller page, a narrower filter or a count instead of a list. |
draft_journey returns issues (422) | The journey draft broke a rule the console also checks. The issues name the steps; ask the assistant to fix them. |
| A revoked connection is back | It connected again with the same key. Disable, rotate or delete the key. |
| A developer tool does not appear on the Connected AI apps tab | Tools that send the key directly (Claude Code, Cursor) do not create a connection row. Control them through the key. |