Login

Codex

Last updated:

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. The hosted server needs two commands and a sign-in. The local server runs on your machine with an API token.

Hosted server

Connect

Add the server, then sign in:

sh
codex mcp add americancloud --url https://mcp.americancloud.com/mcp
codex mcp login americancloud

Your browser opens the American Cloud sign-in page. Sign in, then click Connect on the consent page. Codex stores the sign-in and holds the connection from then on. On a machine without a browser, add --no-browser to the login command, open the printed address elsewhere, and paste the full redirect address back into the terminal.

The entry in ~/.codex/config.toml holds no secret:

toml
[mcp_servers.americancloud]
url = "https://mcp.americancloud.com/mcp"

You receive an email that confirms the connection. If you did not connect Codex, open Connected apps and revoke it.

Codex starts with full access. Codex is a known app, so the connection begins with Full access as you, within your own American Cloud role: it can list, create, change and delete the resources of each service. To limit it, open Connected apps and choose Read-only or Custom. The change applies to Codex's next request; you do not need to sign in again.

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 asks for approval before it runs a tool. Choose Allow, Allow for this session, or Always allow.

Permissions

The app starts with Full access as you, within your own American Cloud role (see the note above). Codex asks for approval before running tools (depending on your approval mode), and destructive operations are explicitly flagged. We recommend keeping approvals on. To limit the app to read-only, or to revoke it, open Connected apps. The overview explains the permission model.

Troubleshooting

  • Codex reports the server as not signed in — run codex mcp login americancloud again. This happens after a revoke, or when a sign-in expires.
  • A tool answers that the app lacks a permission — choose the permission on Connected apps and ask again. Every tool is visible from the start, and a permission change applies to the next request.
  • "This app was disconnected in Connected apps." — someone revoked the app. Wait a few minutes, then sign in again.

Local server

Prerequisites

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

Configure

Add the server with one command:

sh
codex mcp add americancloud \
  --env AMERICANCLOUD_API_TOKEN=your-api-token \
  -- 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_TOKEN = "your-api-token"

An API key from before tokens existed (a client ID and secret) still works: set AMERICANCLOUD_API_CLIENT_ID and AMERICANCLOUD_API_CLIENT_SECRET instead of the token.

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 token with Full access and add the --allow-writes flag after the package name — via the CLI:

sh
codex mcp add americancloud \
  --env AMERICANCLOUD_API_TOKEN=your-api-token \
  -- 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

Register your SSH key first. Before the first VM, ask the agent to register your machine's public key, for example ~/.ssh/id_ed25519.pub, with American Cloud, then to create the VM with that key. Your machine then logs in with the key it already has, and no VM password is needed. The server's own instructions tell the agent to do this; the ask makes sure.

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 — the permission model, service groups, --services scoping, and safety details
Contact us