Skip to main content

Troubleshooting

Start with these checks:

  1. Confirm the client uses https://api.cloudsek.com/mcp.
  2. Confirm both the Authorization and X-CloudSEK-Org-Id headers are present.
  3. Ask What CloudSEK tools do you have available?
  4. Test a GTI query, such as Check whether 1.2.3.4 is malicious.
  5. Test an account query, such as Show my latest alerts.

If GTI works but account data does not, check the Alerts API configuration and Org ID. If no tools appear, check the client configuration and connection.

Connected, but alert tools return no data​

This usually means the Alerts API configuration has no records:

  • A new configuration starts empty. It receives only alerts created or routed to it after setup.
  • Open the configuration in the CloudSEK Platform and turn on Default if it should receive all new alerts and incidents.
  • If the configuration was disabled, alerts created while it was disabled are not added later.
  • Confirm X-CloudSEK-Org-Id matches the organization that owns the Alerts API token.

GTI results can still work because GTI uses a separate data source.

Bearer token is missing or 401 Unauthorized​

The Authorization header is missing, malformed, expired, or revoked. Check:

  • The value is Authorization: Bearer YOUR_TOKEN, with one space after Bearer and no quotes or trailing spaces in the token.

  • The environment variable exists in the process that launched the client. On macOS or Linux, check without printing the secret:

    test -n "$CLOUDSEK_BEARER_TOKEN" && echo set || echo missing

  • Claude Desktop was fully quit and reopened after its config changed.

  • The token remains active under CloudSEK Platform → Integrations → Alerts API.

403 Forbidden or organization access error​

  • Confirm the Org ID comes from the same CloudSEK organization as the token.
  • Check the X-CloudSEK-Org-Id spelling and capitalization.
  • Ask your CloudSEK administrator whether the token can access the requested product or operation.

Tools do not appear in Claude Desktop​

  • Confirm the file path matches your operating system. See Claude Desktop setup.
  • Validate the file as JSON using your editor's JSON diagnostics. Do not paste a config containing a token into an online validator.
  • Run node --version and npx --version. Install Node.js 20 or newer if either command is missing.
  • Fully quit Claude Desktop. Closing its window is not enough.
  • Open Help → Show Logs and look for mcp-remote, JSON parsing, or command errors.
  • On Windows, use the environment block shown in the Claude Desktop guide if argument strings containing spaces fail.

To check network reachability, run:

curl --head https://api.cloudsek.com/mcp

Any HTTP response confirms DNS and TLS connectivity. A non-success status can be normal because this check does not send MCP authentication or a protocol request.

Claude Code reports cloudsek not found or a connection error​

  • Run claude mcp list.
  • If cloudsek has an error, run claude mcp remove cloudsek, then add it again.
  • If you used --scope project, run Claude Code from that project.
  • Type /mcp inside a Claude Code session for server and tool errors.
  • If you passed a token on the command line, check that shell quoting did not truncate it. Rotate the token if it was stored in shell history against your policy.

Gemini CLI does not load tools​

  • Validate settings.json as JSON.
  • Use url with "type": "http". Do not use the deprecated httpUrl key.
  • Start Gemini CLI from a shell where the credential variables are exported.
  • Exit the current Gemini CLI process and start a new one after changing the environment or config file.

Codex CLI does not connect​

  • Confirm CLOUDSEK_BEARER_TOKEN and CLOUDSEK_ORG_ID are exported in the current shell.
  • Validate config.toml as TOML.
  • Configure the HTTP server in config.toml. The codex mcp add command only supports STDIO servers.
  • Type /mcp in a Codex session to inspect server status.
  • Raise startup_timeout_sec to 30 or 60 if startup times out.

Kiro does not connect​

  • Save the MCP config and wait a few seconds. Kiro reloads it without a restart.
  • Confirm the workspace file is .kiro/settings/mcp.json or the user file is ~/.kiro/settings/mcp.json.
  • Open the command palette, search for MCP, and open the config from Kiro to confirm you edited the active file.
  • Environment variables must exist before Kiro starts. Restart Kiro after changing your shell environment.
  • Open the MCP server view to inspect connection status and reconnect the server.

IOC lookup tool not found​

Use ioc_lookup. Older prompts may refer to get_ioc_intel, which has been replaced. No extra GTI credential is required.

GTI tools are missing or return errors​

  • Confirm you use the hosted https://api.cloudsek.com/mcp endpoint.
  • If tools appear but calls fail, wait one minute and retry in case the GTI service is temporarily unavailable.
  • Self-hosted deployments require the server administrator to configure GTI_MCP_URL.
  • Contact the CloudSEK integrations team if the issue continues.

Read tools work, but updates fail​

Check the request before retrying:

  • Use a token issued from 30 July 2026 or later. Earlier tokens are read-only on write routes; rotate under Integrations → Alerts API → Rotate Token.
  • Use an incident display ID such as XVA-1234, not an internal UUID.
  • Use the event record identifier returned by CloudSEK tools for event updates.
  • Use exact status values and casing. ClosedResolved is valid; closed resolved is not.
  • Use P0, P1, or P2 for incident priority.
  • Do not set event priority. Event severity is read-only.
  • Set a closed status when requesting event remediation.
  • On 429, wait for the retry period before sending the request again. Bulk writes have a separate, lower rate limit than single-record writes.

A write succeeded, but nothing changed​

Single-record writes are idempotent. If the current value already matches the request, the result can show changed: false. Check the current snapshot and the returned operation ID.

Identical comments on the same record are deduplicated and return the earlier operation ID. Change the wording only when you intend to add a separate comment.

Some modules rescan assets and create a newer event in the same series. An update against a stale event identifier can be redirected to the latest event. The response states when this happens.

A bulk job looks incomplete​

Bulk updates run asynchronously:

  1. Pass the returned job_id to get_job_status.
  2. Poll until the job reaches a final state.
  3. Review successful, skipped, and failed records.
  4. Retry only failed records after correcting the cause.

A record skipped because it already has the target value is a successful no-op. If two fields needed changes, confirm that two separate jobs were created and checked.

Token expired or was rotated​

  1. Create or rotate the token under CloudSEK Platform → Integrations → Alerts API.
  2. Update every client config or environment variable that uses it.
  3. Restart the terminal or source its shell profile when environment variables changed.
  4. Fully quit and reopen Claude Desktop. Kiro reloads saved config files, but it must restart when its process environment changes.