Login

Cursor

Last updated:

This guide connects Cursor to American Cloud, so Cursor's agent can inspect and manage your infrastructure alongside your code. The hosted server needs one config entry and a sign-in. The local server runs on your machine with an API token.

Hosted server

Connect

Cursor reads MCP servers from a JSON file at either level:

  • Project: .cursor/mcp.json in your repository (applies to that project)
  • Global: ~/.cursor/mcp.json in your home directory (applies everywhere)

Create the file (or open Cursor Settings → MCP → Add new MCP server) and add the hosted server with the client ID that American Cloud registered for Cursor:

json
{
  "mcpServers": {
    "americancloud": {
      "url": "https://mcp.americancloud.com/mcp",
      "auth": {
        "CLIENT_ID": "cursor"
      }
    }
  }
}

The entry holds no secret, so it is safe to commit in a shared repository. Cursor detects the change and asks you to sign in. Your browser opens the American Cloud sign-in page. Sign in, then click Connect on the consent page. If Cursor does not prompt, open Customize in the sidebar and toggle the server on.

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

Cursor starts with full access. Cursor 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 Cursor's next request; you do not need to sign in again.

Verify

Open the agent panel and ask:

What regions can I deploy to on American Cloud?

The agent will request approval to run the American Cloud tool the first time.

Register your SSH key first. Cursor has a shell, so it can also work inside a VM over SSH. 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. See Inside a VM.

Permissions

The app starts with Full access as you, within your own American Cloud role (see the note above). Cursor asks for approval before tool calls unless you've enabled auto-run, and destructive operations are explicitly flagged. We recommend keeping approval on. To limit the app to read-only, or to revoke it, open Connected apps. The overview explains the permission model.

Troubleshooting

  • The server shows an error after a while — open Customize, toggle the server off and on, and sign in 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

Configure

Add the local server to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

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

If you use a project-level .cursor/mcp.json in a shared repository, don't put a real token in it — keep the server config global instead, or add the file to .gitignore.

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.

Cursor detects the change automatically; if the server doesn't appear, toggle it in Cursor Settings → MCP or restart Cursor.

Verify

Open the agent panel and ask:

What regions can I deploy to on American Cloud?

The agent will request approval to run the American Cloud tool the first time.

Enable resource management (optional)

By default the server is read-only. To let the agent create and manage resources, use a token with Full access and add the flag:

json
"args": ["-y", "@americancloud/mcp", "--allow-writes"]

Cursor asks for approval before tool calls unless you've enabled auto-run, and destructive operations are explicitly flagged. We recommend keeping approval on for write-enabled setups.

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