MCP

Parity serves its API as MCP tools. Each tool is one API call made with the caller's token, so a tool can do exactly what the token can. Give an agent a sandbox token and its tools reach that sandbox only.

Connect

Remote, over Streamable HTTP, with the token as a bearer header:

{
  "mcpServers": {
    "parity": {
      "type": "http",
      "url": "https://api.parity.ninja/mcp",
      "headers": { "Authorization": "Bearer ${PARITY_TOKEN}" }
    }
  }
}

Local, over stdio, with the parity CLI:

{
  "mcpServers": {
    "parity": {
      "command": "parity",
      "args": ["mcp"],
      "env": { "PARITY_API": "https://api.parity.ninja", "PARITY_TOKEN": "pst_…" }
    }
  }
}

The stdio server can also read and write local files: proof_add takes a path, and proof_export and inbox_attachment take save_to.

Behaviour

• No call waits more than about 50 seconds. A tool that is still waiting returns what it has with a next hint: call sandbox_status with wait, or job_status, again.
• Errors are the API's problem details, with code and retryable (see Errors).
• With a sandbox token, sandbox defaults to the token's own sandbox, and sandbox_create and sandbox_list are not offered.

The server sends these instructions to the agent on connect:

Parity sandboxes: a full copy of an app (services, database, mail inbox, auth) for one task.
Use the sandbox's own public URL (sandbox_status: services[].public_urls) to drive the app like a user.
Typical loop: sandbox_status until "ready"; create users (auth_user_create, or the app's own sign-up);
inbox_wait for verification mail and use its links/codes; job_run to trigger work; sandbox_logs and
sandbox_exec to debug; proof_add for evidence (screenshots, test output); proof_export at the end.
No call waits more than about 50 seconds: a tool that is still waiting returns what it has with a
"next" hint (call sandbox_status with wait, or job_status, again).
With a project token, a call that names no sandbox acts on $PARITY_SANDBOX, else the sandbox named
after the current git branch, as the parity CLI does; sandbox_destroy always names its sandbox.
Errors are RFC 9457 problem details {"type", "title", "status", "detail", "code", "retryable"}:
not_ready (retry shortly), dependency_failed (a job failed; log_tail says why), wrong_sandbox (this
token is for another sandbox), rate_limited (slow down; retry_after says when).
Mail links carry internal: true when they point at this sandbox; prefer those. For "the next mail
after my action", take inbox_list's cursor first, act, then inbox_wait with after set to it.

Tools

auth_signin

Mint a one-time sign-in link for an auth user. Opening it in a browser runs the app's own OIDC login, so the app sets its own session. Returns {url, expires_at}; the link works once, for 15 minutes.

auth_user_create

Create a user in the sandbox's auth resource (its OIDC provider), with orgs and roles. Returns {id, email, password, orgs}; the password is shown once. Only for apps that declare an auth resource (no_auth otherwise: use the app's own sign-up). Then auth_signin gives a one-time sign-in link.

auth_user_delete

Delete an auth user.

auth_user_list

List the users of the sandbox's auth resource, with their orgs and roles, in creation order: {users, total_size, next_page_token}. q keeps emails containing it. While next_page_token is set, more are on the next page (page_token).

auth_user_update

Change an auth user's email, password or memberships. orgs replaces every membership. Returns the user.

environment_status

Read a project's environments (staging, production, customer deployments: whatever its manifest declares): whether each is frozen or pinned by a rollback, its current rollout and status, and the block jobs waiting for a person with their prompts. With environment, that one in full. Builds move between environments through releases: see release_status. Agents can't promote, approve or reject: tell the user what is waiting and that they decide it (parity approve <step> --env <environment>, or the console).

inbox_attachment

Download one attachment of a message, by its part or file name (inbox_read lists them), as an embedded resource with its content type; with parity mcp, save_to writes it to a local file. Without part, lists the attachments.

inbox_list

List the mail the sandbox received (every address at the sandbox's domains lands here), newest first: id, to, from, subject, received_at, snippet, and the links, codes and attachments extracted from each. Filter by recipient, subject text or regexp, since, or after (a cursor); q searches every message, not just one page. The answer's cursor is the newest message: pass it as inbox_wait's after to get the next mail once you have acted. inbox_read gives one message's text. While next_page_token is set, older mail is on the next page (page_token).

inbox_read

Read one message: its text, the extracted links and codes (one-time codes, verification links) and its attachments (part, name, content_type, size; inbox_attachment downloads one). The HTML part only with html: true.

inbox_wait

Wait for a message (to an address, with subject text or a subject regexp) and return it with its text, links, codes and attachments. Without after, it returns the newest match, even one that came before the call, so call it right after the action that sends mail. With after (a message id, or the cursor inbox_list gave before you acted), it returns the first match after that message, so old mail never answers. expect_none asserts that no match arrives in the window instead (signed evidence that something was not sent). Waits at most 50 seconds, sending progress; on timeout call again with the after the answer gives. Prefer links with internal: true.

job_run

Run one of the manifest's jobs now (a seed, a migration, a cron's task), from the app version the sandbox runs. Waits up to about 50 seconds, sending progress, and returns {job, name, status, log_tail, duration_seconds}; a failure is dependency_failed with the log tail. A job still running returns status running with next: call job_status with its name.

job_status

The state of one job run (from job_run's name), waiting up to about 50 seconds for it to finish, with progress.

proof_add

Attach evidence to the sandbox's proof bundle: a screenshot, a test log, an API response. It lands in files/ of the export, with your note and its content type. Give text as content, bytes as content_base64 (or, with parity mcp, a local path); several files at once in files. Returns {name, size, sha256, content_type}, or {files: [...]} for several.

proof_export

Export the proof bundle as a zip: proof.json (sandbox, commit, image digests, times, users created, your verdict), calls.jsonl (every API call this token made), inbox/.eml, egress.json, logs/.log and files/*. Fill claim, result and summary for the reviewer. Returns the list of entries and the zip as an embedded resource (or writes it to save_to with parity mcp).

release_status

Read a project's releases, newest first: each is one build moving through the manifest's release steps (promote into environments, block for approval, wait, run a job, group). Shows where each release is and what it waits for: a block's prompt and approvals, a promote's environments (held: frozen or pinned by a rollback), a wait's end. With number, that release in full. Agents can't approve, reject or skip: tell the user what waits and that they decide it (parity approve <step>, or the console).

sandbox_create

Create a sandbox for one task: the app's services, database, mail and auth in their own namespace. Needs a project token. The sandbox's createdBy is the person the token was minted for. Returns the sandbox (id, status, domain, services[].public_urls) and its token at once: give that sandbox token to the agent doing the task. With wait (the default) it then waits up to about 50 seconds for ready, sending progress; if the sandbox is still starting it returns with next: call sandbox_status with wait until status is ready. A failed setup job is dependency_failed with the log tail. Pass idempotency_key to make a retry return the same sandbox and token.

sandbox_destroy

Destroy the sandbox and all its data. Its token stops working. Exported proofs and calls.jsonl are kept by Parity (GET /v0/proofs), but export the proof first: nothing can be exported after.

sandbox_egress

Every outbound call the sandbox made: DNS queries for outside names and connections to outside hosts (HTTP Host, TLS server name), blocked or let through, with the service that tried and a count. A blocked host needs adding to the manifest's externals. sandbox_status lists the blocked hosts too.

sandbox_exec

Run a command in a running service or resource container (such as psql in db, or a script in web) and return {exit_code, stdout, stderr}. Output is capped at 1 MiB per stream. The sandbox's generated values are replaced with [redacted] where they appear verbatim, as a courtesy: exec can read the env, so treat its output as secret-bearing.

sandbox_extend

Push the sandbox's expiry back by a duration, such as 1h, up to the manifest's max_ttl. Returns the sandbox with the new expires_at.

sandbox_list

List the sandboxes this token can see, with status and expiry, a page at a time: while next_page_token is set, call again with it as page_token.

sandbox_logs

Read logs as text: one service, resource or job, or the whole sandbox when neither is given. Several containers are prefixed with [pod/container]. Use since to see only what an action just caused.

sandbox_status

Get a sandbox: status (starting, ready, failed, expiring), expires_at, services with public_urls and health, resources, lifecycle jobs and conditions. With wait, it waits up to about 50 seconds for ready (or failed), sending progress; call it again while status is starting. The app's URL is services[].public_urls.

sandbox_sync

Roll the sandbox onto a changed parity.yaml (manifest: its text), new prebuilt images (images: {service: ref}), or both; deploy jobs such as migrations run again. Waits up to about 50 seconds for ready unless wait is false. To run changed source code, use parity up from the working directory: it uploads the tree and Parity rebuilds the services that only have build:.