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_preview_status
  • Plan — create_change_plan
  • Apply — apply_site_patch
  • Build — create_preview, run_checks
  • Ship — request_publish; direct production publish and rollback return a browser step-up link
  • Inspect — get_deployment_logs
  • Onboard — list_templates, create_site_from_template

Each tool's schema makes its blast radius explicit: request_publish requires a deploymentId for a ready preview. Direct publish_site / rollback_deployment are not exposed via MCP at all — they don't appear in tools/list. Instead, request_publish returns a webApprovalUrl deep link; the user opens it to complete approval and step-up MFA in the web UI.

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