STAGING
Skills

Installing the Showly Skill

Adding the official Showly Skill to Claude Code or Codex.

The Showly Skill wraps the MCP server with intent-triggered prompts and a publish-loop-aware refusal model. This page walks through installing it on Claude Code, Codex, and any other MCP-aware agent.

How authorization works

You do not paste a token. Showly's MCP server is a remote HTTP server at https://mcp.showly.ai, and it uses the standard MCP authorization handshake (OAuth 2.1 + PKCE). The first time your agent calls a Showly tool:

  1. The agent connects, gets a 401, and discovers Showly's authorization server automatically.
  2. It opens a browser tab to showly.ai where you sign in and approve the requested scopes.
  3. Showly issues a short, scoped token directly to the agent. You never see or copy it.

So the installer's only job is to register the server URL with your agent. The sign-in happens in your browser on first use.

Prerequisites

  • A Showly workspace and at least one site connected.
  • Permission to approve agent access. The approval step requires a role with at least site:write (owner, admin, developer, or member). Approving from a lower-privileged account will mint a token narrowed to whatever scopes you actually hold.

Claude Code

The canonical installer is the @showly/mcp-server package (bin showly-mcp). Run it with the claude-code target:

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

This writes the Showly MCP server block into your Claude Code config. No token, no separate login command. The next time you invoke a Showly tool, the agent runs the browser sign-in described above.

Test the connection from inside Claude Code:

Showly, list my sites.

The first call opens a browser tab to approve access; after you approve, you should see your sites listed, sourced from mcp__showly__list_sites.

Codex

Use the same installer with the codex target. It writes the Showly server into your ~/.codex/config.toml for you:

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

Restart Codex to pick up the new server, then invoke a Showly tool to trigger the browser sign-in.

Any other MCP host

To inspect the config the installer would write without applying it, target stdout:

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

Copy the printed MCP server block into your host's config. Any MCP client that supports the standard authorization flow (WWW-Authenticate discovery → browser consent) connects to https://mcp.showly.ai with no manual token. If there is no browser on the machine running your agent, or the person approving is somewhere else, use the headless sign-in below.

Headless sign-in (device flow)

When the agent's machine has no browser — a server, a container, CI, a remote shell — or the human approving is on a phone rather than at that machine, run npx @showly/mcp-server login --to claude-code. It prints a page URL and a short code, waits while you approve on any device, and writes the credential into your host config when you do. --to codex writes ~/.codex/config.toml, whose entry reads the credential from the SHOWLY_TOKEN environment variable rather than from the file — the command prints the matching export SHOWLY_TOKEN=… line, and Codex cannot authenticate until that is set where it starts. --to stdout writes nothing and prints a snippet, and --print-token prints only the token so CI can capture it without it landing in a file.

Approve only if the code on the page matches the code in your terminal. The consent screen asks you to confirm that explicitly, because the name a client shows there is one it chose for itself — the code is the part you can check. A code lasts 15 minutes, and opening the page buys you a further 10 minutes to finish signing in and approving; if it runs out, run the command again.

This is not something your client finds on its own. MCP clients do not start device flows, so login is how you reach it. The credential it writes expires after 90 days, and Showly issues no refresh token — run login again when it does.

Troubleshooting

tool not found: mcp__showly__list_sites — The Skill is installed but the MCP server isn't connected yet. In Claude Code run claude mcp list and check the showly entry; invoke a Showly tool once to trigger the sign-in.

Browser sign-in doesn't appear / "unauthorized" — Your agent may not support the standard MCP authorization flow. Confirm it's a recent version, then retry; the agent must be able to follow the 401 → WWW-Authenticate discovery to open the consent page.

"You don't have permission to approve" — The approving account needs at least site:write. Sign in with an owner/admin/developer/member account, or have a teammate with that role approve.

"site not found" — The approved scopes or the site allowlist don't cover the site you asked about. Re-run the sign-in and approve the needed scopes, or widen access from the My agent page (/app/integrations).

Tool calls hang — The MCP server can't reach Showly's API. Check your network; if you've overridden the endpoint, confirm SHOWLY_MCP_URL (the MCP server URL) and SHOWLY_API_URL (the API base) aren't pointing somewhere stale.

Revoking access

To revoke an agent's access, open the My agent page (/app/integrations), find the agent, and disconnect it. Revocation takes effect immediately; the agent will be prompted to sign in again on its next call. There is no token to rotate by hand — the agent obtains a fresh one through the browser flow, or through npx @showly/mcp-server login if it has no browser. Credentials from the headless sign-in expire after 90 days.