> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enginy.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Security & Troubleshooting
> Use Enginy MCP safely and debug the most common authorization, scope, and client-compatibility issues.
## Security recommendations
Enginy MCP gives an MCP client the same data access as the approving Enginy user, within the approved scope set. Treat that client as a trusted operator, not as a passive viewer.
Recommended posture:
* connect only to the official hosted MCP URL: `https://openapi.enginy.ai/mcp`
* keep allowed redirect URIs tight, especially in production
* leave the allowed client-ID list empty only during initial setup or in lower-risk environments
* once you know the client IDs your team actually uses, pin them
* start from read-only scopes and add writes deliberately
* require human confirmation for write-heavy workflows so prompt injection or agent mistakes cannot silently mutate data
* revoke individual user connections when someone no longer needs MCP access
## Why human confirmation matters
Like other remote MCP systems, Enginy is powerful enough to read and mutate business data on behalf of the user who approved it.
That means you should assume an unsafe prompt, malicious retrieved content, or an over-eager agent could try to:
* exfiltrate sensitive records
* broaden its own operating scope by suggesting risky re-authorization
* mutate campaigns, contacts, inbox state, or webhooks without enough review
For workflows that can write data, keep a human confirmation step in the loop.
## Troubleshooting guide
| Symptom | What it usually means | What to check |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `redirect_uri is not allowed` | The callback URL is not on the workspace allowlist | Add the exact redirect URI, including port and path |
| `OAuth client_id is not allowed` | The workspace is pinning client IDs and this one is missing | Add the exact client ID or remove the allowlist temporarily |
| `Requested scopes are not allowed` | The client asked for more than the policy ceiling | Reduce requested scopes or expand the workspace policy |
| `Tool requires scopes: ...` | The token authenticated, but the chosen tool needs more permission | Re-authorize with the required scope set |
| `Token validation failed` | The connection, user, or policy is no longer valid | Check whether the user connection was revoked or the policy was disabled/tightened |
| `needs authentication` or `Cannot POST /token` | The client assumed a shorthand token path or is using the wrong base URL | Verify the MCP URL and let the client use discovery; Enginy supports compatibility aliases too |
| No tools appear or only a tiny subset appears | The approved scope set is narrow or the client cached stale auth state | Run `mcp_whoami`, inspect granted scopes, then reconnect if needed |
| A refresh suddenly stops working | The refresh token was rotated, revoked, expired, or invalidated by policy | Re-authorize the client and make sure it stores the newest refresh token after each refresh |
| Authorization succeeds but the client keeps looping back to "Connect" | The client re-runs OAuth/registration on each attempt instead of reusing its token; repeated disconnect/reconnect makes it worse | Remove and re-add the connector once, confirm with `mcp_whoami`, and stop re-clicking connect; try another client to isolate (see below) |
## Manual inspection points
If you need to debug a custom client:
* start from `https://openapi.enginy.ai/mcp`
* inspect OAuth authorization-server metadata instead of hardcoding endpoints
* confirm the token issuer and JWKS match the same Enginy environment
* verify the redirect URI and client ID values are the same ones Enginy saw during authorization
## Operational behavior that surprises clients
* Enginy's MCP transport is stateless. Do not rely on a sticky server-side session.
* Refresh tokens are rotating. Always replace the stored refresh token with the newest one.
* Reusing an already-rotated refresh token returns `invalid_grant`; if another refresh already succeeded, the active token chain is preserved.
* Tightening the workspace policy later can invalidate a previously working token set.
## The client keeps asking you to reconnect (authorization loop)
A frequent report looks like a permissions problem but almost never is: the client writes the tool call, you click **Connect**, the authorization page opens, you approve every scope, it confirms "connected and authorized" — but back in the client it still refuses to run the tool and shows **Connect** again, in a loop.
What is actually happening: the **MCP client** re-runs the full OAuth + dynamic client registration flow on each attempt instead of reusing the access token it just received. Every disconnect/reconnect or re-grant registers a brand-new client and opens a fresh connection, which keeps the loop alive. On the Enginy side each authorization completes correctly — `mcp_whoami` returns your user, workspace, granted scopes, and an active connection as soon as any single token is accepted.
This is a client-side connection issue, not an Enginy scope or permission rejection. A real scope rejection returns a specific message such as `Tool requires scopes: ...` or `Requested scopes are not allowed` (see the table above), not a silent reconnect loop.
To break the loop:
1. **Fully remove** the Enginy connector from the client — not just "disconnect", remove it entirely.
2. Re-add it **once** and complete a single authorization.
3. Before running a write tool, run a read first (ask the client to call `mcp_whoami`, or to list your campaigns) to confirm the session is live.
4. **Do not re-click connect repeatedly** or re-grant permissions in a loop — each cycle registers a new client and can confuse the client's cached auth state.
5. If it still loops, try a different client or surface (for example, Claude desktop vs. web) to isolate whether it is specific to one client build.
If a single clean authorization still cannot run any tool — and `mcp_whoami` does not return your identity afterwards — treat it as a bug and capture the exact client-side error text before reporting it.
Revisit the architecture, tool-generation model, and admin-versus-user control split.
See the discovery, transport, registration, and interface-specific setup details for client implementers.
Confirm whether your client is a direct fit, a config-based fit, or a bridge-only integration.
Separate known limitations from real bugs before you start debugging the wrong thing.