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 your client cannot run the browser flow (a headless server, say), see the no-browser fallback below.

No-browser fallback (device flow)

For environments without a browser, Showly also supports the OAuth device flow: your agent shows a short code, you open https://showly.ai/oauth/device on any other device, enter the code, and approve. This is a fallback — the browser flow above is the default and needs no code.

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 under Admin → Agent (the MCP tokens page).

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 Admin → Agent (the MCP tokens page), find the token, and revoke 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.