# Troubleshooting

## The AI client does not show any IONOS CLOUD tools

**Possible causes:**

* The `ionoscloud-mcp` binary path in your configuration is incorrect.
* The binary does not have run permissions.
* The AI client did not reload its configuration after you edited it.

**Steps:**

1. Verify the binary exists and is executable:

   ```bash
   ls -l /path/to/ionoscloud-mcp
   ```
2. Test the binary directly:

   ```bash
   IONOS_TOKEN=your-token /path/to/ionoscloud-mcp
   ```

   The process blocks waiting for JSON-RPC input on stdin; it produces no output. Press **Ctrl+C** to exit. The MCP server does not validate the `IONOS_TOKEN` at launch, so a bad token will not cause an immediate exit; you will see an authentication error on the first tool call instead. If the process exits immediately with a non-zero code, the binary itself is broken or the binary architecture does not match your platform.

   On Windows:

   ```cmd
   set IONOS_TOKEN=your-token && C:\path\to\ionoscloud-mcp.exe
   ```
3. Restart your AI client after saving the configuration file.

## Compute Engine or Object Storage tools are missing

By default, all tools are registered at startup, so Compute Engine and Object Storage tools should be visible immediately. If they are missing, the cause depends on which AI client you are using:

**On Windsurf** (which applies a 100-tool cap that the default eager mode exceeds): lazy mode is correct. Confirm `IONOS_MCP_LOAD_MODE=lazy` is set in the `env` block, then ask your AI assistant *"Load the IONOS CLOUD Compute tools"* (or *"Load the Object Storage tools"*). The assistant will call the matching loader sentinel and Windsurf will refresh its catalog.

**On any other client** (Claude Desktop, Cursor, VS Code, Claude Code, etc.):

1. Check the `env` block of your AI client configuration. If `IONOS_MCP_LOAD_MODE` is set to `lazy`, **remove the line entirely** to fall back to the eager default and restart your AI client — every tool should then appear. Alternatively, leave the env var in place and ask your AI assistant *"Load the IONOS CLOUD Compute tools"* to register Compute on demand via the loader sentinel.
2. For Object Storage specifically, also confirm that `IONOS_S3_ACCESS_KEY` and `IONOS_S3_SECRET_KEY` are set — Object Storage tools register at startup but their probes return 401 without S3 credentials.

For more information, see [<mark style="color:blue;">Selective Tool Loading</mark>](/cloud/ai/mcp-server/configuration/selective-tool-loading.md).

## Authentication errors

If tools return authentication errors, verify your credentials:

1. Confirm `IONOS_TOKEN` is set and has not expired. Check [<mark style="color:blue;">DCD Token Management</mark>](https://dcd.ionos.com/).
2. For Object Storage tools, confirm `IONOS_S3_ACCESS_KEY` and `IONOS_S3_SECRET_KEY` are set correctly.
3. Check there are no extra spaces or quotes around the credential values in your configuration file.

## Object Storage tools time out

Certain Object Storage configuration tools may time out on buckets with large configurations or in regions with higher latency.

**Steps:**

1. Retry the request; transient network issues are the most common cause.
2. If the issue persists on a specific bucket, verify the bucket exists and your <code class="expression">space.vars.ionos\_cloud</code> account can access it.

## The server exits immediately

If the MCP server process exits as soon as your AI client starts it, the cause is typically the binary itself, not credentials. The server does not validate `IONOS_TOKEN` at launch; an invalid or missing token surfaces as an authentication error on the first tool call instead (see [Authentication errors](#authentication-errors)). Common causes for an immediate exit:

* The binary architecture does not match the host (for example, an `arm64` binary on an `amd64` machine).
* The binary path in your configuration is wrong, or the binary is not executable.
* The binary was quarantined by macOS Gatekeeper (run `xattr -d com.apple.quarantine /path/to/ionoscloud-mcp`).

**Steps:**

1. Check the AI client's MCP server logs:
   * **Claude Desktop (macOS):** `~/Library/Logs/Claude/mcp-server-ionoscloud.log`
   * **Claude Desktop (Windows):** `%APPDATA%\Claude\logs\mcp-server-ionoscloud.log`
   * **Claude Code:** Run `claude mcp list` to check server status; add `--debug` flag when starting Claude Code for verbose output
   * **Cursor:** Open **Output** panel > select **MCP** from the dropdown
   * **VS Code:** Open **Output** panel > select **GitHub Copilot** or **MCP** from the dropdown
   * **Windsurf:** Open **Output** panel > select **Cascade** from the dropdown
   * **Gemini CLI:** Run with `--debug` flag: `gemini --debug`
   * **Kiro:** Check `~/.kiro/logs/` for MCP server logs
   * **JetBrains AI:** Go to **Help** > **Show Log in Finder/Explorer** and search for MCP entries
   * **Continue:** Open **Output** panel in VS Code > select **Continue** from the dropdown
   * **Zed:** Open the developer console via **Help** > **Show Developer Console**
2. Verify the binary runs at all by invoking it directly from a shell (see [The AI client does not show any IONOS CLOUD tools](#the-ai-client-does-not-show-any-ionos-cloud-tools) above).

## Rate limit errors

If a tool returns an HTTP 429 error, the <code class="expression">space.vars.ionos\_cloud\_api</code> rate limit has been exceeded.

**How to identify it:** The error message includes `429` or `rate limit`. A 429 is distinct from a 401 (invalid token) or 403 (insufficient permissions).

**Steps:**

1. Wait 30–60 seconds before retrying.
2. If you are running agentic workflows, add pauses between tool calls or reduce the scope of each query (for example, query one data center at a time instead of all at once).
3. Note that MCP clients may call multiple tools in parallel; a single AI response can trigger several simultaneous API requests. Reducing parallelism, or opting into lazy loading with `IONOS_MCP_LOAD_MODE=lazy` so fewer tools are exposed up front, can help.

## JSON configuration errors

If your AI client reports a configuration parsing error, check your JSON for syntax issues such as trailing commas or mismatched braces. Use a JSON validator if needed.

## Next steps

* [<mark style="color:blue;">FAQ</mark>](/cloud/ai/mcp-server/faq.md): answers to common questions about credentials, rate limits, and token scope
* [<mark style="color:blue;">Selective Tool Loading</mark>](/cloud/ai/mcp-server/configuration/selective-tool-loading.md): if tools are still missing after fixing the connection
* [<mark style="color:blue;">Use Cases</mark>](/cloud/ai/mcp-server/use-cases.md): try your first real workflows once connected


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ionos.com/cloud/ai/mcp-server/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.