Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 <API key> 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

Local MCP (stdio): startup checks

1

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.

uvx krutrim-mcp-server --help
2

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.

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.

3

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.

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).

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

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

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

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

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

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

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

Last updated

Was this helpful?