Set up a preview with a coding agent (MCP)

Setting an app up is one of the two jobs the Autonoma MCP does: connect your coding agent and it sets your previews up for you - works out how your app should get them, does the setup either way, asks you for any secrets it needs, and iterates until previews are landing - while you watch, read-only, in the Autonoma UI.

This is the default way to set Autonoma up, and the alternative to answering a questionnaire about your stack and then filling in a config form. Your agent already knows your repo - its build, its services, its env, how it deploys - so it can do the setup faster than you can describe it, and answer questions about your own schema that you would otherwise be guessing at. You stay in control: the UI shows every step live and hands control back the moment you take over.

The agent picks the path too

An app gets its previews one of two ways, and they need completely different work:

• Autonoma-hosted - Autonoma builds and hosts a preview per pull request. The agent writes the build, services and env config, and deploys through these tools.
• Your own pipeline - your project already builds previews. Autonoma deploys nothing; the agent connects those previews so Autonoma knows when one is live.

On your own pipeline there are two ways Autonoma learns a preview is live, and the agent is told which applies rather than assuming. If your project is on Vercel, Autonoma’s Marketplace integration already reports every deployment, so the agent connects the project instead of writing anything - and connecting is also what makes a deployment-protected preview reachable at all. Every other host is a signed webhook the agent wires into your pipeline.

Being on Vercel does not commit you to reusing your own previews. Plenty of Vercel projects pick Autonoma-hosted previews deliberately, because an Autonoma-hosted preview gets its own database and a test run cannot leave rows in whatever your Vercel previews point at. If the agent picks Autonoma-hosted for a Vercel project, the Vercel tools stand down and it follows the hosted playbook.

Autonoma-hosted is the default, and the agent picks it on its own. Reusing your own previews is always your decision - the agent cannot choose it for you, and the server refuses it without your answer. What changes is whether the agent raises the option.

If your project is on Vercel, our integration makes it a genuine choice, so the agent will ask. It fits when your previews are entirely Vercel’s: the backend in the same deployable unit, and either data cleanly scoped to a tenant that can be deleted whole or a branchable database (Neon, Supabase, PlanetScale) giving each preview its own. A backend deployed elsewhere, or global tables a teardown would leak into, means Autonoma-hosted - which plenty of Vercel projects choose deliberately.

Anywhere else the agent will not bring it up, and will set up Autonoma-hosted previews. You can still ask for your own - it will explain both sides first. That is the same routing the questionnaire applies when you set up by hand. A deploy workflow in your repo is not evidence either way: a YAML file does not say whether those previews work, which database they point at, or whether you want test data written into it.

The two mistakes are not symmetrical: a needless Autonoma-hosted preview costs an environment we build for you anyway, while wrongly reusing your own previews writes test data into a real shared database. The trade-off is spelled out here.

Start from the Autonoma UI

You do not install or configure anything for this. Autonoma’s connect screen hands you one command - the planner CLI, carrying your app’s id - and that command does the wiring:

AUTONOMA_SHARED_SECRET=... AUTONOMA_DISTINCT_ID=... AUTONOMA_API_TOKEN=... AUTONOMA_GENERATION_ID=... AUTONOMA_APPLICATION_ID=... npx @autonoma-ai/planner@latest

Copy it, open a terminal in your project folder, and paste. From there it registers this MCP server with your coding agent, authorizes it, mints a pairing code, and starts a fresh agent session on the job - then keeps going once the preview is up, through your test suite, the SDK integration and a scenario dry run. There is no second command and no pairing code for you to read off a screen.

Registering the server before starting the agent is the whole reason this is a command rather than something you paste into a session you already have open: an agent loads its MCP servers at startup, so it can never pick up one it registered itself. A CLI process is not an agent session, so it can do both in order.

That one screen is the fork: the command is the default, and the questionnaire is the Answer a few questions instead link along the bottom.

The app id in the command is how the agent knows which app to set up. You never hand it a repo name, and it can only ever touch an app in an organization you belong to.

Hosted and headless agents

The OAuth sign-in needs a browser on the same machine. If you are a hosted agent, an autonomous engineer, or a CI job, run the same command with --non-interactive:

AUTONOMA_API_TOKEN=... AUTONOMA_GENERATION_ID=... AUTONOMA_APPLICATION_ID=... \
  npx @autonoma-ai/planner@latest --non-interactive \
  --coding-agent claude --frontend apps/web --backend apps/api

It never opens a browser - the coding agent it starts is authorized with the run’s API key as a bearer header instead - never blocks on a question, and reports each step as it starts and finishes so the process that launched it can follow along. Anything that would have been asked has to arrive as a flag; where guessing wrong would spend the run on the wrong thing it refuses with a clear error instead, and where the choice is cheap - which of two installed coding agents to use - it picks one and says which. See running unattended for the full flag list.

This is the whole of the headless path. It replaces registering the MCP by hand and pairing yourself, and it does more than that ever did - the same one invocation carries on through the test suite, the SDK integration and the dry run.

Wiring it up by hand instead

If you manage your own MCP servers and would rather drive the tools directly, that still works. Register the server with the connection details and an API key, then ask the user for a pairing code from the Autonoma UI:

1. Call pair(code) - returns the applicationId, the linked repository, the preview path playbook, and the current config.
2. Follow the loop - select_preview_path → get_config / apply_config → trigger_deploy → get_session_status (poll until ready) → verify the app works → go_live → validate_sdk → fix recipes with dry_run_scenario / update_recipe.
3. If request_env fires - tell the user which env vars Autonoma needs and why. The user enters values in the Autonoma UI; you poll get_session_status until they land. You never see the values.

Pairing codes are single-use and expire after 15 minutes, so ask for the code that is on the user’s screen now rather than reusing one from earlier in the conversation.

The agent will also stop and wait for you again if the app needs secret values it does not have - request_env asks for key names only, you type the values into the Autonoma UI, and the agent polls get_session_status until they land. Secret values never pass through a tool call.

How the agent sets Autonoma up

Once paired, the agent works a loop, and the Autonoma UI streams every step:

1. Pair - pair(code) claims your app for the agent and returns which repo it is linked to, how it gets its previews, and the playbook for that path. Your agent is told to pair first, before it analyzes your repo: pairing is low-risk (it makes no code changes and deploys nothing) and it is what flips the UI into “connected” and starts streaming activity, so you get immediate feedback instead of staring at an idle screen while the agent reads code.
2. Check the repo, then pick the path - pair returns the repository the app is linked to, and the agent is told to confirm its working directory matches before it reads a single file. An agent run from the wrong checkout would otherwise analyze an unrelated codebase and act on evidence that has nothing to do with your app. If the app has not chosen yet, the agent calls select_preview_path with autonoma-hosted - the default - and a one-line reason you can see. Reusing your own previews takes an explicit ask from you.

Everything after that depends on the path.

If Autonoma hosts the preview

3. Read and edit - get_config / apply_config read and save the full preview environment config document. A save is validated; an invalid document returns the errors to fix. apply_config also takes an optional branch to set which branch the base preview deploys from (setting it here does not deploy).

   The agent does this work on an autonoma-integration branch cut from your default branch, not on the default branch itself. Getting a preview to build usually takes real commits - a Dockerfile that was never built from a repo root, a missing build arg - and none of that belongs on your trunk unproven. It pushes that branch, points the base preview at it, and iterates there; the work reaches your default branch the way anything else does, as a pull request you review. Pointing the base preview at a branch does not change which branch Autonoma treats as your main one.

   Your app has one preview config, and every environment deploys from it - the base environment and each open pull request alike. Saving one is a change to the whole app, not to the pull request you happen to be looking at. Per-environment configuration is a known limitation we may lift later; today there is no way to give one pull request a different config, and prNumber on the config tools chooses only which environment gets redeployed with the saved document. Secret values work the same way: set_secret stores them per app and service, not per pull request.

4. Deploy - trigger_deploy deploys the configured deploy branch as the preview.

5. Watch and iterate - get_session_status returns the deploy status, the preview URL, diagnostics, and a recentLogs tail (build logs on failure, app logs when ready). The agent polls it, reads the diagnostics and logs if the preview fails, fixes the config, and deploys again - until it comes up.

6. Verify beyond the health check - a ready preview can still be broken (the health-check page renders while API routes crash). The agent is instructed to exercise the main flow against the preview URL and then read the app’s runtime logs in recentLogs - not just declare done because the status says ready.

If your own pipeline builds it, on Vercel

There is nothing to write here. Autonoma’s Vercel Marketplace integration reports every deployment already, so the work is connecting the project.

Being on Vercel is not itself a reason to take this path. It is still your own pipeline, so where the test data lands is the question that decides it - and a Vercel preview points at your project’s own database by default, commonly the same one production uses, unless you have wired per-preview database branching. The agent is told to check that your schema is tenant-scoped before continuing here, and to go back and pick Autonoma-hosted if it is not.

3. Read the connection state - get_vercel_setup returns whether your organization has the Autonoma Vercel integration installed, which projects can be linked, which one is linked already, and that project’s ready deployments. It also returns a nextStep naming the exact call to make, so the agent does not have to infer the sequence.

4. Link the project - link_vercel_project connects the Vercel project to the app. The agent picks the candidate whose matchesRepository is true - the project building the same GitHub repo - and asks you if none matches, rather than guessing from a name. Linking is the step everything else depends on: it applies the deployment-protection bypass, without which Autonoma cannot reach a protected preview, and adopts the AUTONOMA_SHARED_SECRET Vercel injected into your project so your SDK handler’s signature matches.

5. Get a deployment to point at - the agent is told to make one rather than reuse an old one. The next thing it does is add your Autonoma SDK handler on its own branch, and Vercel builds a preview for every branch pushed, so it pushes that branch and uses its preview. That deployment is the only one that actually contains the handler, so onboarding never has to be re-pointed later, and a fresh build already carries the injected AUTONOMA_SHARED_SECRET, so nothing needs rebuilding.

   To reuse an existing deployment instead, the agent asks you which - the same question this screen’s dropdown asks, over the same list - and then create_vercel_deployment rebuilds your choice so it picks up the shared secret. It will not take a production deployment on its own initiative.

6. Wait, then commit it - get_vercel_deployment_status polls until ready, telling a still-building deployment apart from a terminal ERROR or CANCELED so a failed build ends the wait instead of extending it. select_vercel_deployment then makes it the preview Autonoma tests against, which advances onboarding on its own - there is no signal to wait for and no confirm step.

If your organization has not installed the integration at all, the agent cannot do it for you: it hands you the install link from get_vercel_setup and polls until you have.

If your own pipeline builds it, anywhere else

There is no config to write, nothing to deploy and no build logs to read - apply_config, trigger_deploy, request_env and get_target_logs all refuse on this path rather than doing something surprising. The work is wiring one signed call:

3. Read the contract - get_signal_setup returns the endpoint, your applicationId, the shared secret, every body field, and a starter GitHub Actions workflow. The agent is told to treat that workflow as a template: it hangs off GitHub’s deployment_status, which many pipelines never emit, so the agent reads how your project actually deploys and makes the same call from whatever step knows a preview is live.
4. Wire it in - conventionally on a branch and a pull request, so you review it rather than the agent pushing to main. It puts the shared secret in your pipeline’s secret store rather than committing it.
5. Prove it fired - get_signal_status is the only confirmation the wiring works, so the agent triggers a real deploy and polls. It is told a hand-written curl proves nothing about your pipeline. It also watches prReviewsConfirmed: until a signal carries a prNumber, your app records preview URLs but no pull request is ever reviewed.
6. Confirm - confirm_signal_setup advances onboarding, once a signal has actually landed.

Then, whichever path you took

7. Go live - go_live takes the app from a verified preview to live, the last two steps of onboarding. Until it runs, Autonoma reviews no pull requests and holds back the comments it would have posted (they are re-run for your open pull requests when you finish, so nothing is lost). It does not wait on the SDK endpoint or the recipes below - those are separate work that continues afterwards. Called too early it refuses and names the step your app is actually on and the call that moves it forward, so you can see where it stalled rather than reading a state-machine error. On your own pipeline it goes live on trust: Autonoma cannot prove your signal carries a prNumber until a real pull request deploys, so open one afterwards and check get_signal_status reports prReviewsConfirmed.

8. Validate your SDK endpoint - once the preview is up, Autonoma needs the environment factory you implement. It is conventionally mounted at /api/autonoma, and any other route works as long as the agent records it: sdk_path on the app that serves the handler names the mount path, and an app that declares none is assumed to use the convention. The agent sets it with apply_config before validating, and validate_sdk writes back whatever path actually answered - so a handler on a different route is a one-line config change, not a reason to move your code. You will usually write it on its own pull request (conventionally titled feat: autonoma-sdk), and each pull request gets its own preview. list_dry_run_targets lists them - your main preview plus every open PR - and flags the one Autonoma detected as the SDK pull request. validate_sdk then points at that target, calls your handler’s discover, and stores the schema it returns - on an Autonoma-hosted preview and on a Vercel deployment alike. (The one target it cannot validate is a preview from your own non-Vercel pipeline: that needs the signing secret your pipeline signs with, and no tool here accepts a secret value, so the agent hands that step back to you in the UI.) If it fails, the error is your handler’s own, and get_target_logs reads that specific preview’s build or runtime logs for the stack trace behind it. (get_session_status only ever reports your main preview, so it will not show you a pull request’s preview.)

9. Fix the test-data recipes - a scenario is a named app state a test depends on (e.g. “logged-in admin with one open invoice”), and its recipe is the JSON your deployed Autonoma SDK follows to create those entities in the app’s own database. Before onboarding finishes a recipe often does not work yet. The agent lists scenarios with list_scenarios, reads one with get_recipe, and tests an edit end-to-end with dry_run_scenario (which calls your SDK up to create the entities, then down to remove them). Passing the edited recipe to dry_run_scenario runs it without storing it, so the agent can loop on the real SDK error without ever leaving a half-finished recipe in place; it promotes the one that passes with save: true, or saves directly with update_recipe.

   There are two different things that can be wrong, and they iterate differently. A recipe JSON problem (a wrong field, an unresolved {{variable}}) is stored on Autonoma, so update_recipe -> dry_run_scenario takes effect immediately with no redeploy. A problem in your SDK handler code (the factory that turns the recipe into database rows) lives in your repo and only changes when the app is rebuilt: push the fix to the deploy branch (get_config / pair return which branch that is), redeploy - trigger_deploy for a PreviewKit preview, or wait for your own deployment to finish - and only then dry-run again, so you are not testing stale code. If that fix is already deployed to its own PR preview, list_dry_run_targets plus dry_run_scenario’s target points the run straight at it instead, with no redeploy of the app’s own preview. Fastest of all is to iterate the SDK handler against a local server and database first and confirm the rows land, then push a recipe you already know works.

   Previews scale to zero when idle, so the first dry_run_scenario against a cold environment can return a 503 while it wakes. dry_run_scenario waits through that warm-up automatically (a bounded retry), so the first run may just take a little longer - a slow first attempt is the environment starting, not a broken recipe.

While the agent holds the config, the Autonoma UI is read-only and shows what it is doing in real time. You can press Take over at any point to reclaim the config and continue by hand; the agent stands down immediately. If the agent goes idle, control returns to you automatically.

The same split carries through the rest of setup. Once the preview is up the work moves into your terminal - the test suite, the SDK integration and the scenario dry run all happen there - so Finish setup in Autonoma stops offering you those steps and says so, with a live tally of what the platform has confirmed for itself: artifacts that landed, an SDK endpoint that answered, scenarios that provisioned. Take over there hands you the manual steps instead. Your run keeps going in the terminal either way, so stop it there too if you meant to take the work back.

The tool-call list is an audit log: every tool in the table below shows up here as the agent uses it, so you can see exactly what it changed.

The server’s connect-time instructions already tell your agent what Autonoma is and the order to use these tools, so even an agent that has never seen Autonoma knows where to start. Any client can also reach that guidance without a setup file: invoke the configure_preview prompt (a guided flow that pairs with your code and runs the loop), or the connect_my_deploys prompt (the same flow scoped to the your-own-pipeline path - wiring the signed signal and proving it lands), or read the onboarding guide resource (autonoma://onboarding-guide) on demand - useful when a long session has pushed the connect-time instructions out of the agent’s context. Each path also has its own readable playbook resource - autonoma://autonoma-hosted-playbook, autonoma://own-pipeline-playbook, and autonoma://vercel-playbook - so an agent that paired into one path can re-read just that one without hunting through chat history.

Secrets stay yours

When your app needs a secret value the agent does not have - an API key, a database URL, a token - it calls request_env with only the key names. That surfaces a prompt in the Autonoma UI where you enter the values. The values go straight from your browser to Autonoma, encrypted; the agent never sees them and there is no tool that accepts a secret value.

The agent tells you why it needs each key, and you can skip any of them - an empty key is reported back as unavailable so the agent adapts rather than stalling.

The agent should always ask you first whether to set env from your .env (you paste it into the UI) or to configure it yourself - so you decide, every time, what Autonoma stores.

Take as long as you need. While a request is pending the agent keeps polling get_session_status, so it picks the values up on its own once you submit them - you do not have to go back to the agent and tell it you are done (though you can, and it will check).

What your agent can do

Some tools apply to only one path; called on the other they return an error naming the tool to use instead, rather than failing quietly.

Troubleshooting

The tools do not show up. Confirm the client connected (e.g. claude mcp list) and that you completed the browser sign-in.

The pairing code does not work. Codes are single-use and short-lived. Reopen Configure with coding agent in the UI to mint a fresh one.

The UI went read-only and I want to edit by hand. Press Take over - the agent stands down and the form becomes editable again.