Early access is open. Stagd is free during the beta. Sign up
Guides

Coding agents

Give Claude Code, Cursor, Codex and other agents a running copy of each change, and tools to check it with.

A coding agent writes code well but can’t see it run: its sandbox has no database with real data, no other services, no mail and no sign-in. With Stagd, every change the agent pushes gets a preview, the whole app running at its own URL, and the agent can open it, read its logs and mail, and fix what’s wrong before anyone reviews the pull request.

Agents reach Stagd through its MCP server, or through the CLI when they can run commands. Either way they act as you, with your access and no more.

Connect an agent

Install the CLI and sign in once (Quickstart). Then add stagd mcp to your agent as an MCP server. It runs on your machine and hands each call to Stagd, signed in as you.

For Claude Code and Cursor, one command does it, for every project:

stagd mcp install

Or add it yourself:

claude mcp add stagd -- stagd mcp
{ "mcpServers": { "stagd": { "command": "stagd", "args": ["mcp"] } } }
[mcp_servers.stagd]
command = "stagd"
args = ["mcp"]

For Cursor, the JSON goes in .cursor/mcp.json in the repository, or ~/.cursor/mcp.json for every project. For Codex, the TOML goes in ~/.codex/config.toml. Other MCP clients take the same command: stagd mcp, over stdio.

The tools live in Stagd, not in the CLI: new ones show up without updating it. Clients that connect over the internet rather than starting a command (claude.ai, ChatGPT) need MCP’s sign-in, which Stagd doesn’t have yet.

Set up a repository

Stagd’s MCP server has a setup prompt that takes a repository from nothing to its first live preview. In Claude Code, run it in the repository’s checkout:

/mcp__stagd__setup

In other agents, pick the setup prompt, or ask the agent to set up Stagd for this repository. The agent then:

  1. Checks what your org has set up (onboarding_status). It points you at the steps only an admin can do in the browser (GitHub, repositories, compute, secrets) and says who the admins are.
  2. Writes stagd.yaml from the compose file, the Dockerfiles and how the app is configured, starting from Stagd’s starter when there is one.
  3. Checks it with check_config, and fixes what that reports.
  4. Names the secrets the app uses that have no value, and tells you where to set them. It never asks for a value, and never writes one to a file.
  5. Pushes a branch, opens a pull request, and starts a preview.
  6. If it fails, reads why (explain_failure, get_logs), fixes it, and deploys again, until it’s live.
  7. Ends with the preview’s URL and a screenshot.

The same steps are on Home in the dashboard, and in your terminal with stagd setup.

The tools

Each one in full, with what it takes and answers: MCP tools.

Tool What it’s for
whoami Who the agent acts as, in which org, with which role
onboarding_status The org’s steps to its first live preview, as Home shows them: what’s done, what’s next, and whose step it is
list_repositories The repositories your org can preview, whether previews are on, the secrets each app uses, and a starter stagd.yaml
create_preview A preview of a pull request or branch, or the same one again at a new commit. Answers at once with its id and URLs
wait_for_preview Waits until the preview is live, failed or asleep, then says where it stands and why it failed. Call it again for a slow build
get_preview, list_previews One preview, or the previews of a repository or pull request
explain_failure For a failed preview: the error, the failing service’s last log lines, Stagd’s explanation and a prompt to work out the cause
destroy_preview Tears a preview down. Marked destructive, so the agent asks you first
get_screenshot The picture Stagd took as the preview went live
get_logs A service’s recent log lines, errors only if asked, since a time. With build: true, the end of the build’s output
get_usage Each service’s CPU and memory now, its average CPU and peak memory over a window (window_minutes), restarts and when it started. With series: true, the points too, e.g. to see a leak
get_mail The mail the preview caught, or one message in full with its links, attachments and any template text left unfilled
wait_for_mail Waits for a message to arrive, or checks that none does
clear_mail Empties the preview’s inbox
get_texts, wait_for_text The same for text messages, with services: { sms: {} }
check_config Runs stagd.yaml and the compose file through a deploy’s checks before they’re pushed

The loop

What an agent usually does with a change:

  1. Push, then preview it. create_preview for the pull request or branch. For a pull request Stagd may have started one already (When pull requests get previews): list_previews finds it.
  2. Wait for it. wait_for_preview until it’s live. If it failed, the answer says why, and get_logs with build: true shows the build’s output.
  3. Look at it. get_screenshot for the first page, get_logs with errors_only for what went wrong while it started, and the preview’s URL for the agent’s own browser, if it has one.
  4. Fix and push again. The preview moves to the new commit. Its database and volumes stay, so the agent doesn’t start over.

Before changing stagd.yaml itself, the agent runs check_config with the files, so the change works the first time.

Check what a change sends

Mail and text messages are where a change is hardest to check by hand: who got what, with which link. In a preview nothing is delivered, everything is caught (Capture mail), so an agent can trigger each notification and read it.

The pattern is a cursor. Take it before the step, then ask only for what arrived after it:

  1. get_mail with no message: its answer ends with a cursor.
  2. Do the step: invite a user, reset a password, pay an invoice.
  3. wait_for_mail with after set to that cursor, and a filter: to, from or subject, each matching part of the text, case-insensitively. to matches To, Cc and Bcc, Bcc being everyone the mail went to that the headers don’t name.
  4. get_mail with the message’s id: its text, its links (each once, as they’d open), its attachments, and unfilled, the text a template seems to have left unfilled ({{name}}, ${total}, undefined, null, NaN, [object Object], Invalid Date) with the words around it.

wait_for_mail answers as soon as a match arrives, or with none after seconds (up to 60). None is an answer too: wait after the cursor with to set to someone who shouldn’t hear about it, and an empty list shows they didn’t. Each answer has a new cursor for the next step.

Text messages work the same: get_texts for the cursor, wait_for_text with after, to (a number, matched by its digits, so +47 912 34 567 finds +4791234567) or body.

Scripts and CI jobs do the same with the CLI:

after=$(stagd preview mail <id> --cursor)
# ...the step...
stagd preview mail <id> --wait --after "$after" --to bob@example.com
stagd preview mail <id> --none --after "$after" --to kari@ --timeout 10s

--wait prints the first matching message and exits non-zero if none arrives. --none exits non-zero if one does.

Safety

  • The agent is you. It has your role in the org: whatever you may do in Stagd, it may do, and nothing more. Destroying a preview is marked destructive, so clients ask before they do it.
  • No secrets. Nothing an agent gets back holds a secret’s value: logs hide them, and there’s no tool for secrets.
  • What a preview shows is data. Pages, logs and mail come from the app and can hold text written to steer an agent. The tools hand them back as data; tell your agent to treat them that way, never as instructions.
  • Nothing real happens. Mail and text messages are caught, never sent, and the preview has its own database, so clicking Delete or running a migration harms nothing outside it.

Without MCP

An agent that can run commands can use the CLI directly. --json gives every command’s answer as JSON. See the CLI reference, and the API reference for everything else.

For language models and agents: this page as Markdown, or every page through llms.txt.