> 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/configuration/selective-tool-loading.md).

# 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), [<mark style="color:blue;">Activity Log</mark>](https://docs.ionos.com/cloud/observability/activity-logs), and [<mark style="color:blue;">Managed Kubernetes</mark>](https://docs.ionos.com/cloud/containers/managed-kubernetes) tools are always available at startup. Compute Engine and Object Storage tools register automatically at startup. You can skip this page and begin 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 118 product tools register at startup. The system skips loader sentinels, which exist solely to bootstrap lazy mode.                                                                                                                                                                                                                                             | The right configuration for every client without a tool-count cap, including Claude Code, Claude Desktop, VS Code, JetBrains, Gemini CLI, and Claude in Chrome.                                                                                                                                                                                |
| `lazy`                     | At startup, the system registers a total of 47 tools: the 45 always-on product tools (Cloud DNS, Billing, Certificate Manager, Activity Log, Managed Kubernetes) and the two loader sentinels (`ionos_load_compute_tools` and `ionos_load_objectstorage_tools`). Compute Engine and Object Storage tools register only after the matching loader sentinel is called. | The mode suits clients with a hard tool-count cap, such as Windsurf's 100-tool limit or operators who need the smallest possible tool surface for compliance-audited environments. The configuration requires the client to honor `notifications/tools/list_changed`, a capability that Windsurf, Claude Desktop, Cursor, and VS Code support. |
| `dynamic` (alias `search`) | The server registers only three meta-tools: `ionos_search_tools`, `ionos_describe_tools`, and `ionos_call_tool`. The full catalog stays in memory behind them, and the AI assistant discovers and invokes tools through those three at runtime.                                                                                                                      | Clients with a hard tool-count cap and no tool search of their own, such as Cursor with its cap of roughly 40 tools. Because the registered tool list never changes, the client is not required to support `notifications/tools/list_changed`.                                                                                                 |

{% hint style="info" %}
**Note:** 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` 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. For more information, see [<mark style="color:blue;">Authentication</mark>](/cloud/ai/mcp-server/configuration/authentication.md). Every tool is bounded by the token's permissions regardless of load mode.

Load mode is also not the lever for preventing changes to your account. Whether write tools exist at all is controlled by `IONOS_MCP_TOOL_SCOPE`, which applies identically in every load mode. For more information, see [<mark style="color:blue;">Write Operations</mark>](/cloud/ai/mcp-server/configuration/write-operations.md).
{% 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`, and `dynamic` (alias `search`). An unrecognised value logs a warning to standard error and falls back to `eager`.

{% hint style="warning" %}
**Important:**

* Windsurf users must set `IONOS_MCP_LOAD_MODE=lazy`. Windsurf enforces a strict 100-tool limit across all MCP servers. While the default `eager` mode exceeds this limit by providing 118 tools, the `lazy` mode preserves the startup catalog of 47 tools (45 always-on product tools and 2 loader sentinels). For more information, see [<mark style="color:blue;">Windsurf</mark>](/cloud/ai/mcp-server/connect-to-an-ai-client/windsurf.md).
* Cursor users must set `IONOS_MCP_LOAD_MODE=dynamic` instead. Cursor caps tools at roughly 40 across all MCP servers, which neither `eager` nor the 47-tool `lazy` catalog fits, and `dynamic` presents just three tools. For more information, see [<mark style="color:blue;">Cursor</mark>](/cloud/ai/mcp-server/connect-to-an-ai-client/cursor.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 %}

## Enabling dynamic mode

Set `IONOS_MCP_LOAD_MODE=dynamic` 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": "dynamic"
      }
    }
  }
}
```

The client then sees three tools instead of the full catalog:

| Tool                   | What it does                                                                                                                                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ionos_search_tools`   | Searches the catalog by keyword and returns matching tool names, their product group, and a shortened one-line description. Input schemas are not included. Leave the query empty and set `group` to browse one product. |
| `ionos_describe_tools` | Returns a tool's full description and its complete input schema.                                                                                                                                                         |
| `ionos_call_tool`      | Invokes a tool by name with its arguments.                                                                                                                                                                               |

The AI assistant works through them in that order: search for a capability, describe the tool it picked, then call it. Nothing else changes. Scope, permissions, and confirmation gating behave exactly as in the other modes, and a tool the active `IONOS_MCP_TOOL_SCOPE` disallows is not in the catalog at all. For more information, see [<mark style="color:blue;">Write Operations</mark>](/cloud/ai/mcp-server/configuration/write-operations.md).

The cost is round trips: the assistant needs two extra calls before it can act, and it cannot see the tools directly. Prefer `eager` on clients that either have no tool cap or defer tool schemas themselves, such as Claude Code.

## 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
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, and the optional `goal` query parameter:

```
GET https://docs.ionos.com/cloud/ai/mcp-server/configuration/selective-tool-loading.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.