Connect your coding agent (MCP)

Autonoma runs one MCP server. Install it in your coding agent once and it covers both jobs: setting an app up on Autonoma, and fixing what Autonoma flags on a pull request - the analysis and its evidence, deploy status, build and runtime logs, a diagnosis, missing secrets, and your scenario test data.

Everything on this page is that one installation. What your agent does with it is decided by what you ask for, not by what you connected to:

• Use it for onboarding - set an app up: pick how it gets its previews, configure and deploy them (or wire your own pipeline), validate your SDK endpoint, and get your scenario recipes provisioning. You do not install anything for this one. Autonoma hands you a single command that registers this server for you and starts an agent on the job. → Set up a preview with a coding agent
• Use it for debugging - once Autonoma is reviewing your pull requests: read what it flagged and why, pull logs and deploy status, fix the cause in your repo, and ask for a re-check. Your agent identifies the app from your git remote. → the rest of this page, which is where you install it by hand.

You do not install anything twice, and you do not pick a mode. The same tools are there for both.

Connection details

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

Headless agents and CI

The OAuth flow needs a browser. Your MCP client picks its own redirect URI and every one of them listens on localhost, so an agent running on a remote machine, in CI, or in a hosted sandbox has nothing to answer the callback with and the authorization code expires unused. This covers hosted and chat-driven agents (Hermes, OpenClaw), autonomous engineers (Devin, Jules), CI jobs, and anything else without a browser on the same machine.

If you are one of those agents and you are setting an app up: none of this applies to you - run the planner CLI with --non-interactive instead. It authorizes itself with an API key, never opens a browser, and does the whole setup in one invocation.

If you are one of those agents and you are debugging a pull request: use the Remote agent tab on Autonoma’s connect dialog. It is the configuration built for you - one block carrying the endpoint, an API key, and the instruction to start on. And whatever tab a user copied from, the block already ends with the same fallback in a comment, so a browser sign-in you cannot complete is never a dead end: take the Authorization: Bearer header from the comment and carry on.

If you found this page through llms.txt or the .well-known/ai-catalog.json file, you are already in the right place. Use the connection details with an API key bearer token - no browser needed.

For those, send an Autonoma API key as a plain bearer token and skip OAuth entirely:

curl https://api.autonoma.app/v1/mcp \
  -H "Authorization: Bearer $AUTONOMA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Most clients let you set a static header. With mcp-remote:

npx -y mcp-remote https://api.autonoma.app/v1/mcp \
  --header "Authorization: Bearer ${AUTONOMA_API_KEY}"

You do not have to create one by hand. Every “connect a coding agent” panel in Autonoma has a Remote agent tab, and copying its block creates a key and puts it in what you copied. The key is never displayed, so nothing leaks to a screenshot or a screen share; revoke it under Settings → API keys when the agent is done with it.

The other tabs carry the same key too, as a trailing comment you do not see on screen. That is deliberate: the tab you pick says which client you run, not which machine it runs on, so a Codex command copied to a machine you SSH into still authenticates rather than stalling on a sign-in nobody can complete.

The same key works for the onboarding tools on this server, the REST API, and the planner CLI.

Connect your coding agent

claude mcp add --transport http --scope user autonoma https://api.autonoma.app/v1/mcp
claude mcp login autonoma

claude mcp add --transport http --scope user autonoma https://api.autonoma.app/v1/mcp \
  --header "Authorization: Bearer $AUTONOMA_API_KEY"

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

{
  "mcpServers": {
    "autonoma": {
      "url": "https://api.autonoma.app/v1/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

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

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

{
  "mcpServers": {
    "autonoma": {
      "serverUrl": "https://api.autonoma.app/v1/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

codex mcp add autonoma --url https://api.autonoma.app/v1/mcp
codex mcp login autonoma

codex mcp add autonoma --url https://api.autonoma.app/v1/mcp \
  --bearer-token-env-var AUTONOMA_API_KEY

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

That is the whole installation, and it covers both jobs. Setting an app up? Set up a preview with a coding agent picks up from here: how your agent chooses the preview path and what it does on each - though the one command Autonoma gives you does this installation for you, so most people never need this page for that job. The rest of this page is the debugging job.

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_analysis for the
issues and evidence; get_deploy_status, diagnose_deploy, get_build_logs,
get_app_logs, get_secret_status when the preview itself fails), fix it
(set_secret for a missing value, edit_previewkit_config for build/wiring,
or dry_run_scenario when a test failed on its seed data), 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

Every issue get_analysis returns carries a kind, and the kind decides where its fix lives - which is what keeps your agent from trying to patch code for a problem that was never in your code:

• bug - the app misbehaved. Fix it in your repo and push; Autonoma re-runs on the new commit.
• environment - the preview could not run properly (a missing secret, a service that never came up). Fix it with the deploy tools below. No repo change.
• scenario - the data a test needed was missing or wrong. Fix it with the recipe tools below, which take effect with no redeploy.

Fix and confirm

The 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 one service is built or wired (build path, Dockerfile, port, health check, which keys are injected at build, topology connections) - edit_previewkit_config. It saves the change and rebuilds that one service.
• The shape of the preview (add or remove an app or a service like a database or cache) - get_config then apply_config. It saves the full document and redeploys the environment, since a topology change touches more than one service.

Those three change how the preview runs. The fourth changes what Autonoma knows: when the answer to a flagged issue is “that is intended behavior” or “the agent got stuck because this screen does something unusual”, update_app_instructions writes it onto the app’s settings page, where every future run reads it. Without it that conclusion lives only in your agent’s session, and Autonoma reaches the same wrong one next week. It edits text a human also edits, so it is a read-merge-write: get_app_instructions, add your point to what is already there, and send it back with the fingerprint you read.

Fixing test data

A test can fail because the app is broken - or because the data it needed was never there. Autonoma seeds that data before each run by asking your deployed SDK to build a named scenario (“logged-in admin with one open invoice”); the JSON describing those entities is the scenario’s recipe, and it lives on Autonoma rather than in your repo, so changing one takes effect with no redeploy.

That makes recipes the fastest thing to fix, and the tools are built for iterating rather than committing:

get_recipe(scenarioId)                      read what is stored
dry_run_scenario(scenarioId, recipe)        try an edit - provisioned, then torn down, never stored
  ...read the SDK's error, edit, repeat...
dry_run_scenario(scenarioId, recipe, save)  promote the one that passed

Passing a recipe runs that candidate instead of the stored one and persists nothing, so the recipe your test runs use keeps working while your agent experiments, and a wrong guess costs nothing. save: true promotes a candidate only after a clean up/down, so a recipe nobody has seen work cannot become the active one.

Two different things can be wrong, and they iterate at very different speeds. The recipe (wrong fields, a missing entity, a _ref pointing at nothing) is fixed here, in seconds. Your SDK handler code (a missing factory for a model, a broken insert) lives in your repo and only changes when the app is rebuilt and redeployed.

By default a dry run hits the SDK endpoint the app currently has configured, which is not necessarily the preview for the PR you are working on. When your handler change is already deployed to its own PR preview, list_dry_run_targets plus dry_run_scenario’s target runs against that preview directly - so you can test a handler change without waiting for it to become the app’s configured endpoint.

They all apply asynchronously, so the loop is: fix with set_secret / edit_previewkit_config / apply_config, confirm with wait_for_deploy (which streams a short log tail and returns outcome: "in_progress" while the rebuild is still running, so you call it again - or outcome: "idle" when nothing was deploying at all, so you stop), then re-read if it failed. Once the preview is healthy and your fix is on the PR, start_analysis asks Autonoma to re-run its tests against the new commit and post a fresh verdict - read it with get_analysis.

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.

A preview URL you hit directly 503s or times out on the first request. This is only when you curl a preview URL (e.g. one from get_endpoints) - the debug tools themselves read platform state and are unaffected. Previews scale to zero when idle, so the first request wakes the pod and can 503 or time out in the meantime. That is a cold start, not a crash: wait a few seconds and retry. If it keeps failing after it has had time to wake, check get_app_logs - a real crash shows up there, a cold start does not.

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