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:

   ls -l /path/to/ionoscloud-mcp

2. Test the binary directly:

   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:

   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 Selective Tool Loading.

Authentication errors

If tools return authentication errors, verify your credentials:

1. Confirm IONOS_TOKEN is set and has not expired. Check DCD Token Management.
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 IONOS CLOUD 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). 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 above).

Rate limit errors

If a tool returns an HTTP 429 error, the IONOS CLOUD API 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

• FAQ: answers to common questions about credentials, rate limits, and token scope
• Selective Tool Loading: if tools are still missing after fixing the connection
• Use Cases: try your first real workflows once connected