STAGING
Skills

Skills quickstart

Install @showly/mcp-server, authorize from your terminal, and open a real site URL fast.

Showly's headline promise is "deploy a site from your agent." This page is the end-to-end recipe. Install plus your first site build 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 how the headless sign-in works.

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

2. 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, your host opens a browser sign-in and the human clicks Allow.

If the machine has no browser — a server, a container, CI, a remote shell — or you are not sitting at it, run the headless sign-in instead:

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

It prints exactly this and then waits:

Showly needs one approval from you. If you do not have a Showly
account yet, you will be asked to create one first.

  1. Open this page:   https://showly.ai/oauth/device
  2. Enter this code:  K7QM-3XPD

Same machine as your browser? Use the direct link instead:
  https://showly.ai/oauth/device?user_code=K7QM-3XPD

The page will show the code K7QM-3XPD before you approve.
Approve ONLY if it matches the code above. If it shows a
different code, someone else is trying to get in - refuse it.

Waiting for approval until 14:58 local. Once you approve, this
command picks it up on its own - no need to come back and tell it.

Open the page on any device — your phone works — and sign in with the email you registered with. The consent screen shows the code, the requested scopes and Allow / Deny.

Check the code on the page against the code in your terminal, tick the box that says they match, and click Allow. That check is the point: the name a client shows on that screen is one it chose for itself, so the code is the only part you can verify. Back in your terminal the command returns within a few seconds and read tools work immediately.

3. Make a one-line change and review it

Ask the agent:

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

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 and returns the protected site 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 protected site URL and its one-time password inline. Open it to review the change before publishing it.

4. 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, review the exact version, and complete any plan-required teammate approval. OTP/MFA enrollment is not required. Once publishing starts, the agent calls get_preview_status with waitForChange: true and it long-polls (default 30 seconds, up to a 60-second ceiling). When the production deployment flips to ready, the response includes productionUrl, which the agent returns as the published site URL.

If you enable Advanced deployment controls for a site, the same tools use the explicit Preview and Live language and preserve the existing Live release while you review a newer Preview.

What leaves your machine

  • Your agent runs locally (Claude Code, Codex, ...).
  • Reading site context returns only data allowed by the MCP token's scopes.
  • Your changed files are sent to Showly when apply_site_patch or another

upload tool is called.

  • Showly builds those files into a protected unpublished version and records the applicable

actions in the workspace audit history.

See Architecture for the complete delivery flow.

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 — publish_site uses a short-lived two-step

confirmation after the user says yes. If the workspace has a second-reviewer approval policy enabled, use request_publish and its webApprovalUrl instead. Neither flow requires OTP/MFA enrollment.

Next steps