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

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 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):

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 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 Who the agent acts as, in which org, with which role
list_repositories The org’s repositories, and whether previews are on
create_preview Starts a preview of a pull request or branch
wait_for_preview Waits until a preview is live, failed or asleep
get_preview One preview in full
list_previews The org’s previews, of a repository or pull request
list_activity Who changed what in the org, and when
explain_failure What Stagd knows about why a preview failed
destroy_preview Tears a preview down
get_screenshot The picture taken as the preview went live
get_logs Log lines, or the build’s output
get_usage Each service’s CPU and memory
get_mail The mail the preview caught
wait_for_mail Waits for mail to arrive, or checks none does
clear_mail Empties the preview’s inbox
get_texts The text messages the preview caught
wait_for_text Waits for a text message to arrive
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) 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 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, 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
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). These tools read what it caught. 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

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