# 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](https://stagd.dev/docs/quickstart.md)). 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:

```sh
stagd mcp install
```

Or add it yourself:

```sh tab="Claude Code"
claude mcp add stagd -- stagd mcp
```

```json tab="Cursor"
{ "mcpServers": { "stagd": { "command": "stagd", "args": ["mcp"] } } }
```

```toml tab="Codex"
[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](https://stagd.dev/docs/reference/mcp.md).

| 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](https://stagd.dev/docs/guides/describe-your-app.md#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](https://stagd.dev/docs/guides/describe-your-app.md#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:

```sh
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](https://stagd.dev/docs/reference/cli.md), and the [API reference](https://stagd.dev/docs/reference/api.md) for everything else.
