Troubleshooting

A short list of things that go wrong when wiring an MCP client to ScaiGrid, and how to unstick them. If none of these match, grab the request id from the response and grep the ScaiGrid logs.

Client connects but list_tools returns nothing#

Your token authenticated, but the filter dropped every tool. Causes, in order of likelihood:

• No modules enabled for your tenant. Tools with a module_id are filtered out when their module is disabled. Check GET /v1/modules and confirm at least scaimcp and the modules you care about are enabled.
• Token holds no useful permissions. A token issued for a brand-new user with no roles holds none. Confirm with me_get (the one tool open to any authenticated user) — if even that fails, your auth is broken; if it succeeds, your token works but has no privileges.
• Wrong tenant. The token authenticates a specific tenant. If the modules and roles you set up are on a different tenant, you see an empty catalog.

401 on connect#

The token didn't authenticate. Check, in order:

• It's prefixed with Bearer in the header.
• It's not expired (JWTs expire; sgk_ keys can be revoked).
• The host matches the deployment that minted it. Tokens from the managed scaigrid.scailabs.ai deployment don't work on on-prem deployments and vice versa.

403 on a specific tool#

The token authenticated but lacks the tool's required_permission. Either:

• Give the calling identity the permission (custom role or higher built-in role).
• Use a different identity.
• If you can't grant the permission, find an alternative tool — most workflows can be assembled from tools at lower permission tiers (models:use rather than admin:access).

Tool exists in the REST /v1/modules/scaimcp/tools list but not via MCP list_tools#

The REST endpoint returns the full catalog; the MCP method applies the permission filter. The difference is exactly the tools your token can't call. Either your token's identity needs more permission, or the tool's module isn't enabled for your tenant.

Tool call returns MODULE_NOT_ENABLED#

The tool's module is not enabled for your tenant. Enable it via the admin UI or:

1
2
3

curl -X POST "$SCAIGRID_HOST/v1/modules/<module_id>/enable" \
  -H "Authorization: Bearer $SCAIGRID_API_KEY" \
  -d '{"scope": "tenant", "tenant_id": "ten_..."}'

Calling MCP again immediately after enable should show the module's tools.

remote.* tools missing#

You registered a cloud MCP server through ScaiLink but its tools aren't appearing. Check:

• Your token has scailink:remote.use. Without it, no remote tools appear regardless of registration.
• The registration is approved (some flows go through an admin approval step).
• The cloud server is healthy. ScaiLink's health cron pings registered servers; check GET /v1/modules/scailink/registrations/{id} for status.
• The slug is what you expect — names use remote.{user_id|tenant}.{slug}.{tool}. Mistyped slugs lead to missing tools.

remote.* tool call fails with a non-ScaiGrid error code#

The upstream MCP server returned an error or the outbound transport failed. The code field is the upstream's error class name, the message is what they sent. Treat as an opaque downstream failure — ScaiMCP doesn't translate upstream semantics.

Connection drops mid-conversation#

Streamable HTTP keeps the connection alive but is not immune to network blips, proxy timeouts, or load-balancer 5-minute caps.

• Reconnect on disconnect; the transport is stateless so a fresh connect costs nothing.
• If you sit behind a corporate proxy with short idle timeouts, shorten your client's keepalive accordingly.
• Long-running tool calls (e.g., image generation) hold the connection open for the duration. If your client times out at 30s, image-generation responses get dropped — raise the per-call timeout.

Tool returns unexpected JSON shape#

Two common causes:

• You're calling a remote.* tool — the schema and result shape come from the upstream server, not from ScaiGrid. Re-inspect the tool's inputSchema from list_tools.
• ScaiGrid changed the underlying response. We try to keep these stable but the source of truth is the REST equivalent; check the API reference.

Claude Desktop entry stays grey#

Claude Desktop tried to connect and failed. Expand the entry in the UI to see the error message. Common causes:

• Missing "transport": "streamable-http" — Claude tried stdio.
• Typo in the URL (must end with /mcp).
• Token rejected (see "401 on connect" above).
• Outbound HTTPS blocked by firewall on the user's machine.

High latency on every call#

ScaiMCP itself is thin — latency comes from the underlying service. For inference_chat that's the model backend; for admin tools it's MariaDB. Measure the equivalent REST call to compare. If MCP is consistently slower than REST, file a bug; otherwise tune the backend.

Audit log doesn't show MCP calls#

There is no MCP-specific audit facet. The call shows up under the underlying service action — e.g., inference.chat for inference_chat. Filter by actor_user_id (the identity making the MCP call) and action (the service action). If you don't see anything, the call probably failed before reaching the service — check for TOOL_NOT_FOUND or PERMISSION_DENIED errors at the client.