> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/ai/mcp-server/troubleshooting.md).

# 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 startup, so an invalid token does 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

All tools are registered at startup by default. Compute Engine and Object Storage tools are 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 default eager mode. Once you restart your AI client, all tools will be available immediately. Alternatively, leave the `env` variable in place and prompt your AI assistant: "**Load the IONOS CLOUD Compute tools**" to register the Compute tools on demand.
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).

## Write tools do not appear

Write tools are opt-in. If your AI assistant reports that it can only read your infrastructure, or that no tool exists for creating or deleting a resource, the scope is the usual cause.

**Possible causes:**

* `IONOS_MCP_TOOL_SCOPE` is not set. The server is read-only by default.
* The value is misspelled. An unrecognised value falls back to read-only without failing, so a typo such as `writes`, or `write` followed by a trailing space, silently disables every write tool.
* The AI client was not restarted. The scope is read once, at startup.
* You set `write` but asked for a deletion. Deletions and disruptive actions such as `stop_server` require `destructive`.
* The tool does not exist. A few operations are not exposed at all.

**Steps:**

1. Confirm the `env` block of your AI client configuration contains `IONOS_MCP_TOOL_SCOPE`, set to `write` or `destructive`, with no stray whitespace or quotes.
2. Restart the AI client and check the MCP server log. The server writes the effective scope to standard error at startup, so the log shows which level actually took effect. For log locations, see [<mark style="color:blue;">The server exits immediately</mark>](#the-server-exits-immediately).
3. If you need deletions, set the value to `destructive`. It implies `write`, so a single value is enough.
4. In lazy mode (`IONOS_MCP_LOAD_MODE=lazy`), ask your assistant to *"Load the IONOS CLOUD Compute tools"* first. Write tools register alongside the read tools when the loader runs.
5. If the tool still does not exist, check [<mark style="color:blue;">Operations that are not available</mark>](/cloud/ai/mcp-server/configuration/write-operations.md#operations-that-are-not-available).

## A write tool asks for confirmation, or reports an invalid or expired token

This is expected behaviour, not an error. Every `create_*` tool, every `delete_*` tool, and every disruptive action takes two calls: the first returns a preview and a single-use `confirmation_token`, and the second carries that token to perform the operation.

A token is rejected when:

* More than five minutes passed between the preview and the confirmation.
* The token was already used. Each one works once.
* The token is being applied to a different resource or a different operation than the one it was issued for.
* A different client or session issued it. Tokens do not transfer between sessions.

**Steps:**

1. Ask the assistant to run the operation again from the beginning. A fresh preview and a fresh token are issued.
2. Read the preview before confirming. For a delete, it lists what else the operation affects.
3. If the assistant loops between preview and rejection, start a new conversation so it discards the stale token from its context.

For more information, see [<mark style="color:blue;">Two-phase confirmation</mark>](/cloud/ai/mcp-server/configuration/write-operations.md#two-phase-confirmation).

## A write returns an immutable-field or validation error

Some fields cannot be changed after a resource is created, and a few operations are not available at all.

**Possible causes:**

* The field is immutable. A Managed Kubernetes node pool cannot be renamed, and neither can its per-node hardware be changed. A cluster's location, NAT gateway IP, node subnet, and public/private setting are fixed at creation.
* An autoscaler cannot be switched off once enabled. Its bounds can still be changed.
* You used `0.0.0.0/0` in a firewall or security group rule. This is rejected up front, because the API stores it as a bare `0.0.0.0`, which matches nothing. Omit the field instead to match all sources.
* The operation is not exposed. Renaming an IP block, attaching a CD-ROM to a server, attaching a NIC to a classic load balancer, and detaching a LAN from a private cross connect are not available through the MCP server.

**Steps:**

1. Check [<mark style="color:blue;">Operations that are not available</mark>](/cloud/ai/mcp-server/configuration/write-operations.md#operations-that-are-not-available).
2. For an immutable field, create a replacement resource rather than trying to change the existing one.
3. For an operation the server does not expose, use [<mark style="color:blue;">ionosctl</mark>](https://docs.ionos.com/cli-ionosctl), the [<mark style="color:blue;">Terraform provider</mark>](https://docs.ionos.com/terraform-provider), or the [<mark style="color:blue;">DCD</mark>](https://dcd.ionos.com/).

## A Managed Kubernetes write appears to do nothing

Managed Kubernetes writes are asynchronous. The API answers with `202 Accepted` and the tool returns before the change has taken effect, so an immediate follow-up read still shows the old values.

**Steps:**

1. Call `get_k8s_cluster` or `get_k8s_nodepool` and read `metadata.state`. Wait until it leaves `BUSY` before chaining a dependent call.
2. Note that a resource in the `BUSY` state *queues* further modifications rather than rejecting them. A second call that appears to succeed may not run until the first completes, so avoid sending several changes in quick succession.
3. For Compute Engine server power actions, check `get_server` and read `vmState` in the same way.

## The client cannot reach the server over HTTP

**Possible causes:**

* The server is listening on `127.0.0.1` and the client runs on another host or in another container.
* The client URL points at a path other than the root endpoint, or is configured as a stdio server.
* A firewall or container port mapping blocks the port.

**Steps:**

1. Read the startup line the server writes to standard error. It states the effective transport and listen address, for example `listening on 127.0.0.1:8080 (streamable HTTP transport)`. If it reports `stdio`, the value you passed was not recognised and the server fell back to the default.
2. If the client is not on the same host, restart the server with a reachable address, such as `--http-addr :8080`, and publish the port from the container with `-p 8080:8080`.
3. Configure the client with the root URL, `http://<host>:<port>/`, and declare it as a Streamable HTTP (remote) server rather than a command to run.

For more information, see [<mark style="color:blue;">Transport</mark>](/cloud/ai/mcp-server/configuration/transport.md).

## The server starts but the AI client reports that it failed

If you set `IONOS_MCP_TRANSPORT=http` in the `env` block of an AI client that starts the binary itself, the server listens on a port instead of answering the client on standard input. The client then reports a failed or unresponsive server. Remove `IONOS_MCP_TRANSPORT` from the client configuration; desktop AI clients require the default `stdio` transport.

## 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 startup; an invalid or missing token surfaces as an authentication error on the first tool call instead. For more information, see [<mark style="color:blue;">Authentication errors</mark>](#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 incorrect, 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;">Write Operations</mark>](/cloud/ai/mcp-server/configuration/write-operations.md): enable write tools and understand the confirmation flow
* [<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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.