Transport

The IONOS CLOUD MCP Server speaks two MCP transports:

Transport	How it works	When to use
stdio (default)	Your AI client starts the binary as a local subprocess and exchanges JSON-RPC messages over standard input and output.	Every desktop and terminal AI client, including Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, and JetBrains. Keep the default unless you have a reason to change it.
http	The server listens on a TCP address and serves the MCP Streamable HTTP transport at a single endpoint. Clients connect over the network instead of starting a process.	One shared server instance that several clients or automated agents connect to, for example a server running in a container or on a cluster, or a client that only supports remote MCP servers.

Both transports expose the same tools and the same tool-loading modes. The transport changes only how the client reaches the server, not what the server can do.

Select the transport

The transport is set with a command-line flag or an environment variable. If both are set, the flag wins:

Flag	Environment variable	Values	Default
--transport	IONOS_MCP_TRANSPORT	stdio, http	stdio
--http-addr	IONOS_MCP_HTTP_ADDR	A Go listen address, such as 127.0.0.1:8080, :8080, or 10.0.0.5:9000	127.0.0.1:8080

An unrecognised transport value falls back to stdio and the server logs a warning. --http-addr is ignored when the transport is stdio.

The server logs the effective transport and where it came from to standard error at startup:

transport: http (source: --transport flag)
listening on 127.0.0.1:8080 (streamable HTTP transport)

Start the server over HTTP

Run the binary with the HTTP transport:

export IONOS_TOKEN="your-api-token"
ionoscloud-mcp --transport http --http-addr 127.0.0.1:8080

In a container, bind to all interfaces so the port is reachable from outside the container. The default 127.0.0.1:8080 only accepts connections from inside it:

docker run --rm -p 8080:8080 \
  -e IONOS_TOKEN="$IONOS_TOKEN" \
  ghcr.io/ionos-cloud/ionoscloud-mcp --transport http --http-addr :8080

Connect a client over HTTP

Register the server in your AI client as a remote Streamable HTTP server, rather than as a command the client starts, and point it at the root path of the address the server listens on: http://<host>:<port>/.

The configuration format differs between clients. Most expect a url field in place of the command and env fields used for stdio, and some also expect a type such as http or streamable-http. Check your client's MCP documentation for the exact schema.

Credentials stay with the server. IONOS_TOKEN, IONOS_S3_ACCESS_KEY, and IONOS_S3_SECRET_KEY are read from the environment of the process that listens, so the client configuration holds no secrets. For more information, see Authentication.

A session is closed after 30 minutes without a request from the client. Clients reconnect and open a new session on the next tool call.

One server, one account

An HTTP instance is shared by design. Every client and agent that connects sends its tool calls to the same process, and that process holds one set of IONOS CLOUD credentials. Three consequences follow:

• The server authenticates to IONOS CLOUD; the clients do not authenticate to the server. All connected clients read and change resources in the account the server's IONOS_TOKEN belongs to, with the permissions of that token's contract user. Nothing in a tool call identifies the calling client to the IONOS CLOUD API, and the Activity Log attributes every request to that one user. To separate teams or environments, run a separate instance per token instead of sharing one.

• The tool scope is global. IONOS_MCP_TOOL_SCOPE is read once when the process starts and applies to the whole server. A server started with destructive offers the delete tools to every connected client and agent; there is no per-client or per-session scope. Start a read-only instance for clients that only inspect resources. For more information, see Write Operations.

• Confirmation tokens do not cross sessions. When a write operation requires two calls, the confirmation token returned by the first call is bound to three things: the session that made the call, the operation, and the target resource. An agent in one session cannot use it to confirm an operation another session started. The token remains single-use and expires after five minutes.

Important: The HTTP endpoint has no TLS and no authentication of its own.

The server does not verify who connects to it, and it does not terminate TLS. Any client that reaches the port can call the registered tools against your account, and both prompts and tool results travel in plain text.

Bind to 127.0.0.1 for local use, or place the server behind a reverse proxy such as NGINX or Caddy that terminates TLS and authenticates callers before you expose it beyond a trusted network. Never expose it directly to the public internet.

The server rejects cross-origin browser requests that are not safe, which prevents a web page from driving a local instance, but this is not a substitute for authentication.

Limitations

• Clients that start the server as a subprocess, which is most desktop AI clients, require stdio. Setting IONOS_MCP_TRANSPORT=http in such a client's env block makes the server listen on a port instead of answering the client, and the client reports that the server failed to start.

• The server-sent events transport that earlier MCP revisions used is not implemented. Clients that support only the deprecated SSE transport cannot connect.

• There is no health-check or metrics endpoint. Only the MCP endpoint is served.