Login

Codex

Last updated: July 10, 2026

This guide connects Codex — OpenAI's agentic coding CLI — to American Cloud. Like Claude Code, Codex runs in your terminal, so a single session can both manage your infrastructure through the MCP server and run commands on your machine — provision a server and deploy to it without leaving the CLI.

Prerequisites

  • Codex CLI installed (codex --version to check)
  • Node.js 20 or newer — the MCP server runs via npx
  • An American Cloud API key from console.americancloud.com/api-keys — start with a read-only key

Configure

Add the server with one command:

sh
codex mcp add americancloud \
  --env AMERICANCLOUD_API_CLIENT_ID=your-client-id \
  --env AMERICANCLOUD_API_CLIENT_SECRET=your-client-secret \
  -- npx -y @americancloud/mcp

This writes the server into your Codex config at ~/.codex/config.toml. You can also add or edit the entry by hand:

toml
[mcp_servers.americancloud]
command = "npx"
args = ["-y", "@americancloud/mcp"]
 
[mcp_servers.americancloud.env]
AMERICANCLOUD_API_CLIENT_ID = "your-client-id"
AMERICANCLOUD_API_CLIENT_SECRET = "your-client-secret"

The first launch runs npx, which downloads the package before the server starts. Codex's default startup timeout is 10 seconds — if the first start times out on a cold cache, raise it by adding startup_timeout_sec = 30 under [mcp_servers.americancloud].

Verify

List the configured servers to confirm it registered:

sh
codex mcp list

Then start a Codex session and ask:

What regions can I deploy to on American Cloud?

Codex will ask for approval to run the American Cloud tool the first time.

Enable resource management (optional)

By default the server is read-only. To let Codex create and manage resources, use a read-write API key and add the --allow-writes flag after the package name — via the CLI:

sh
codex mcp add americancloud \
  --env AMERICANCLOUD_API_CLIENT_ID=your-client-id \
  --env AMERICANCLOUD_API_CLIENT_SECRET=your-client-secret \
  -- npx -y @americancloud/mcp --allow-writes

Or in ~/.codex/config.toml:

toml
args = ["-y", "@americancloud/mcp", "--allow-writes"]

Codex asks for approval before running tools (depending on your approval mode), and destructive operations are explicitly flagged. We recommend keeping approvals on for write-enabled setups.

The build-and-deploy workflow

Where this setup shines: Codex combines American Cloud tools with your terminal. A single session can:

  1. Write or modify your application code
  2. Create a VM with your SSH key, configure firewall rules, and point DNS at it — via the MCP server
  3. Deploy and verify over SSH — via your shell

Try:

Create a small Ubuntu VM in us-west with my SSH key, open ports 22 and 80, wait for it to come up, then install nginx over SSH and confirm it serves the default page.

Or for Kubernetes:

Fetch the kubeconfig for my production cluster and check whether all deployments are healthy.

Next steps

  • Things to try — prompt ideas from quick audits to full provisioning
  • Overview — service groups, --services scoping, and safety details