Skills

Skills quickstart

Install @showly/mcp-server, authorize, get a real preview URL in under two minutes.

Showly's headline promise is "deploy a site from your agent." This page is the end-to-end recipe. Install plus your first preview takes roughly 90 seconds on a fresh laptop; the production publish path adds a manual in-browser approval step (covered in section 5).

1. Install into your agent

The canonical install path is the @showly/mcp-server package (bin showly-mcp). For Claude Code:

npx @showly/mcp-server install --to claude-code

For Codex:

npx @showly/mcp-server install --to codex

These write a single MCP-server entry (transport + URL) into ~/.claude.json or ~/.codex/config.toml. No token is written: the agent discovers Showly's OAuth authorization server from the endpoint itself and runs a browser sign-in on first use. The package also ships a typed manifest.json listing every Showly tool, its required scopes, and whether MCP-origin calls are allowed.

See Installing the Skill for how the browser sign-in works and the no-browser fallback.

If your agent isn't supported by the installer, run npx @showly/mcp-server install --to stdout and paste the snippet manually.

3. Authorize from a real conversation

Open Claude Code (or your Codex equivalent) and ask anything that touches a Showly tool. For example:

"List my Showly sites."

The agent will call list_sites. Because there is no Showly token on this machine yet, the agent prints something like:

Please open https://showly.ai/oauth/device?user_code=ABCD-EFGH
to authorize Claude Code.

Open that URL. You'll be asked to sign in (use the same email you registered with) and then shown the consent screen: agent name, requested scopes, Allow / Deny buttons.

Click Allow. Back in your terminal, the agent picks up the freshly-minted token within a few seconds. Read tools work immediately.

4. Make a one-line change and preview it

Ask the agent:

"On the northstar site, change the H1 to 'Hello from W7' and give me a preview."

The agent chains four tool calls:

  1. create_change_plan — turns your sentence into a structured plan.
  2. apply_site_patch — stages the edit as a _changeset_ (scope site:write).
  3. create_preview — builds the changeset into a real artifact, uploads it to

the preview bucket, and returns a preview URL (scope preview:create).

  1. run_checks — reads the lint / typecheck / build status on that deployment

(scope checks:run).

Total wall-clock time: ~5 seconds for tiny edits, ~30 seconds for a real Next.js app. The agent shows you the preview URL inline. Click it — that's your change live on *.preview.showly.site. (Customer previews are served on the showly.site domain; the control plane — mcp.showly.ai, api.showly.ai — is on showly.ai.)

5. Going to production

Showly does not let agents directly publish to production. The agent calls request_publish (scope publish:request), which creates a pending approval and returns a webApprovalUrl deep link instead of shipping anything:

{
  "ok": true,
  "data": {
    "approvalId": "appr_xxx",
    "deploymentId": "dep_xxx",
    "state": "pending",
    "expiresAt": "2026-05-31T10:00:00.000Z",
    "reused": false,
    "webApprovalUrl": "https://showly.ai/app/deployments/dep_xxx/publish"
  }
}

The agent hands you the webApprovalUrl. Open it, complete the step-up MFA challenge, click Approve, and the deploy starts. Once it does, the agent can call get_preview_status with waitForChange: true and it'll long-poll (default 30 seconds, up to a 60-second ceiling) — when the deployment flips to ready, the agent picks up the transition and resumes the conversation.

What's running where

  • Your agent runs locally (Claude Code, Codex, ...).
  • Showly MCP server runs on mcp.showly.ai. It speaks the

Streamable HTTP MCP transport and authenticates every request with the OAuth-issued bearer token.

  • Showly API runs on api.showly.ai. It owns the database, RLS, builds,

audit, and deploy adapters.

  • Your code never leaves your machine until apply_site_patch — at that

point the changeset is uploaded to a Showly-owned storage bucket and built there.

See Architecture for the full diagram.

Common errors

  • missing_bearer_token — your agent didn't include `Authorization: Bearer

mcp_…. Re-run npx @showly/mcp-server install` and restart the agent.

  • invalid_token — your token is expired, revoked, or not an MCP token.

Invoke a Showly tool again to trigger a fresh browser sign-in; the agent obtains a new token automatically. (To force it, revoke the old row under Admin → Agent first.)

  • insufficient_scope — the requested tool needs a scope you didn't grant

during the consent flow. Revoke + re-authorize, this time approving the scope.

  • Production publish — agents can't publish directly. request_publish

returns a webApprovalUrl; complete the step-up MFA and approval in the web UI.

Next steps