MCP server

What it is#

MCP (Model Context Protocol) is the standard way to give an AI assistant tools. The Deploys.app MCP server is a bridge between an assistant — Claude Desktop, Claude Code, or any MCP client — and the Deploys.app API.

It exposes every user-facing action through a search + execute pair, so the ~90 API actions never flood the model’s context: the assistant searches for the action it needs, reads its input schema, then runs it on your behalf. It is the same backend the console and CLI use, so it can only do what your identity is allowed to do.

There are two ways to connect. Most people want the first.

Connect with OAuth (recommended)#

No download, no secret to manage — you log in through the browser and the assistant acts as your account.

Claude Code:

# add it to the current project (default scope)
claude mcp add --transport http deploys https://mcp.deploys.app/

# …or make it available in every project on your machine
claude mcp add --transport http --scope user deploys https://mcp.deploys.app/

The first time the assistant uses it, a browser window opens for you to sign in to Deploys.app. After that the connection is remembered. Use claude mcp list to check which servers are configured in the current scope.

Claude Desktop: Settings → Connectors → Add custom connector → set the URL to https://mcp.deploys.app/ and complete the sign-in.

Confirm it’s connected:

claude mcp list        # deploys ✓ connected

Connect with a service account (local)#

For CI, headless, or offline use — or when you want the assistant to act as a service account rather than as you — run the server locally and authenticate with a key.

Download a prebuilt binary (no Go toolchain needed):

curl -fsSL https://dl.deploys.app/mcp/latest/deploys-mcp-darwin-arm64 -o deploys-mcp
chmod +x deploys-mcp

Register it with Claude Code, passing the service-account credentials as env:

claude mcp add deploys \
  -e DEPLOYS_SA_EMAIL='ci@acme.serviceaccount.deploys.app' \
  -e DEPLOYS_SA_SECRET='…the key…' \
  -- /absolute/path/to/deploys-mcp

Add --scope user here too to make it available in every project rather than just the current one.

Or in the Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "deploys": {
      "command": "/absolute/path/to/deploys-mcp",
      "env": {
        "DEPLOYS_SA_EMAIL": "ci@acme.serviceaccount.deploys.app",
        "DEPLOYS_SA_SECRET": "…the key…"
      }
    }
  }
}

DEPLOYS_API_KEY="<email>:<secret>" works as a single-variable alternative, and DEPLOYS_ENDPOINT overrides the API base URL (mainly for staging).

How it works#

The server exposes exactly two tools:

You don’t call these yourself — you just talk to the assistant. It searches for the action, reads the schema, fills in the parameters, and executes. Actions that change or delete things are flagged destructive so the assistant treats them with care and confirms before running.

Examples#

Ask in natural language; the assistant maps it to an action:

A typical exchange:

You:    show deployments in acme
Claude: (searches → deployment.list → executes)
        6 deployments, all healthy — web services, a couple of cron
        jobs, and a background worker. Want details on any one?

Recipes#

Diagnose a failing deploy#

When a deployment.deploy comes back with a status that isn’t Success, the assistant can close the loop itself — observe, then read the cause:

You:    I deployed web to acme but it's not coming up. What's wrong?
Claude: (deployment.status → sees ready:0, waitingReason CrashLoopBackOff)
        All 3 pods are crash-looping (CrashLoopBackOff, 7 restarts).
        (deployment.logs with previous:true → reads the crashed container)
        The previous container panicked on startup:
          panic: missing env DATABASE_URL
        Add DATABASE_URL to the deployment's env and redeploy.

The two actions behind this:

• deployment.status returns pod counts plus each non-ready pod’s raw failure reason (CrashLoopBackOff, ImagePullBackOff, OOMKilled, exit code) in one call.
• deployment.logs returns a bounded snapshot of recent live container output; with previous: true it reads the last crashed container, which is where a CrashLoopBackOff’s panic or stack trace lives.
• deployment.logsHistory returns the durable 30-day captured history over a since / until window — oldest-first, or newest-first with reverse: true, paged with the opaque cursor. Reach for it when the pod is already gone and live logs have nothing left to read (available only where the location has a log bucket configured). It reuses the same deployment.logs permission.

All three are read-only and return once (no streaming). See Monitoring & debugging for the contract and the deployment.logs permission split.

For triaging recurring crashes, error.list and error.get pull up the deployment’s grouped, deduplicated error issues — each with an occurrence count and a representative stack — so the assistant can read what’s been throwing without scrolling raw logs, and error.create lets it report an error directly. See application error detection.

Ship a throwaway preview#

To iterate on a static site or a container without touching production, spin an ephemeral preview that cleans itself up. deployment.deploy with a ttl (seconds) creates a deployment that auto-deletes when the window expires:

You:    Build a preview of the new landing page.
Claude: (deploys_publish_site, environment "preview" → site://…@<sha>)
        (deployment.deploy type:Static, site:…, ttl:7200 → landing-preview)
        (deployment.get → url + releaseUrl)
        Preview is live:  https://landing-preview-….deploys.app   (rolling — always the latest build)
        This exact build: https://landing-preview-<sha8>-….deploys.app   (immutable; expires in 2h)
You:    Looks good — keep it up while I show the team.
Claude: (deployment.extendTTL ttl:7200 → re-stamps the window to now + 2h)

The pieces:

• deployment.deploy with ttl turns any deploy into a self-deleting preview; omit ttl for a normal deployment. Publish with a non-production environment so the release is served X-Robots-Tag: noindex.
• deployment.get returns url (rolling, always the current build) and — for static deployments — releaseUrl (immutable, pinned to that exact build), plus expiresAt so the assistant can see (and reap) what’s near expiry.
• deployment.extendTTL re-stamps the window (expires_at = now + ttl) without redeploying — the keep-alive for a long session.
• deployment.delete drops it early.

Container previews get a rolling url only; the immutable releaseUrl is static-only (containers have no content-addressed release). Preview URLs are public and unlisted. See static sites → preview deployments.

Permissions & safety#

• It acts as an identity you control. Over OAuth it’s your account; locally it’s the service account whose key you provided. Either way it’s the same authentication and IAM roles as the console and CLI — the assistant can never exceed what that identity is permitted to do.
• Scope the service account. For the local mode, grant the service account only the roles it needs, the same as you would for CI.
• Destructive actions are labelled. Each action advertises a read-only or destructive hint, so deletes, pauses, and rollbacks are gated rather than run blindly.

See also#

• The deploys CLI — the same API from the terminal
• Service accounts — credentials for the local mode
• API overview — the underlying actions