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:
- 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. - Writes
stagd.yamlfrom the compose file, the Dockerfiles and how the app is configured, starting from Stagd’s starter when there is one. - Checks it with
check_config, and fixes what that reports. - 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.
- Pushes a branch, opens a pull request, and starts a preview.
- If it fails, reads why (
explain_failure,get_logs), fixes it, and deploys again, until it’s live. - 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:
- Push, then preview it.
create_previewfor the pull request or branch. For a pull request Stagd may have started one already (When pull requests get previews):list_previewsfinds it. - Wait for it.
wait_for_previewuntil it’s live. If it failed, the answer says why, andget_logswithbuild: trueshows the build’s output. - Look at it.
get_screenshotfor the first page,get_logswitherrors_onlyfor what went wrong while it started, and the preview’s URL for the agent’s own browser, if it has one. - 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:
get_mailwith no message: its answer ends with acursor.- Do the step: invite a user, reset a password, pay an invoice.
wait_for_mailwithafterset to that cursor, and a filter:to,fromorsubject, each matching part of the text, case-insensitively.tomatches To, Cc and Bcc, Bcc being everyone the mail went to that the headers don’t name.get_mailwith the message’s id: its text, itslinks(each once, as they’d open), itsattachments, andunfilled, 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.