Connect your coding agent (MCP)

Autonoma runs an MCP server so your coding agent can read a pull request's live debugging data - deploy status, build and runtime logs, a diagnosis, and which secrets are missing - and fix a broken preview from inside your repo, the same way it fixes anything else.

When Autonoma flags a problem on your PR, the fix usually lives in your codebase. Instead of copying logs out of a dashboard, point your agent at the MCP server and let it pull exactly what it needs.

Connection details

Everything below is the same server, just configured per client. When a client asks for these values, use:

Setting	Value
URL	`https://api.autonoma.app/v1/mcp/debug`
Transport	Streamable HTTP
Authentication	OAuth - your client opens a browser to sign in to Autonoma and authorize; no API key or token to paste

Connect your coding agent

Add the server with the Claude Code CLI:

claude mcp add --transport http autonoma https://api.autonoma.app/v1/mcp/debug

The first time your agent uses a tool, Claude Code opens a browser to sign in and authorize. Run claude mcp list to confirm it connected.

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

{
  "mcpServers": {
    "autonoma": {
      "url": "https://api.autonoma.app/v1/mcp/debug"
    }
  }
}

Reload Cursor, then complete the browser sign-in when prompted from Settings → MCP.

For GitHub Copilot's agent mode, add the server to .vscode/mcp.json:

{
  "servers": {
    "autonoma": {
      "type": "http",
      "url": "https://api.autonoma.app/v1/mcp/debug"
    }
  }
}

Start the server from the mcp.json editor lens, then authorize in the browser when prompted.

Add the server to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "autonoma": {
      "serverUrl": "https://api.autonoma.app/v1/mcp/debug"
    }
  }
}

Refresh MCP servers from Cascade's settings, then complete the browser sign-in.

Codex reaches remote servers through the mcp-remote bridge, which also handles the OAuth browser flow. Add it to ~/.codex/config.toml:

[mcp_servers.autonoma]
command = "npx"
args = ["-y", "mcp-remote", "https://api.autonoma.app/v1/mcp/debug"]

Any MCP client that speaks Streamable HTTP can connect with the connection details above. For a client that only supports STDIO servers, bridge to the remote server with mcp-remote:

{
  "mcpServers": {
    "autonoma": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.autonoma.app/v1/mcp/debug"]
    }
  }
}

mcp-remote opens the browser for the OAuth sign-in and proxies the connection over STDIO.

Point your agent at it

The server gives your agent the tools; a short line in your agent's instructions tells it when to reach for them. The fastest way is to invoke the setup_autonoma prompt - your agent adds the section to AGENTS.md (or CLAUDE.md) for you. Or add it by hand:

After you push a PR, Autonoma reviews its preview deploy. If it flagged a
problem, use the Autonoma MCP tools to find the cause (get_deploy_status,
diagnose_deploy, get_build_logs, get_app_logs, get_secret_status), fix it
(set_secret for a missing value, edit_previewkit_config for build/wiring),
and confirm with wait_for_deploy - before merging.

Because that file is read every session, your agent pauses to check the preview without you having to ask.

The server also ships two things any client can use without a setup file: a debug_broken_preview prompt (a guided fix flow for a given PR) and a readable debugging guide resource. And its connect-time instructions already tell your agent what Autonoma is and the recommended order to use the tools - so even an agent that has never heard of Autonoma knows where to start.

What your agent can do

Every tool takes your repo (owner/repo); the per-PR tools also take the PR number. Your organization is inferred from the repo (which you must belong to), so every call is automatically scoped to it. You don't need to hand your agent the repo name - it infers it from the repository's git remote, or calls list_apps to let you pick. You do not need GitHub access; the repo name is just how Autonoma identifies your app.

Read the evidence

Tool	Input	Returns
`list_apps`	none	The repos you can debug across your organizations - use when the repo isn't obvious
`get_deploy_status`	repo, PR	Per-service deploy status, endpoints, and the latest build outcome
`diagnose_deploy`	repo, PR	The raw evidence in one call - status, service/addon states, latest build outcome, a rule-based failure classification, the config's env-key surface, and error-shaped logs - plus deterministic findings categorized as a missing env var, setup problem, or platform error. It is not an AI summary; you reason over the signals
`get_build_logs`	repo, PR	Build-log lines, from the `tail` (newest) or `head` (start of the build), optionally for one service
`get_app_logs`	repo, PR	Runtime (stdout/stderr) log lines, from the `tail` (a crash) or `head` (startup)
`get_endpoints`	repo, PR	The preview URL, a suggested SDK URL, and one entry per service (internal services like a database report `url: null` with a reason)
`get_secret_status`	repo	The full env-var surface per app: topology connections (with template values) and secret-backed vars (declared build secrets + runtime secrets), with masked length and a fingerprint only, plus which declared build secrets are missing

Fix and confirm

Tool	Input	Returns
`set_secret`	repo, PR, app, key, value?	Sets (or, without a value, removes) a secret env var's value and applies it - rebuilds if it's a build secret, restarts otherwise. Values are stored encrypted and never returned
`edit_previewkit_config`	repo, PR, app, fields	Changes structural config for one service (path, Dockerfile, port, health check, build-secret keys, connections) and rebuilds it. Only the fields you pass change; never sets a secret value
`wait_for_deploy`	repo, PR, app?	Blocks (up to ~45s, then re-callable) until the deploy settles (ready or failed) and returns the outcome plus the last few log lines, so you can see progress and keep debugging after a `set_secret` or `edit_previewkit_config` rebuild

The two write tools split cleanly by what they change, so your agent never has to guess which to use:

A secret value (an API key, token, or password) - set_secret. It stores the value and applies the minimal action itself: a rebuild if the key is a declared build secret (baked into the image at build), a restart otherwise. You do not tell it which; it reads your config.
How the app is built or wired (build path, Dockerfile, port, health check, which keys are injected at build, topology connections) - edit_previewkit_config. It saves a new config revision and rebuilds the service.

Both apply asynchronously, so the loop is: fix with set_secret / edit_previewkit_config, confirm with wait_for_deploy (which streams a short log tail and tells you settled: false if the rebuild is still running so you can call it again), then re-read if it failed.

Troubleshooting

The tools do not show up. Confirm the client connected (e.g. claude mcp list) and that you completed the browser sign-in. A client that only supports STDIO needs the mcp-remote bridge shown under Other clients.

A tool says no live preview environment was found. Autonoma tears the preview down after testing, so the live-surface tools (get_deploy_status, get_endpoints, wait_for_deploy) return unavailable once it is gone. This does not mean there is nothing to inspect: get_build_logs and get_app_logs still work for a post-mortem (see below). Open the PR and let a new preview deploy if you need the live surface again.

Logs from a torn-down or old preview. Build and app logs are retained for about 30 days and stay readable after the preview is torn down - so you can debug why a past deploy failed without redeploying. If the logs come back empty, the preview may never have deployed, or its logs have aged out; re-run the preview to get fresh ones.

Which pull requests can I use? Any PR in a repo you have connected to Autonoma, in an organization you belong to.