> 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 ideal configuration for nearly every client, including Claude Code, Claude Desktop, Cursor, 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. |
| `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="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).

**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
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.