MCP tools

MCP overview

Why Showly exposes capabilities as MCP tools rather than a raw REST API.

Showly exposes its capabilities to coding agents through the Model Context Protocol. This page explains the _why_ — for the _what_, jump to the tool reference.

Why MCP

A bare REST API would force every agent to learn a custom auth flow, custom request shapes, and custom error semantics. MCP solves all three:

  • Typed tools. Each capability is a tool with a JSON Schema'd input and output. The agent's host (Claude Code, Codex) auto-renders the tool list for the user.
  • Scoped tokens. A Showly MCP token is bound to a workspace, optionally a project, the authorizing user when created through OAuth/device flow, and a set of tool scopes. The token never grants more than the agent needs.
  • First-class audit. Every tool call records the client id, the action, the parameters (with secret redaction), and the outcome.

What the agent sees

Once the user has installed the Showly MCP client, the agent sees tools grouped by capability:

  • Read — list_projects, list_sites, get_site_context, get_site_files, get_preview_status
  • Plan — create_change_plan
  • Apply — apply_site_patch
  • Build — create_preview, run_checks, retry_deployment
  • Ship — request_publish (opens a human-approval flow on plans with approval workflows); publish_site and rollback_to_version act directly via a two-step in-conversation confirmation token
  • Inspect — get_deployment_logs, diagnose_deployment, list_deployments, list_site_versions, diff_site_versions
  • Onboard — list_templates, create_site_from_template, create_site_from_html, create_trial_site, claim_trial_site
  • Transfer — request_upload_url, request_download_url (signed URLs for large files that shouldn't ride through the model's context)
  • Clean up — delete_preview, delete_site

Each tool's schema makes its blast radius explicit: request_publish requires a deploymentId for a ready preview. The one verb kept entirely off MCP is the legacy rollback_deployment — it lives in the web UI behind step-up MFA. Production-affecting MCP tools (publish_site, rollback_to_version, delete_site) never act on the first call: they return a short-lived confirmation token that must be echoed back in a second call.

How tokens are scoped

A workspace admin issues an MCP token from Workspace settings → MCP clients. Each token has:

  • a client name (so audit logs read like "Claude Code (alice@acme)")
  • an optional project scope (which project this client can touch)
  • a scope set — flat scope strings (no tiers, no implication ladder), defaulting to project:read, site:read, preview:read; see the full list in Scopes and tokens
  • a TTL (default 90 days, max 365 days)

Tokens can be revoked instantly from the same panel.

Boundaries

The MCP surface intentionally does not expose:

  • Direct database access.
  • Production environment variable values.
  • Cross-tenant reads of any kind.
  • Workspace billing or user-management mutations.

If your agent workflow needs something not on this list, file an issue — the answer is almost always "add a tool with a tighter scope," not "open the API."

Next