# Selective Tool Loading

[<mark style="color:blue;">Cloud DNS</mark>](https://docs.ionos.com/cloud/network-services/cloud-dns), [<mark style="color:blue;">Billing</mark>](https://docs.ionos.com/cloud/management/usage/cost-and-usage), [<mark style="color:blue;">Certificate Manager</mark>](https://docs.ionos.com/cloud/security/certificate-manager), and [<mark style="color:blue;">Activity Log</mark>](https://docs.ionos.com/cloud/observability/activity-logs) tools are always available at startup. By default, Compute Engine and Object Storage tools are now also registered at startup, so most users can skip this page; just start asking your AI assistant questions about your resources.

The MCP server supports three tool-loading modes, selected via the `IONOS_MCP_LOAD_MODE` environment variable:

| Mode              | Behaviour                                                                                                                                                                                                                                                                                                                        | When to use                                                                                                                                                                                                                                                                             |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eager` (default) | All 110 product tools register at startup. Loader sentinels are not registered; they exist only to bootstrap lazy mode.                                                                                                                                                                                                          | The right choice for nearly every client, including Claude Code, Claude Desktop, Cursor, VS Code, JetBrains, Gemini CLI, and Claude in Chrome.                                                                                                                                          |
| `lazy`            | Only the 37 always-on product tools (Cloud DNS, Billing, Certificate Manager, Activity Log) plus the 2 loader sentinels (`ionos_load_compute_tools`, `ionos_load_objectstorage_tools`) register at startup — 39 tools total. Compute Engine and Object Storage tools register only after the matching loader sentinel is called. | Clients with a hard tool-count cap (Windsurf's 100-tool limit) or operators who want the smallest possible tool surface for compliance-audited environments. Requires that the client honours `notifications/tools/list_changed`; Windsurf, Claude Desktop, Cursor, and VS Code all do. |
| `router`          | Reserved for a future release; not yet implemented. If set today, the server logs a warning to stderr and falls back to eager.                                                                                                                                                                                                   | Not available today.                                                                                                                                                                                                                                                                    |

{% hint style="info" %}
**Why eager is the default:** Claude Code (the dominant client) defers tool schemas client-side using ToolSearch, so only tool names (1–3k tokens) are sent up front. Eager startup is cheap there. Clients that ignore `notifications/tools/list_changed` would never discover lazy tools at all, so eager-by-default is universally safer.

For environments where tool exposure matters (compliance audits, sensitive accounts), the right lever is **token scope**, not load mode. Scope `IONOS_TOKEN` to only the products you actually need — see [<mark style="color:blue;">Authentication</mark>](/cloud/ai/mcp-server/configuration/authentication.md). All tools remain read-only and bounded by the token's permissions regardless of load mode.
{% endhint %}

## Enabling lazy mode

Set `IONOS_MCP_LOAD_MODE=lazy` in the `env` block of your AI client configuration:

```json
{
  "mcpServers": {
    "ionoscloud": {
      "command": "/path/to/ionoscloud-mcp",
      "env": {
        "IONOS_TOKEN": "your-api-token",
        "IONOS_MCP_LOAD_MODE": "lazy"
      }
    }
  }
}
```

Accepted values: `eager` (default), `lazy`, `router` (reserved).

{% hint style="info" %}
**Windsurf users must set `IONOS_MCP_LOAD_MODE=lazy`.** Windsurf applies a 100-tool limit across all MCP servers. The default eager mode exposes 110 tools and exceeds this limit; lazy mode keeps the startup catalog at 39 tools (37 always-on product tools + 2 loader sentinels). For more information, see [<mark style="color:blue;">Windsurf</mark>](/cloud/ai/mcp-server/connect-to-an-ai-client/windsurf.md).

**Do not use lazy mode for unattended agentic workflows on clients with no tool cap.** An agent that does not know to call a loader sentinel first will silently skip Compute and Object Storage operations; the agent says "I don't have a tool to list your servers" instead of returning an error. For more information, see [<mark style="color:blue;">Use IONOS CLOUD Resources in Agentic Workflows</mark>](/cloud/ai/mcp-server/use-cases/agentic-workflows.md). On Windsurf, the 100-tool cap takes precedence and lazy mode is the only option; expect to prompt the agent explicitly with *"Load the Compute tools"* before any Compute step.
{% endhint %}

## Loader tools

The two loader sentinels are present **only when `IONOS_MCP_LOAD_MODE=lazy`** is set. In eager mode (the default), they do not appear in the catalog because the full tool set is already registered.

| Tool                             | Effect                                                                                                                                 | Available in     |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `ionos_load_compute_tools`       | Registers all 50 Compute Engine tools and sends a `notifications/tools/list_changed` notification so the client refreshes its catalog. | `lazy` mode only |
| `ionos_load_objectstorage_tools` | Registers all 23 Object Storage tools and sends a `notifications/tools/list_changed` notification.                                     | `lazy` mode only |

Call them by asking your AI assistant. For example, send this prompt:

> Load the <code class="expression">space.vars.ionos\_cloud</code> Compute tools.


---

# Agent Instructions: 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/configuration/selective-tool-loading.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.