Skip to main content

Troubleshooting

Common failure modes and how to fix them. The MCP (Model Context Protocol) Services never throws out of a tool — every problem comes back as IsSuccess: false plus an ErrorMessage. Read the message first; the table below maps the typical messages to root causes.

Connection & registration​

claude mcp list shows the server but with a connection error​

The server URL is reachable but the MCP handshake failed.

  • Wrong path — the URL must end with /mcp (tenantless) or /{tenantId}/mcp. Just the host without a path returns 404.
  • Network reachability — for the production endpoints you may need to be on the corporate VPN. Verify with curl -sSI <url> — a 200/405 response is fine; a timeout means networking, not MCP.

mcp__octomesh__* tools don't appear after registering​

Claude Code only enumerates tools at session start.

  1. Confirm with claude mcp list that the server shows Connected.
  2. Restart your Claude Code session (/exit, then start a new one in the same project).
  3. The tool catalogue should now be visible — try asking the assistant to call list_available_tools.

Authentication​

Every tool call returns ErrorMessage: "Not authenticated"​

You haven't completed the Device Flow for the current MCP session, or your token expired and the refresh token is also gone.

  1. Ask the assistant: "Authenticate me to tenant <tenant>." — this calls authenticate.
  2. Open the returned verification URL, enter the user code, complete the browser login.
  3. Ask the assistant: "Check my authentication status." — this calls check_auth_status and stores the tokens.

Token state is per MCP session (keyed by the Mcp-Session-Id HTTP header). A new Claude Code session is a new MCP session — you authenticate once per session, not once per call.

check_auth_status keeps returning isAuthenticated: false​

The browser login hasn't completed yet, or completed against a different tenant than the authenticate call.

  • Make sure you finished the browser flow (some Identity Servers show a "success" page; some redirect silently). The user code is short-lived — typically 5–10 minutes.
  • If the code expired, call authenticate again to get a fresh one.

Tokens were valid a moment ago, now everything fails​

The session's access token expired and the refresh token is also gone (server restart, or more than the refresh-token lifetime since last activity).

Authenticate again. The session retains the per-MCP-session identifier, so re-registration with claude mcp is not needed.

Tenant resolution​

ErrorMessage: "No tenant could be resolved"​

The tool needed a tenant but neither path was supplied:

  • Add tenantId to the call — every tenant-scoped tool accepts it. Best practice.
  • Or register the legacy endpoint — /{tenantId}/mcp puts the tenant in the URL itself.

Tool ran but operated against the wrong tenant​

You probably registered the legacy /{tenantId}/mcp endpoint and then passed a different tenantId as a parameter. The parameter wins (priority 1), so the result is correct but unexpected if you assumed the URL would be authoritative.

Switch to registering the tenantless /mcp endpoint and pass tenantId explicitly per call.

Destructive operations​

ErrorMessage: "Refusing to delete '...' without confirm=true."​

This is intentional — destructive tools refuse to run unless you pass confirm: true. The AI assistant should ask you for explicit consent before adding the parameter. If you want to proceed, instruct the assistant accordingly:

Yes, go ahead — set confirm to true.

There is no global override. Each destructive call needs its own confirmation.

File transfers​

Upload returns 404 / 410​

The reservation expired. Reservations and uploads live for 30 minutes, then the background sweeper purges them.

Call prepare_file_upload again to get a fresh transferId and retry the PUT.

Upload returns 413 Payload Too Large​

The 5 GiB hard cap was exceeded. Split the payload, or use a different mechanism for the data (e.g. octo-cli for tenant dumps over 5 GiB, or direct backend access).

Download URL gives a Connection reset mid-transfer​

The reservation expired between the tool call and the download. Re-run the export/dump tool to get a fresh transferId.

import_ck_model returned success but get_available_models still doesn't list it​

get_available_models reads from a per-tenant cache that can be briefly stale after an import. The reliable source of truth is get_ck_library_status:

{ "tool": "get_ck_library_status", "parameters": { "tenantId": "..." } }

It reports the actually-loaded version and modelState. Wait a moment if the engine is still validating, then re-call.

Service-managed CK models​

import_ck_from_catalog returned success but the model isn't loaded​

Service-managed CK models — anything under System.*, e.g. System.Communication, System.StreamData, System.Reporting, System.UI, System.Ai, System.Bot, System.Identity, System.Notification — cannot be loaded with import_ck_from_catalog. The tool returns IsSuccess: true with "Enqueued 0 import job(s)" and silently does nothing. This is consistent (the model is owned by the corresponding backend service) but misleading.

Use the matching enable_<feature> tool instead:

ModelTool
System.Communication-*enable_communication
System.StreamData-*enable_stream_data
System.Reporting-*enable_reporting
System.UI-*(no MCP tool yet — install via Studio or octo-cli)

For user-managed CK models (Basic.*, Industry.*, custom tenant models), import_ck_from_catalog works as expected.

Aggregation & query tools​

ErrorMessage: "Aggregation requires at least one column"​

Pass at least one entry in the aggregations array. count does not need attributePath; everything else does.

ErrorMessage: "Aggregation alias '...' is not unique"​

Two columns in the same call produced the same alias. Either rename one explicitly via alias, or change the function/path so the default alias differs. Default aliases follow <function>_<sanitised-path> (e.g. avg_Power).

ErrorMessage: "groupBy paths must be non-empty / contain no duplicates"​

Check the groupByAttributePaths list — empty strings, nulls, and duplicates are all rejected up front, before the call reaches the engine.

Stream-data tool returns "Archive not found" or "Stream data not enabled"​

The four-stage cascade for stream-data resolution failed at one of these steps:

  1. Tenant not found
  2. Stream-data CK model not enabled in this tenant → run enable_stream_data
  3. Archive runtime store not initialised
  4. archiveRtId doesn't exist → verify with get_archive_storage_stats

The error message tells you which stage failed.

CK type / entity gotchas​

update_entity returns IsConflict: true​

Another writer changed the entity since your last read. The response carries the current Entity and CurrentRtVersion — rebase your change and call update_entity again with expected_version: <CurrentRtVersion>. See Tool reference → optimistic locking.

ErrorMessage: "Invalid CkTypeId" when constructing a type id​

CkTypeId is Name-VersionUint, not SemVer. "MyType-1" is valid; "MyType-1.0.0" throws because the version is parsed as uint.

ErrorMessage: "Invalid OctoObjectId" on rtId​

OctoObjectId is a 24-character hex string (MongoDB ObjectId). Letters outside [0-9a-fA-F] get rejected with this error. Real example shape: 507f1f77bcf86cd799439011.

Where to look next​

  • get_tool_details(name) — full tool description, parameter schema, examples
  • list_available_tools — what the server currently advertises (useful after a version upgrade)
  • /health, /health/ready, /health/live — server-side health probes