Overview

Last updated:

The American Cloud MCP server lets an AI assistant manage your cloud in plain English. Connect it and your assistant can list, price, create and change virtual machines, storage, networks, Kubernetes clusters, databases, WordPress sites and DNS, with you in the loop for every change. It speaks the Model Context Protocol, so it works with Claude, Claude Code, ChatGPT, Grok, Cursor, Codex, Windsurf, VS Code and other MCP clients.

Two ways to connect

Hosted serverLocal server
Best forClaude on the web, Claude Desktop, Claude Code, ChatGPT, Grok, Cursor, CodexWindsurf, VS Code, other stdio clients, scripts and CI
SetupAdd one address, sign in to American CloudInstall Node.js, create an API token, edit a config file
CredentialYour American Cloud sign-in. No token to copy.An API token in your client config
PermissionsSet per app in Connected appsSet by the token and the --allow-writes flag
Addresshttps://mcp.americancloud.com/mcpnpx @americancloud/mcp

Most people want the hosted server. The client guides cover both, hosted first:

Once connected, see Things to try for prompt ideas.

How the hosted server works

You add the address to your client and sign in to American Cloud in your browser. Your client never sees a token. From then on the app acts as you: it can do what your American Cloud role allows, and nothing more. Claude asks you before it runs a tool that changes something, and tools that delete or reinstall a resource are marked destructive so that every client that supports confirmations prompts for them.

Each app you connect gets a row on the Connected apps page at console.americancloud.com/connected-apps. That page is where you control it:

  • A known app starts with full access. Claude, Claude Code, ChatGPT, Codex and Cursor can list, create, change and delete the resources of each service, within your own role. An app that registered itself with the sign-in service, such as Grok, starts read-only, and you switch it to full access in Connected apps. Account settings, billing, users and API keys stay out of reach of every app.
  • Limit an app at any time. Choose Read-only to let the app look and price but change nothing, or Custom to pick services one by one. The app picks up the change on its next request.
  • Revoke ends the app's access at once. To connect again, wait a few minutes and sign in once more.
  • Each app and each user has its own row. A teammate who connects Claude gets their own row, capped by their own role. Users who manage the account's users can see and revoke every app in the account.
  • You get an email each time an app connects. If it was not you, revoke the app and contact support.
Screenshot: the permissions dialog for a connected app, with Read-only, Full access and Custom

Giving your assistant a long autonomous task? Set the app to Read-only first, review the plan, then switch to Full access for the build.

How the local server works

The local server is the same open-source package, @americancloud/mcp, run on your own machine. Your API token goes from your environment straight to the American Cloud API. It's open source (Apache-2.0) at github.com/American-Cloud/americancloud-mcp and published to npm with provenance attestation.

[ claude code · read-only audit ]
A read-only token audits a real account — inventory, then a firewall finding. No writes.

You need Node.js 20 or newer and an API token from console.americancloud.com/api-tokens. A token has the same presets as a connected app: Read-only, Full access, or Custom. The generic client configuration is:

json
{
  "mcpServers": {
    "americancloud": {
      "command": "npx",
      "args": ["-y", "@americancloud/mcp"],
      "env": {
        "AMERICANCLOUD_API_TOKEN": "your-api-token"
      }
    }
  }
}

Safety: read-only by default

The local server lets an AI assistant work with real infrastructure and real billing, so it is deliberately conservative out of the box:

  • Read-only by default. Only read tools (list, get, cost estimates) are registered until you add "--allow-writes" to args. Without it, the assistant can explore and inspect but cannot create, modify, or delete anything.
  • Use the narrowest token. With a Read-only token, writes are impossible at the account level regardless of any flag. Only pair a Full access token with --allow-writes when you actually want the assistant to make changes.
  • Secrets need --allow-writes too. Five read tools return a credential: the kubeconfig, the object storage keys (two tools), a database password and the backup repository keys. The API needs the manage permission for them, so the local server registers them only with --allow-writes.
  • Destructive tools are flagged. Delete, release, reinstall, and similar irreversible operations are marked destructive, so MCP clients that support confirmations will prompt you before running them.
json
"args": ["-y", "@americancloud/mcp", "--allow-writes"]

Other clouds' MCP servers make different choices here: some can't write at all, and some can do whatever your credential allows. See which cloud providers have an MCP server for a side-by-side.

Environment variables

VariableRequiredPurpose
AMERICANCLOUD_API_TOKENyesYour API token
AMERICANCLOUD_API_URLnoAPI base URL override

An API key from before API tokens existed (a client ID and secret pair) keeps working. Set AMERICANCLOUD_API_CLIENT_ID and AMERICANCLOUD_API_CLIENT_SECRET instead of the token, never both. The API tokens page lists such keys under Legacy with a Replace with token button.

Inside a VM

The MCP server manages your account: it creates, changes, powers, resizes and deletes resources. It does not run commands inside a VM, and American Cloud stores no key to your machines. We chose this on purpose: a provider-run command channel into your servers would be a root path for anyone who compromised it or tricked your assistant, and your SSH keys are safer with you.

In-VM work takes one of these paths:

  • A coding agent with a shell, such as Claude Code, Codex or Cursor, gets the VM's public IP from the server and runs ssh cloud@<public-ip> itself, with your own key. It can install software, deploy code and check services in the same session. Register your machine's public key with American Cloud before the first VM and create the VM with it, so the agent logs in with a key and never needs the VM password.
  • A new VM can configure itself on first boot. Ask the assistant to include a cloud-init script when it creates the VM.
  • A running VM can be reached from a browser console that the assistant opens for you.

A chat assistant without a shell, such as Claude.ai, ChatGPT or Grok, can use the second and third paths. Both need write access, so an app that starts read-only, such as Grok, needs Full access first. If you ask the assistant to run a command on a VM, it tells you so and offers these instead.

Service groups

The server provides 179 tools across 7 service groups. The hosted server lists every tool in every group to every app; the app's permissions in Connected apps decide which calls succeed. The local server enables the core infrastructure groups by default: compute, storage, networking, kubernetes. Scope or extend the list with the --services flag:

sh
npx @americancloud/mcp --services all
npx @americancloud/mcp --services compute,dns
GroupToolsCovers
compute (default)25VMs, packages, images, regions, SSH keys
storage (default)27block storage, snapshots, object storage and its access keys
networking (default)57isolated/VPC networks, VPC tiers, public IPs, firewall, port forwarding, load balancers, egress, ACLs
kubernetes (default)11managed Kubernetes clusters
databases36MySQL/PostgreSQL/Redis database clusters, backups, infrastructure, offerings
wordpress16managed WordPress
dns7hosted DNS zones and records

In a local client config, flags go in the args array:

json
"args": ["-y", "@americancloud/mcp", "--services", "all"]

Scoping with --services keeps the tool list small, which helps clients with limited context windows pick the right tool.

A few read tools return credentials by design — for example fetching a Kubernetes cluster config or a database connection string. Their tool descriptions are labeled accordingly. These tools need the manage permission of their service, because the answer grants access; on the local server they also need --allow-writes. Treat retrieved credentials with the same care as any other secret.

Versioning and source

The server is versioned independently of the platform API; each release states the API surface it targets. Release notes, source, and issue tracking live on GitHub.

Contact us