@ao-mcp/local

The on-machine MCP bridge for Automated Operations. It runs as a local stdio MCP server and proxies to the hosted AO MCP endpoint, handling browser sign-in and session/auth for you.

The bridge is a native Go binary. npm is one distribution option, not a runtime dependency. To install it without Node or npm:

# macOS / Linux
curl -fsSL https://mcp.automatedoperations.com/install.sh | sh

# Windows PowerShell
irm https://mcp.automatedoperations.com/install.ps1 | iex

Both installers resolve the signed platform package from the public registry, verify its SHA-512 integrity, and install ao-mcp-local into a user-owned bin directory. Set AO_MCP_INSTALL_DIR during installation to choose a different location. Native installations then check for, verify, and activate AO releases automatically; the next natural MCP process start uses the new binary. There is no consumer update setting or maintenance command.

To remove a native installation without changing any MCP-client configuration:

# macOS / Linux
curl -fsSL https://mcp.automatedoperations.com/install.sh | sh -s -- --uninstall

# Windows PowerShell
& ([scriptblock]::Create((irm https://mcp.automatedoperations.com/install.ps1))) -Uninstall

Use npx -y @ao-mcp/setup remove separately when the AO entries should also be removed from detected MCP clients. Uninstalling the binary never deletes login profiles or unrelated files from a user-selected installation directory.

Entitled organizations may pin managed native deployments through their AO organization policy. The agent accepts only the effective authenticated policy returned by AO Cloud; local users and machine administrators cannot create a pin. AO does not expose version selection to consumer installs.

Offline behavior

The local agent does not cache infrastructure state. When AO Cloud or the network is unavailable, operational tool calls return a retryable ao_unavailable result that explicitly states no cached operational data was returned. Versioned schemas, help, and runbook resources may be cached in future releases; live reads and writes never silently fall back to stale answers.

# one-time sign-in (opens your browser)
npx @ao-mcp/local login

# most users never run it directly — `npx @ao-mcp/setup` wires it into your
# MCP client (Claude Desktop, Cursor, VS Code, …), which spawns it for you

Signing in after your MCP client started

The bridge starts even without a usable sign-in. It then lists only its own tools (authenticate, auth_status, switch_account, sign_out, local_agent_status) and answers every remote request with an auth_required result. Sign in either way:

• ask the agent to call authenticate (opens your browser), or
• run npx @ao-mcp/local login in a terminal — the running bridge notices the new sign-in within a few seconds by itself.

Either way the same MCP session connects: the bridge sends notifications/tools/list_changed and the next tools/list includes the remote tools. No client restart is needed.

Large results (ao://results/…)

A tool result too large to return inline comes back with a text summary plus a resource_link to an ao://results/<id> URI (also in the result's _meta["ao.resultResource"], expiry in _meta["ao.resultExpiresAt"]). Read the complete JSON with resources/read on that URI:

{"jsonrpc":"2.0","id":7,"method":"resources/read","params":{"uri":"ao://results/<id>"}}

The link belongs to the MCP session that produced it: read it from the same session, within 15 minutes. After a sign-in, an account switch or a reconnect the session is new and old links no longer resolve — run the tool again.

Documentation resources (ao://docs/…)

AO's documentation is readable from inside the session, versioned to the AO Cloud release you are connected to: resources/read on ao://docs/<path> returns one page as markdown (template ao://docs/{path} in resources/templates/list). Find pages with the docs_search tool; tools that are not in the default tool list are discovered with find_tools and run with call_tool.

Commands

ao-mcp-local             run the stdio MCP bridge (default; MCP clients spawn this)
ao-mcp-local login       sign in via your browser and store a session token
ao-mcp-local logout      clear the stored token
ao-mcp-local version     print version

Your session token is stored in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) when available, else a permission-restricted file. Set AO_TOKEN to supply a token directly (headless / CI, without refresh or account switching). Hermetic test runners can set AO_TOKEN_FILE to an absolute token.json path; its sibling profiles.json retains the normal refreshable multi-account behavior.

How it's packaged

The binary ships as per-platform optional dependencies (@ao-mcp/local-<platform>-<arch>). npm installs only the one matching your machine; this launcher (bin/cli.js) resolves it and execs it, passing your MCP client's stdio straight through. No postinstall download, no external host — npm carries the bytes. macOS binaries are Developer ID signed and notarized; Windows binaries are Authenticode signed.

Support

Questions, issues, feedback — we'd love to hear from you: [email protected] · https://automatedoperations.com