MCP tools

End-to-end flow

An actual deploy expressed as a sequence of MCP tool calls.

The MCP tool reference lists every tool individually. This page strings them together as a single real deploy so you can see what an agent's session actually looks like.

The flow assumes:

  • a Showly workspace with at least one site
  • an MCP token with scopes project:read, site:read, site:write, preview:create, checks:run, publish:request, publish:confirm, logs:read
  • a Claude Code or Codex client connected to https://mcp.showly.ai/mcp — e.g.

claude mcp add --scope user --transport http showly https://mcp.showly.ai/mcp, then authorize in the browser on the first tool call. See the connect guide for every other host.

Inputs and outputs below are shortened JSON. See the tool reference for full schemas.

1. list_projects — pick the project

Find the project the agent will operate on.

// Input
{}
// Output
{
  "ok": true,
  "data": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "Acme",
      "slug": "acme",
      "createdAt": "2026-05-01T10:00:00.000Z"
    }
  ]
}

The agent picks the relevant projectId and remembers it for the rest of the session.

2. list_sites — find the site

A project can hold several sites, so the agent lists the sites under the chosen projectId to get a concrete siteId to operate on.

// Input
{ "projectId": "22222222-2222-4222-8222-222222222222" }
// Output
{
  "ok": true,
  "data": [
    {
      "id": "33333333-3333-4333-8333-333333333301",
      "name": "Marketing site",
      "slug": "marketing-site",
      "projectId": "22222222-2222-4222-8222-222222222222"
    }
  ]
}

The agent picks the matching siteId and uses it for the rest of the session.

3. get_site_context — read current state

Fetch the manifest + recent activity for the site the user wants to change.

// Input
{ "siteId": "33333333-3333-4333-8333-333333333301" }
// Output
{
  "ok": true,
  "data": {
    "site": {
      "id": "33333333-3333-4333-8333-333333333301",
      "name": "Marketing site"
    },
    "framework": "next",
    "routes": ["/", "/pricing", "/about"],
    "envReferences": ["NEXT_PUBLIC_ANALYTICS_ID"],
    "latestPreviewUrl": "https://acme-pr-12.preview.showly.site",
    "lastProductionDeploymentId": "99999999-9999-4999-8999-999999999902"
  }
}

4. create_change_plan — declare intent

Describe what you want to change. This call does not modify files.

// Input
{
  "siteId": "33333333-3333-4333-8333-333333333301",
  "request": "Change the hero headline to 'Ship without ceremony'"
}
// Output
{
  "ok": true,
  "data": {
    "siteId": "33333333-3333-4333-8333-333333333301",
    "request": "Change the hero headline to 'Ship without ceremony'",
    "plan": [
      {
        "path": "app/page.tsx",
        "action": "edit",
        "summary": "Replace H1 text"
      }
    ],
    "nextStep": "apply_site_patch"
  }
}

The agent typically shows the plan to the user for confirmation before continuing.

5. apply_site_patch — write the change

Stage the actual file edits.

// Input
{
  "siteId": "33333333-3333-4333-8333-333333333301",
  "files": [
    {
      "path": "app/page.tsx",
      "content": "export default function Page() {\n  return <h1>Ship without ceremony</h1>;\n}\n"
    }
  ],
  "message": "Update hero headline"
}
// Output
{
  "ok": true,
  "data": {
    "changesetId": "cs_01HZ8K2QRR3KKTYR4MA8YPNZRC",
    "siteId": "33333333-3333-4333-8333-333333333301",
    "fileCount": 1,
    "ttlSeconds": 3600,
    "nextStep": "create_preview"
  }
}

The changeset is temporary — if you don't materialize it within ttlSeconds, it expires.

6. create_preview — build a preview URL

Materialize the changeset as a preview build.

// Input
{ "changesetId": "cs_01HZ8K2QRR3KKTYR4MA8YPNZRC" }
// Output
{
  "deploymentId": "99999999-9999-4999-8999-99999999990a",
  "previewUrl": "https://acme-pr-13.preview.showly.app",
  "framework": "next",
  "fileCount": 1
}

The build runs in an isolated workspace. Most marketing sites finish under 90 seconds.

7. run_checks — smoke + lint

Run the workspace's check matrix against the preview.

// Input
{ "deploymentId": "99999999-9999-4999-8999-99999999990a" }
// Output
{
  "ok": true,
  "data": {
    "deploymentId": "99999999-9999-4999-8999-99999999990a",
    "checks": [
      { "id": "lint", "status": "passed" },
      { "id": "typecheck", "status": "passed" },
      { "id": "build", "status": "passed" },
      { "id": "audit-gate", "status": "pending" }
    ],
    "summary": "3 passed / 1 pending"
  }
}

If a check fails the agent should surface the failure to the user and loop back to step 4 with a corrected plan.

8. request_publish — open the approval

On Team/Enterprise plans with approval workflows, publishing routes through a human approver — this call opens the request and returns a deep link the reviewer visits to approve or reject. OTP/MFA enrollment is not required. On self-serve plans the agent can publish with the two-step publish_site confirmation.

// Input
{
  "deploymentId": "99999999-9999-4999-8999-99999999990a",
  "message": "Hero headline update — agent-proposed"
}
// Output
{
  "approvalId": "ap_01HZ8K2QRRA0V01Q3Q7H7R7K2P",
  "deploymentId": "99999999-9999-4999-8999-99999999990a",
  "state": "pending",
  "expiresAt": "2026-05-26T11:00:00.000Z",
  "reused": false,
  "webApprovalUrl": "https://showly.ai/app/approvals/ap_01HZ8K2QRRA0V01Q3Q7H7R7K2P"
}

The agent surfaces webApprovalUrl to the user. A reviewer clicks it, reviews the diff, and approves; Showly then promotes the preview artifact to production.

The legacy rollback_deployment verb is not an MCP tool — it lives in the web UI behind step-up MFA. publish_site and rollback_to_version are MCP-callable via a two-step confirmation; see the tool reference for details.

9. get_deployment_logs — confirm

After approval, the production deploy carries the same deploymentId. Pull logs to confirm the build artifact promoted cleanly.

// Input
{
  "deploymentId": "99999999-9999-4999-8999-99999999990a",
  "lineCount": 50
}
// Output
{
  "ok": true,
  "data": {
    "deploymentId": "99999999-9999-4999-8999-99999999990a",
    "lineCount": 50,
    "source": "db",
    "lines": [
      "[build] starting pnpm build",
      "[build] generated 1 page in 14s",
      "[deploy] promoted to production at 2026-05-26T10:05:21Z"
    ]
  }
}

That's the full loop: plan → patch → preview → check → approve → ship → confirm.

What's next