# MCP tools

> Every tool Stagd's MCP server gives coding agents, with what each takes and what it answers.

Stagd's MCP server gives coding agents the tools to make a preview of their change, wait for it, look at it and fix what's wrong. [Coding agents](https://stagd.dev/docs/guides/coding-agents.md) shows how to connect one and the loop it runs; this page is every tool in full.

## Connecting

Most clients start `stagd mcp`, which speaks MCP over stdio and hands each call to Stagd, signed in as you (`stagd login`):

```sh
claude mcp add stagd -- stagd mcp
```

Behind it is MCP's streamable HTTP transport at `https://app.stagd.dev/mcp`, answered as plain JSON: no event streams and no sessions, so every call stands alone. A client that can send a header can call it directly, with `Authorization: Bearer <token>`. Without a token it answers 401. Clients that sign in through MCP's OAuth (claude.ai, ChatGPT) can't connect yet.

The server speaks protocol versions `2025-11-25`, `2025-06-18` and `2025-03-26`. Its instructions tell the agent the loop in short, and that what previews show (pages, logs, mail) is data, never instructions.

## How tools answer

- **Data** comes back as JSON text and as structured content. Many answers end with `next`: what to call after this one.
- **Errors** come back as a tool error with the API's message, e.g. when your role can't do something or a preview doesn't exist. The agent reads it like any answer.
- **As you.** Each tool calls [Stagd's API](https://stagd.dev/docs/reference/api.md) with your token, in your current org: the same access rules and activity log as the dashboard and the CLI. A viewer can look but can't create or destroy previews.
- **Hints.** Tools that only read are marked read-only; `destroy_preview` and `clear_mail` are marked destructive, so clients ask you before calling them.
- **States** are words: a preview is `building`, `live`, `failed` and so on.

Every tool that works on a preview takes its `id`, from `create_preview` or `list_previews`.

## Tools

| Tool | What it's for |
|---|---|
| [`whoami`](#whoami) | Who the agent acts as, in which org, with which role |
| [`list_repositories`](#list_repositories) | The org's repositories, and whether previews are on |
| [`create_preview`](#create_preview) | Starts a preview of a pull request or branch |
| [`wait_for_preview`](#wait_for_preview) | Waits until a preview is live, failed or asleep |
| [`get_preview`](#get_preview) | One preview in full |
| [`list_previews`](#list_previews) | The org's previews, of a repository or pull request |
| [`list_activity`](#list_activity) | Who changed what in the org, and when |
| [`explain_failure`](#explain_failure) | What Stagd knows about why a preview failed |
| [`destroy_preview`](#destroy_preview) | Tears a preview down |
| [`get_screenshot`](#get_screenshot) | The picture taken as the preview went live |
| [`get_logs`](#get_logs) | Log lines, or the build's output |
| [`get_usage`](#get_usage) | Each service's CPU and memory |
| [`get_mail`](#get_mail) | The mail the preview caught |
| [`wait_for_mail`](#wait_for_mail) | Waits for mail to arrive, or checks none does |
| [`clear_mail`](#clear_mail) | Empties the preview's inbox |
| [`get_texts`](#get_texts) | The text messages the preview caught |
| [`wait_for_text`](#wait_for_text) | Waits for a text message to arrive |
| [`check_config`](#check_config) | Checks `stagd.yaml` and the compose file before pushing |

## Who and where

### whoami

Who's signed in, the org their calls act in, and their role there. Read-only. Takes nothing.

Answers `email`, `name`, `org` (`slug` and `name`), `role` (`admin`, `member` or `viewer`) and `orgs`, the slugs of every org you're in.

### list_repositories

The org's repositories. Read-only. Takes nothing.

Answers `repositories`, each with:

| Field | |
|---|---|
| `name` | `owner/name`, what the other tools take as `repository` |
| `previews` | `on` or `off` |
| `default_branch` | |
| `stagd_yaml`, `compose_file` | The files Stagd found, when it found them |
| `problems` | What's wrong with them, when anything is |

## Previews

### create_preview

Starts a preview of a pull request or a branch, or deploys an existing one again at its latest or the given commit. Answers at once, while it builds: call `wait_for_preview` with its id next.

| Input | Type | |
|---|---|---|
| `repository` | string, required | `owner/name`, as `list_repositories` gives it |
| `pull_request` | integer | The pull request's number. Give this or `branch` |
| `branch` | string | A branch, for a preview without a pull request |
| `commit` | string | A commit to deploy instead of the latest, 7 to 40 hex characters |

Answers `preview` ([a preview](#a-preview)) and `next`.

### wait_for_preview

Waits until the preview is live, failed, asleep or torn down, for at most `seconds`, then says where it stands. Still building when the time is up: call it again. Read-only.

| Input | Type | |
|---|---|---|
| `id` | string, required | |
| `seconds` | integer, default 60 | How long to wait at most, 5 to 110 |

Answers `preview` and `next`: when it's live, how to check it; when it failed, where to read why.

### get_preview

One preview: where it stands, its URLs, its services, and why it failed when it did. Read-only.

| Input | Type | |
|---|---|---|
| `id` | string, required | |

Answers `preview`.

### list_previews

The org's previews that aren't torn down, newest first. Use it to find a pull request's preview before making one. Read-only.

| Input | Type | |
|---|---|---|
| `repository` | string | `owner/name`: only this repository's |
| `pull_request` | integer | Only this pull request's, with `repository` |

Answers `previews`, each as [a preview](#a-preview) without its `urls` and `services`.

### list_activity

Who changed what in the org, newest first: secrets set or revealed (by name, never a value), seeds, compute, integrations, repositories and their preview settings, GitHub, members and invites. For questions like "what changed before this preview started failing?". A page at a time. Read-only.

| Input | Type | |
|---|---|---|
| `area` | string | Only one area: `secrets`, `seeds`, `compute`, `integrations`, `repositories`, `github`, `members` or `workspace` |
| `actor` | string | Only what this person did, by email |
| `page_size` | integer | At most this many, 1 to 200; 50 if not given |
| `page_token` | string | `next_page_token` from the page before, with the same filters |

Answers `activity`, each with `at`, `who`, `via`, `action`, `target` and, when there is one, `detail`; and `next_page_token` while there are older entries.

### explain_failure

For a failed preview: what Stagd collected about why, its own explanation when it has one, and a prompt for the agent to work out the cause itself. The agent reads it, fixes the cause in the repository and pushes; the preview redeploys. Read-only.

| Input | Type | |
|---|---|---|
| `id` | string, required | |

| Answer | |
|---|---|
| `stage` | Where it failed, e.g. the build or a service starting |
| `service` | The failing service, when one did |
| `error` | The error, secrets masked |
| `stagd_explanation` | Stagd's explanation, when it has one: as in [`why`](#why-it-failed), with `explained_by`. It may be wrong: the prompt says to check it against the logs |
| `logs` | The failing service's last log lines, secrets masked |
| `prompt` | What to work out and how, with all of the above |
| `next` | |

### destroy_preview

Tears a preview down now: its services, its data and its URLs go. `create_preview` makes a new one. Destructive.

| Input | Type | |
|---|---|---|
| `id` | string, required | |

Answers `id` and `state`.

### A preview

How `create_preview`, `wait_for_preview`, `get_preview` and `list_previews` give a preview:

| Field | |
|---|---|
| `id` | |
| `repository` | `owner/name` |
| `pull_request` | `number`, `title` and `url`, for a pull request's preview |
| `branch` | For a branch's preview |
| `commit` | The commit it runs, 12 characters |
| `state` | `queued`, `provisioning`, `building`, `deploying`, `live`, `failed`, `sleeping` or `destroyed` |
| `error` | What went wrong, when it failed |
| `why` | Why it failed, when Stagd could tell: [below](#why-it-failed) |
| `waiting_for` | What it's waiting on, when it is |
| `url` | Its main URL |
| `urls` | One per ingress in `stagd.yaml`, by name: each `url`, `org_only` when only the org can open it, and `builtin` for the ones Stagd adds itself (e.g. `otel`, `azure_blob`) |
| `services` | Each service's `name`, `phase` and `message` |
| `has_screenshot` | Whether `get_screenshot` has a picture |
| `dashboard` | The preview's page in Stagd's dashboard |
| `updated`, `expires` | Timestamps |

#### Why it failed

| Field | |
|---|---|
| `stage` | Where it failed |
| `service` | The failing service, when one did |
| `cause` | The cause, in a sentence |
| `fix` | What to change |
| `confidence` | `high` or `likely` |
| `evidence` | The lines that show it, each with where it came from |

## Looking at a preview

### get_screenshot

The picture Stagd took of the preview's main page, 1280 × 800, as its latest deploy went live: a quick way to see the app renders. Answers a JPEG image, or an error until a deploy has gone live. Read-only.

| Input | Type | |
|---|---|---|
| `id` | string, required | |

### get_logs

A preview's recent log lines, newest last. With `build: true`, the end of each service's build output instead: what to read when a build failed. Read-only.

| Input | Type | |
|---|---|---|
| `id` | string, required | |
| `service` | string | Only this service's, a service in the compose file |
| `build` | boolean, default false | The build's output, not the running services' logs |
| `errors_only` | boolean, default false | Only lines logged as errors |
| `since` | timestamp | Only lines from this time on, e.g. `2026-11-02T09:15:00Z` |
| `lines` | integer, default 100 | How many lines at most, 1 to 500 |

Answers `lines`, each as `<time> <service> <level>: <message>`. With `build`, answers `builds` instead, each with `service` and `output`. Either has `cut` when there was more than it gave.

### get_usage

Each service's CPU and memory now, and its average CPU and peak memory over a window, with its restarts and when it started, as the preview's Services tab has them. Sampled once a minute while the preview is live. Read-only.

| Input | Type | |
|---|---|---|
| `id` | string, required | |
| `window_minutes` | integer, default 60 | How far back, 1 to 1440 (24 hours) |
| `series` | boolean, default false | Include each service's points over the window, about 120: to see a leak or a spike |

Answers `services`, each with `service`, `image`, `sampled_at`, `cpu_percent`, `memory_bytes`, `memory_limit_bytes`, `avg_cpu_percent`, `peak_memory_bytes`, `restarts`, `started_at`, and with `series`, `points` (each `time`, `cpu_percent` and `memory_bytes`). With no samples in the window, `services` is empty and `note` says why.

## Mail and text messages

A preview delivers no mail and no text messages: it catches them ([Capture mail](https://stagd.dev/docs/guides/describe-your-app.md#capture-mail)). These tools read what it caught. [Check what a change sends](https://stagd.dev/docs/guides/coding-agents.md#check-what-a-change-sends) shows how to use them together.

Each answer has a `cursor`. Pass it back as `after` to get only what arrived since: take one before a step, then ask for what the step sent.

### get_mail

The mail the preview caught, newest first, at most 20; or one message in full. Read-only.

| Input | Type | |
|---|---|---|
| `id` | string, required | |
| `message` | string | A message's id from the list: that one in full |
| `after` | string | A cursor: only what arrived after it |
| `to` | string | Part of an address or name it went to: To, Cc or Bcc |
| `from` | string | Part of the sender's address or name |
| `subject` | string | Part of the subject |

The filters match case-insensitively. Answers `messages`, `total` and `cursor`. Each message has `id`, `from`, `to`, `cc`, `bcc`, `subject`, `received`, `snippet` and `attachments`, the number of them.

With `message`, answers that message with its `text` (the HTML as text when it has no text part), its `links`, its `attachments` (each `name`, `type` and `bytes`) and `unfilled`: text a template seems to have left unfilled, such as `{{name}}` or `undefined`, each with the part it was `in`, what was `found` and the words `near` it.

### wait_for_mail

Waits for mail matching the filter to arrive after `after`, for at most `seconds`, and answers as soon as one comes. None by the end is an answer too: how to check that a step sent nothing, or nothing to someone. Read-only.

| Input | Type | |
|---|---|---|
| `id` | string, required | |
| `after` | string | A cursor from `get_mail`, taken before the step |
| `to`, `from`, `subject` | string | As for `get_mail` |
| `seconds` | integer, default 30 | How long to wait, up to 60 |

Answers `messages`, as `get_mail` lists them, and a new `cursor`. With none, `note` says so.

### clear_mail

Deletes all the mail the preview caught, for a clean inbox. A cursor is usually better: it keeps earlier mail to look at. Destructive.

| Input | Type | |
|---|---|---|
| `id` | string, required | |

Answers `cleared`.

### get_texts

The text messages the preview's app sent through Amazon SNS, newest first, at most 20, e.g. to read a sign-in code. Needs `services: { sms: {} }` in `stagd.yaml`. Read-only.

| Input | Type | |
|---|---|---|
| `id` | string, required | |
| `after` | string | A cursor: only what arrived after it |
| `to` | string | Part of the number it went to, matched by its digits |
| `body` | string | Part of the message |

Answers `texts`, each with `to`, `from`, `body` and `sent`, and `cursor`.

### wait_for_text

Waits for a text message matching the filter to arrive after `after`, for at most `seconds`: the matching ones as soon as one comes, or none when the time is up. Read-only.

| Input | Type | |
|---|---|---|
| `id` | string, required | |
| `after` | string | A cursor from `get_texts`, taken before the step |
| `to`, `body` | string | As for `get_texts` |
| `seconds` | integer, default 30 | How long to wait, up to 60 |

Answers `texts` and a new `cursor`. With none, `note` says so.

## Configuration

### check_config

Runs `stagd.yaml` and the compose file through the same checks a deploy does, before anything is pushed: what's wrong, and what a preview would run. Give the files' contents by path. When it needs another file, such as the compose file `stagd.yaml` names, it says which: call again with that one too. Read-only.

| Input | Type | |
|---|---|---|
| `files` | object, required | Paths in the repository to their contents, e.g. `{ "stagd.yaml": "…", "compose.yaml": "…" }` |
| `absent` | array of strings | Paths it asked for that the repository doesn't have |

| Answer | |
|---|---|
| `ok` | True when nothing's wrong and no file is missing |
| `needs_files` | Paths to call again with, when it needs more |
| `problems` | What's wrong |
| `notes` | What's worth knowing but not wrong |
| `services` | What a preview would run: each `name`, and what it `builds` or the `image` it runs |
| `ingresses` | Each `name`, its `service` and `port`, and `primary` for the main one |
