> 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/write-operations.md). # Write Operations The space.vars.ionos\_cloud\_mcp\_server is read-only by default. Every tool it exposes is an inspection or query operation, and the server cannot create, modify, or delete anything in your account. Write tools are available for Compute Engine and Managed Kubernetes, but they are opt-in. They register only when you set the `IONOS_MCP_TOOL_SCOPE` environment variable. Until you do, they are not present in the server's tool list and your AI assistant cannot see or call them. {% hint style="warning" %} **Important:** * Write operations create real resources and real charges. Activating `IONOS_MCP_TOOL_SCOPE` lets an AI model provision billable infrastructure in your live space.vars.ionos\_cloud account. Every resource it creates appears on your invoice, effective immediately. Some resources are billed even when nothing uses them, such as a reserved IP block, a snapshot, or a volume left behind after its server is deleted. Deleted data is not recoverable without a snapshot, and a released public IP address cannot be reclaimed. * An AI model decides when and how often to call these tools. It can misinterpret your intent, retry more often than you expect, or select a larger resource than you had in mind. The two-phase confirmation flow exists to keep a human in that loop, but it cannot help if your AI client is configured to approve tool calls automatically; in that setup, the model completes both phases on its own. * You are responsible for everything created, modified, or deleted in your account through these tools, and for the resulting charges. IONOS does not control how a model chooses to call them and is not responsible for any cost, data loss, or outage that results. {% endhint %} ## Activate write tools Set `IONOS_MCP_TOOL_SCOPE` in the `env` block of your AI client's MCP server configuration. The levels are hierarchical, so a single value is enough: `destructive` already grants `write` and `read`. | `IONOS_MCP_TOOL_SCOPE` | Activates | Tools Registered | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | | Unset or `read` (default) | Read-only tools: `list_*`, `get_*`, `head_*` | 118 | | `write` | The above, plus `create_*`, `update_*`, and the non-disruptive actions `start_`, `resume_`, `attach_`, `assign_` | 165 | | `destructive` | The above, plus `delete_*` and the disruptive actions `stop_`, `reboot_`, `suspend_`, `upgrade_`, `restore_`, `detach_`, `recreate_` (implies `write`) | 195 | A comma-separated list such as `read,write` is also accepted. An unrecognised value falls back to read-only. The server logs the effective scope to standard error at startup, so check your AI client's MCP log if you are unsure which level is active. **Example configuration:** ```json { "mcpServers": { "ionoscloud": { "command": "/path/to/ionoscloud-mcp", "env": { "IONOS_TOKEN": "your-api-token", "IONOS_MCP_TOOL_SCOPE": "write" } } } } ``` Restart your AI client after changing the value. The scope is read once at startup. {% hint style="info" %} **Info:** Your space.vars.ionos\_cloud\_api token must also carry write permissions for the products you intend to modify. A read-only token combined with `IONOS_MCP_TOOL_SCOPE=write` registers the write tools, but every call fails with an authorization error. For more information, see [Authentication](/cloud/ai/mcp-server/configuration/authentication.md). {% endhint %} ## How the scope gate works A tool that the active scope disallows is **never registered**. It does not appear in the server's `tools/list` response, so the AI client never learns it exists and cannot call it. * The gate is applied in all three load modes: `eager`, `lazy`, and `dynamic`. For more information, see [Selective Tool Loading](/cloud/ai/mcp-server/configuration/selective-tool-loading.md). * Enforcement is always server-side. Write tools carry the MCP annotations `readOnlyHint`, `destructiveHint`, and `idempotentHint` so that AI clients can build their own approval prompts, but those annotations are a convenience for the client, not the control. * A tool's class comes from the operation it performs, not from the underlying HTTP method. `stop_server` is an HTTP `POST` and is classified as destructive because it interrupts a running server. `detach_server_volume` is an HTTP `DELETE` but does not delete the volume. ## Two-phase confirmation Every `create_*` tool, every `delete_*` tool, and every disruptive action is confirmation-gated. The operation takes two calls: 1. **Preview:** The first call changes nothing. It returns a summary of exactly what the operation will do, together with a single-use `confirmation_token`. 2. **Run:** A second call carrying that token performs the operation. The token is valid for five minutes and can be used once. It is bound to the calling session and to the exact target and operation it was issued for. A token issued for deleting one server cannot be used to delete another, to perform a different operation, or by a different client. {% hint style="info" %} **Note:** `confirmation_token` is not your space.vars.ionos\_cloud\_api token. The MCP server generates it for one pending operation on one target and discards it after use, while `IONOS_TOKEN` authenticates every call the server makes. For more information, see [Authentication](/cloud/ai/mcp-server/configuration/authentication.md). {% endhint %} For a delete, the preview also includes a **blast radius**: what else the operation affects. Deleting a data center lists the servers, volumes, and LANs inside it; deleting a LAN lists the NICs attached to it; deleting a forwarding rule lists the backends behind it. ### Example: create and delete a data center Ask your AI assistant to create a data center: > Create a data center named `docs-demo` in `de/txl`. The assistant calls `create_datacenter` without a `confirmation_token`. Nothing is created. The tool returns a preview that repeats the arguments to confirm and issues the token: ``` About to CREATE one data center: name: docs-demo location: de/txl To proceed, call create_datacenter again with: name: docs-demo location: de/txl confirmation_token: 975e92a57d94ff655c2c2ec3a8ade423 This creates exactly one data center. The token authorizes creating only this name+location and expires in 5m0s. ``` Once you confirm, the assistant repeats the call with the token, and the tool returns the created resource: ```json { "id": "", "type": "datacenter", "properties": { "name": "docs-demo", "location": "de/txl" }, "metadata": { "state": "BUSY" } } ``` The `BUSY` state is expected: provisioning continues in the background. For more information, see [Asynchronous operations](#asynchronous-operations). Deleting works the same way. The preview names the target, states that the operation cannot be undone, and lists the blast radius: ``` About to DELETE a data center and everything inside it. This is IRREVERSIBLE. id: name: docs-demo location: de/txl This data center is empty; deleting removes only the (empty) data center itself. To proceed, call delete_datacenter again with: datacenter_id: confirmation_token: 533c957e7150450f1de87de943cc8f14 This token authorizes deleting ONLY this data center and expires in 5m0s. ``` On a data center that holds resources, the middle line is replaced by a list of the servers, volumes, and LANs the delete removes with it. Read it before you confirm: it is the only point at which the full effect is shown to you. Reversible single-field changes do not require confirmation and complete in one call: `update_*`, `start_`, `attach_`, and `assign_`. ## What you can write 77 write tools are available in total: 69 on Compute Engine and 8 on Managed Kubernetes. | Area | What You Can Write | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Compute | Data centers; servers, including power control (start, stop, restart, suspend, resume, upgrade); volumes, including snapshot creation, snapshot restore, attach, and detach; NICs; LANs | | Networking | IP blocks (reserve and release); security groups and their rules, including assignment to servers and NICs; firewall rules; private cross connects | | Load balancing | Network and application load balancers, including their forwarding rules; target groups; NAT gateways and their translation rules | | Images | Private image and snapshot update and delete | | Managed Kubernetes | Clusters; node pools, including scaling, version upgrades, autoscaling bounds, attached LANs, labels, and annotations; individual worker nodes (recreate, delete) | For the complete list of tool names, see [Tool Reference](/cloud/ai/mcp-server/tool-reference.md). All other products the MCP server covers remain read-only: space.vars.ionos\_cloud\_object\_storage, Cloud DNS, Billing, Certificate Manager, and Activity Log. ## Operations that are not available A few operations have no tool. Use [ionosctl](https://docs.ionos.com/cli-ionosctl), the [Terraform provider](https://docs.ionos.com/terraform-provider), or the [DCD](https://dcd.ionos.com/) instead for the following: * Renaming an IP block. * Attaching or detaching a CD-ROM on a server. * Attaching a NIC to a load balancer. * Detaching a LAN from a private cross connect. Two other operations have no tool of their own: * There is no `create_image` tool. Private images are uploaded over FTP rather than created through the API. For more information, see [Upload an Image via FTP](/cloud/backup-and-storage/images-snapshots/private-images/how-tos/upload-image-via-ftp.md). * There is no `create_snapshot` tool. Snapshots are taken from a volume with `create_volume_snapshot`. Finally, a firewall or security group rule with a source or target of `0.0.0.0/0` is rejected up front. The API stores that value as a bare `0.0.0.0`, which matches nothing, so a rule intended to open a port silently closes it. Omit the field instead to match all sources. ## Asynchronous operations Writes are asynchronous on both products, and **the MCP server does not wait for them**. It returns as soon as the space.vars.ionos\_cloud\_api accepts the request, without polling the provisioning request on your behalf. Checking that a change has actually landed is the caller's job. * **Managed Kubernetes:** the API answers with `202 Accepted`. Poll `get_k8s_cluster` or `get_k8s_nodepool` and read `metadata.state` before chaining a dependent call. A resource in the `BUSY` state queues further modifications rather than rejecting them, so a second call that appears to succeed may not run until the first completes. * **Compute Engine:** a create or update returns the new resource with `metadata.state` set to `BUSY`, and provisioning continues in the background. Poll the matching `get_*` tool until the state is `AVAILABLE`. * **Server power actions:** these endpoints return no body at all, so the tool reports only that the request was accepted. Check progress with `get_server` and read `vmState`. * **Provisioning requests:** `list_requests` and `get_request` expose the API's request queue directly if you want the status of a specific operation rather than the state of the resource. ### Managed Kubernetes limits The space.vars.ionos\_cloud\_api imposes three limits that are worth knowing before you plan a change: * A node pool cannot be renamed. The name is set at creation and is immutable. * An autoscaler's bounds can be changed, but the autoscaler cannot be switched off once it is enabled. * `delete_k8s_node` is not a reliable way to replace a node. It removes the node first, and an active autoscaler may hold the pool at the smaller size rather than replacing it. Use `recreate_k8s_node` instead. ## Best practices * **Leave the server read-only unless you need writes.** The default scope is safe to connect to a production account and to share with teammates. * **Grant `write` rather than `destructive`** when deletion is not required. This is the single most effective limit you can apply. * **Use a dedicated API token** scoped to the products you intend to modify, rather than a token with full account access. For more information, see [Authentication](/cloud/ai/mcp-server/configuration/authentication.md). * **Require manual approval of tool calls in your AI client.** Automatic approval defeats the two-phase confirmation flow. * **Read the preview before confirming.** It is the only point at which you see the full effect of a delete. * **Prefer a non-production account or contract when experimenting**, particularly while you learn how your AI client handles tool approval. * **Audit what happened.** Every change the MCP server makes is recorded in the space.vars.ionos\_cloud audit trail. Query it with `list_activitylog_events` or in the DCD. For more information, see [Activity Logs](https://docs.ionos.com/cloud/observability/activity-logs). ## Next steps * [Tool Reference](/cloud/ai/mcp-server/tool-reference.md): The complete list of read and write tools, with the scope each one requires. * [Environment Variables](/cloud/ai/mcp-server/configuration/environment-variables.md): Full reference for all supported environment variables. * [Troubleshooting](/cloud/ai/mcp-server/troubleshooting.md): Write tools missing, expired confirmation tokens, and immutable-field errors. * [FAQ](/cloud/ai/mcp-server/faq.md): Answers on cost, responsibility, and limiting what the MCP Server can do. --- # 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/write-operations.md?ask=&goal= ``` `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.