Troubleshooting

A grouped reference for the errors and issues you'll most often hit with Devici MCP.

Connection issues

"MCP server unreachable" or "Could not connect"

Your AI client can't reach https://mcp.devici.com/mcp.

Likely cause	Fix
Wrong URL in client config	Verify the URL is `https://mcp.devici.com/mcp` exactly. The path is part of the URL.
Network policy blocks the host	Ask your network team to allow `mcp.devici.com` on outbound HTTPS.
Corporate proxy intercepts the connection	Configure your AI client to use the proxy (most accept `HTTPS_PROXY`). Confirm the proxy passes the `X-Devici-Client-Id` and `X-Devici-Client-Secret` headers through unchanged.
TLS inspection breaks the cert chain	Add Devici's CA to your client's trust store, or allowlist the host in the inspection appliance.

Empty tool list in the client

Connection established but no tools appear.

Likely cause	Fix
Headers weren't applied to the request	Re-check the `X-Devici-Client-Id` and `X-Devici-Client-Secret` header config in your client. Many clients have a "Test connection" button that confirms the credentials reached the server. If your client doesn't support custom headers, switch to the `Authorization: Basic` form — see Authentication → Encoding the Basic auth header.
Client doesn't support Streamable HTTP	Devici MCP is Streamable HTTP only. Switch to a client that supports remote MCP natively.
Session never opened	Reload your AI client. Some clients only list tools after a successful first handshake.

Authentication errors

`401 unauthorized`

The credentials were rejected.

Likely cause	Fix
Client ID or secret is wrong	Re-copy both values from Devici and paste them back into the client config.
Credentials were rotated or revoked	Reissue them in Devici and update the client config.
Whitespace or partial paste	Re-copy carefully, especially the secret. Editor auto-formatting can drop trailing characters.
Header name typo (e.g., `X-Devici-ClientId` instead of `X-Devici-Client-Id`)	Use the exact header names: `X-Devici-Client-Id` and `X-Devici-Client-Secret`.

`403` on a tool call

The credentials authenticated, but the API rejected the action. There are three distinct causes — the error message tells you which.

Error message	Likely cause	Fix
`Insufficient scope: required <resource>:<permission>`	The token's scopes don't include the resource:permission the tool needs. Each API token has its own scope set, configured at creation.	Reissue the token with the required scope, or have the agent call a tool that fits the current scopes.
`IP address not allowed`	The token has an IP allowlist, but MCP traffic reaches Devici from the MCP server's egress IP, not yours.	Remove the IP allowlist on this token, or use a separate no-allowlist token for MCP. See Authentication → Generate a token.
Other `403` from `devici_api_request` (raw API tool)	The agent called a gateway endpoint that isn't on the MCP server's allowlist.	The MCP server only proxies a curated endpoint list. Use the dedicated MCP tools instead, or ask engineering before assuming the endpoint can be added.

Tool-specific errors

"Empty canvas" after import

The OTM imported successfully, but the Devici canvas is blank.

Cause	Fix
Components used generic OTM types (`process`, `datastore`)	Switch to Devici types: `processNode`, `externalEntityNode`, `datastoreNode`, `trustBoundaryNode`, `stickerNode`.
Trust boundaries placed in top-level `trustZones`	Move them to `components` with `type: "trustBoundaryNode"` and self-referencing `parent.trustZone`.
Components missing `representations[].position` and `size`	Add them. Devici uses these to render.
Components missing `metaData.label`	Add `label` to every component's `metaData`.

Dataflows render without arrowheads

Cause	Fix
`markerEnd.type` is `"end"`	Change to `"arrowclosed"`.

"Cannot find component" on import

Cause	Fix
Dataflow references `target` instead of `destination`	Rename the field. Devici parses `destination`.

Two flows between the same components overlap

Cause	Fix
Both edges use the same source / target handles	Add `points` waypoints to route them differently. Don't use `sourceBottom` / `targetBottom` for overlapping edges.

`codex_browse` returns paginated results that don't match expected counts

Cause	Fix
`page` was used as a page index (`0, 1, 2, …`)	Use offset semantics: `page=0, 100, 200, …` for a `limit` of 100.

"Title too long" on create

Cause	Fix
Project, canvas, component, trust boundary, sticky note, or dataflow name exceeds 64 characters	Shorten the name. Codex-sourced threats and mitigations are exempt from this cap; their titles come from the codex.

Validation surprises

threat_model_validate reports findings — some are real misses you can fix, others are codex coverage gaps to surface rather than paper over.

Reported issue	What it means	Recommended action
Components without threats	The component was missed in the codex pass — no attributes were assigned, so the codex didn't produce any threats for it. A real miss.	Re-run an attribute pass on that component. See Playbooks.
Threats without mitigations	The codex had no default mitigation linked to that threat — a codex coverage gap, not a model defect	If your team has a real control that addresses it, attach it via `codex_assign_to_threat` (built-in, custom-codex, or inline custom). Otherwise, surface the gap — don't pad with vaguely-related codex mitigations.
Orphaned threat or mitigation	A threat or mitigation exists but its referenced component or threat doesn't	Either re-link or remove via `threat_model_update`.
Empty canvas	Model has no canvas or an empty one	Re-import via `threat_model_import_otm` with a populated OTM.

Performance and timeouts

Tool calls hang or time out

Likely cause	Fix
Very large OTM payload via `otm_content`	The MCP server is remote, so there's no `otm_file_path` alternative — the OTM must be passed inline. Compact the JSON (no indentation), drop optional verbose descriptions, and resend. If it's still too large, split the model into smaller imports (one canvas at a time) and stitch them in the UI.
Bulk codex op tried to apply more than 20 items in one call	Split into multiple calls. Each `codex_assign_bulk` op array is capped at 20 items by the API.
Long-running validation on a model with hundreds of components	Expected. `threat_model_validate` may take several seconds on large models.

What to include when filing an issue

When something doesn't fit a pattern above and you contact support, include:

The tool name you called.
The error message and HTTP status code.
An approximate timestamp (UTC if possible).
The client ID that was used. The secret should never leave your secret manager.
Your AI client and version (Cursor 2.x, Claude Desktop, etc.).
Any arguments to the tool that aren't sensitive. A minimum reproduction is most useful.

That's enough for support to locate the audit entry and trace the request through the platform.