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, logs:read
  • a Claude Code or Codex client connected via claude mcp add showly --token=<token>

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",
      "buildCommand": "pnpm build",
      "outputDir": ".next"
    },
    "latestPreview": {
      "deploymentId": "99999999-9999-4999-8999-999999999901",
      "previewUrl": "https://acme-pr-12.preview.showly.app"
    },
    "latestProductionDeploymentId": "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": [
      { "name": "typecheck", "status": "passed" },
      { "name": "lint", "status": "passed" },
      { "name": "smoke", "status": "passed" }
    ],
    "summary": { "passed": 3, "failed": 0 }
  }
}

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

Approval is mandatory; the MCP token cannot publish directly. This call opens the approval request and returns a deep link the user must visit in the Showly web UI to complete step-up MFA and confirm.

// 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.

publish_site and rollback_deployment are not MCP tools — they live in the web UI behind step-up MFA. See the tool reference for the rationale.

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,
    "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