> For the complete documentation index, see [llms.txt](https://docs.cloud.olakrutrim.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cloud.olakrutrim.com/mcp/troubleshooting.md). # Troubleshooting Diagnose hosted connection errors, API-key access, and local stdio setup. Start with the section for your connection: Hosted MCP over HTTPS, or the local stdio package. Readiness, tool discovery, and Cloud authorization are separate checks. ## Hosted MCP: connection and API-key checks * Use `https://mcp.olakrutrim.com/mcp` exactly, including HTTPS and the `/mcp` path. * Use Streamable HTTP and exactly one `Authorization: Bearer ` header. Do not send JWT access tokens, refresh tokens, or `X-Krutrim-Refresh-Token`. * Make sure the client receives the raw key through its launch environment or secret input. A desktop app may not inherit your terminal environment. Update saved inputs and restart after key rotation. * Check the client’s MCP status, network access, and organization policy for the hosted endpoint. Do not combine hosted URL settings with a local command. * Call `krutrim_ping` for readiness and read-only mode, then `list_vpcs` in the intended region for a read-only Cloud check. A successful ping does not prove Cloud permissions. | Symptom | What to check | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 401 Unauthorized | Missing, malformed, or revoked API key; a legacy JWT/refresh credential; or duplicate Authorization headers. Send one Bearer header with a valid API key. The server does not refresh credentials. | | 403 Forbidden | The key owner lacks permission for the operation or region. Ask your IAM administrator to review the policy. | | 404 Record not found | Verify the resource KRN with the corresponding list or describe tool for your account and region. | | 503 Service Unavailable | IAM validation may be unavailable. Retry; contact Krutrim Cloud support if the error persists. | | Create timed out | The gateway or client may time out before creation completes. Check with search/list/describe tools for the exact resource before retrying. | Configuration and verification: [Hosted MCP](/mcp/hosted-mcp.md) ## Local MCP (stdio): startup checks {% stepper %} {% step %} ### Check the executable and configuration * Confirm that `uvx` is installed and visible to the application, not just an unrelated terminal session. Desktop apps may use a different executable path. * Use the configuration path and schema from your client guide. Merge entries carefully, validate JSON / TOML / YAML, save the file, and restart the client. * If your organization manages MCP policy, ask your administrator to allow the exact local `uvx krutrim-mcp-server` command. ```bash uvx krutrim-mcp-server --help ``` {% endstep %} {% step %} ### Check the local package and tool catalog Configure `KRUTRIM_API_KEY` privately in the terminal environment before running these checks. A key stored in a client configuration is not automatically exported to your terminal. ```bash uvx krutrim-mcp-server --doctor uvx krutrim-mcp-server --list-tools ``` > `--doctor` checks local configuration, not Cloud authentication. `--list-tools` shows the installed tool catalog, not proof that your client has loaded the tools or that Cloud access works. > {% endstep %} {% step %} ### Verify Cloud access separately In your connected client, request a read-only operation: ``` List my VPCs in In-Bangalore-1. ``` Review the `list_vpcs` call and target region. A successful Cloud response verifies the key and permissions for that request. Do not create or delete resources just to test a connection. {% endstep %} {% endstepper %} ## Local MCP: API key rejected * Check that `KRUTRIM_API_KEY` contains the current raw API key, with no `Bearer` prefix or surrounding spaces. Do not use a Console access token. * Confirm that the key is valid and that the account has the required permissions for the selected region and resource. Use the intended region, such as `In-Bangalore-1` or `In-Hyderabad-1`. * After replacing a key, update each private client configuration or launch environment and restart the client. For VS Code, update the saved API-key input and restart the MCP server. Migrating from access and refresh tokens? See [Local MCP (stdio)](/mcp/local-mcp-stdio.md). ## Local MCP: tools missing or server unavailable If local package checks pass but your client has no tools, inspect the client’s MCP status and configuration scope. ### Claude Desktop * Check the standard local Claude Desktop configuration file and its `mcpServers` entry. Confirm that `uvx` is available to Claude Desktop. * Quit and reopen Claude Desktop after saving changes. The local stdio configuration is separate from packaged desktop extensions. Configuration and platform paths: [Connect Claude Desktop](/mcp/connect-claude-desktop.md) ### Codex * Verify the `[mcp_servers.krutrim-cloud]` TOML section and its API-key environment entry. * Use `codex mcp list` and `/mcp` in the CLI to inspect the server. Start a new session after configuration changes. Configuration guide: [Connect Codex](/mcp/connect-codex.md) ### Cursor * Check whether the entry is in `.cursor/mcp.json` or `~/.cursor/mcp.json`, and that it applies to the current workspace. * Restart Cursor, then inspect Customize → MCPs. Confirm that the executable is available and any enterprise MCP policy allows the server. Scope and configuration guide: [Connect Cursor](/mcp/connect-cursor.md) ### VS Code * Run `MCP: List Servers` to inspect server status and output. Verify the `uvx` command and the `krutrim-api-key` input. * Make sure the configuration uses `servers` and the masked input reference. Start the server and review its trust request. Masked-input configuration: [Connect VS Code](/mcp/connect-vs-code.md) ### Hermes Agent * Check the top-level `mcp_servers` mapping in `~/.hermes/config.yaml` and its explicit `env` API-key value. * A server with `enabled: false` is skipped. Check `tools.include` and `tools.exclude` if only some tools are missing; an include allowlist takes precedence. * Restart Hermes or run `/reload-mcp` to reload configuration and tools. Look for names prefixed with `mcp_krutrim_cloud_`. Configuration guide: [Connect Hermes](/mcp/connect-hermes.md) ### OpenCode * Run `opencode mcp list`. Check `mcp`, `type: "local"`, the `command` array, `environment`, and `enabled: true`. * Confirm `KRUTRIM_API_KEY` is set in the environment that launches OpenCode. An unset `{env:KRUTRIM_API_KEY}` resolves to an empty string. Check for configuration overrides. * If logs show a local discovery timeout, the server’s `timeout` setting is in milliseconds (default 5000). Increase it only as needed for startup, then retry. Do not use remote OAuth authentication commands for this local server. Configuration guide: [Connect OpenCode](/mcp/connect-opencode.md) ## Cloud operations fail or time out * List resources first and use exact returned identifiers in the intended region. Verify permissions before requesting a change. * Hosted MCP: inspect read-only mode with `krutrim_ping`; provide explicit confirmation parameters where required. A client environment variable cannot change the hosted deployment’s mode. * Local stdio: mutations require `confirm=true`; floating-IP allocation also requires `allow_public_ip=true`. `KRUTRIM_MCP_READ_ONLY=true` in the server environment intentionally blocks mutations. Do not disable safety controls merely to test connectivity. * After a create timeout, check whether the resource already exists before retrying. A timeout does not prove that creation failed. ## Before sharing a support report Include the connection type (hosted or local), client, operating system, configuration scope, server or package version, tool name, region, and sanitized error. Note whether the failure occurs during connection, readiness, tool discovery, or a Cloud request. Redact API keys, Console tokens, secret-bearing configuration, and sensitive resource details. Choose a connection path: [MCP Overview](/mcp/overview.md)