Write Operations

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

Important:

• Write operations create real resources and real charges. Activating IONOS_MCP_TOOL_SCOPE lets an AI model provision billable infrastructure in your live 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.

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:

{
  "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.

Info: Your 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.

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

Note: confirmation_token is not your 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.

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:

{
  "id": "<DATA_CENTER_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.

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:       <DATA_CENTER_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:      <DATA_CENTER_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.

All other products the MCP server covers remain read-only: 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, the Terraform provider, or the DCD 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.
• 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 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 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.
• 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 IONOS CLOUD audit trail. Query it with list_activitylog_events or in the DCD. For more information, see Activity Logs.

Next steps

• Tool Reference: The complete list of read and write tools, with the scope each one requires.
• Environment Variables: Full reference for all supported environment variables.
• Troubleshooting: Write tools missing, expired confirmation tokens, and immutable-field errors.
• FAQ: Answers on cost, responsibility, and limiting what the MCP Server can do.