--- summary: Common symptoms with MCP clients connecting to ScaiGrid, and what they usually mean. title: Troubleshooting path: troubleshooting status: published --- 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: ```bash curl -X POST "$SCAIGRID_HOST/v1/modules//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](./reference/api). ## 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.