スキル

スキルのクイックスタート

@showly/mcp-server をインストールし、端末から認証すると、実際のプレビュー URL がすぐに表示されます。

Showly の見出しの約束は、「エージェントからサイトを展開する」です。このページは、端から端までのレシピ。インストールと最初のプレビューには約 90 秒かかります。新鮮なラップトップ。本番公開パスでは、ブラウザ内での手動承認ステップが追加されます。 (セクション 5 で説明します)。

1. エージェントにインストールする

正規のインストールパスは、@showly/mcp-server パッケージ (bin showly-mcp）。 Claude Code の場合:

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

Codex の場合:

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

これらは、単一の MCP-サーバーエントリ (トランスポート + URL) を書き込みます。 ~/.claude.json または ~/.codex/config.toml。トークンは書き込まれません: エージェントはエンドポイント自体から Showly の OAuth 認証サーバーを検出します初めて使用するときにブラウザーのサインインを実行します。パッケージには型付きのものも出荷されます manifest.json すべての Showly ツール、その必要なスコープ、および MCP 発信元の呼び出しは許可されます。

ブラウザーでのサインインとヘッドレスサインインについてはスキルのインストールを参照してください。

エージェントがインストーラーでサポートされていない場合は、次を実行します。 npx @showly/mcp-server install --to stdout を選択し、スニペットを手動で貼り付けます。

2. 実際の会話から承認する

Claude Code (またはあなたの Codex に相当するもの) を開いて、 Showly ツール。例えば：

「私の Showly サイトをリストします。」

エージェントが list_sites を呼び出します。このマシンにはまだ Showly トークンがないため、ホストがブラウザーのサインインを開き、人が Allow をクリックします。

マシンにブラウザーがない場合（サーバー、コンテナー、CI、リモートシェル）、またはあなたがそのマシンの前にいない場合は、ヘッドレスサインインを使います。

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

次の内容をそのまま表示して待機します。

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.

任意のデバイス（スマートフォンでも構いません）でページを開き、登録に使ったメールアドレスでサインインします。同意画面にはコード、要求されたスコープ、許可 / 拒否ボタンが表示されます。

ページのコードとターミナルのコードを見比べ、一致していることを示すチェックを入れ、許可をクリックします。この確認が要点です。同意画面に出るクライアント名はクライアント自身が付けたものなので、検証できるのはコードだけです。ターミナルに戻るとコマンドは数秒で完了し、読み取りツールはすぐに使えます。

3. 1 行の変更を加えてプレビューします。

エージェントに尋ねてください:

「northstar サイトで、H1 を「Hello from W7」に変更してプレビューしてください。」

エージェントは 4 つのツール呼び出しを連鎖させます。

create_change_plan — 文章を構造化された計画に変えます。
apply_site_patch — 編集を _changeset_ としてステージングします (スコープ site:write)。
create_preview — 変更セットをビルドし、保護されたプレビュー URL を返します

(スコープ preview:create)。

run_checks — そのデプロイメントの lint / typecheck / build ステータスを読み取ります

(スコープchecks:run)。

小さな編集は約 5 秒、実際の Next.js アプリは約 30 秒が目安です。エージェントは保護されたプレビュー URL を表示します。現在の本番サイトに影響を与えずに変更を確認できます。

4. 本番環境への移行

Showly エージェントが本番環境に直接公開することはできません。エージェントが電話をかける request_publish (スコープ publish:request)。保留中の承認が作成され、何も送信する代わりに、webApprovalUrl ディープリンクを返します。

{
  "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"
  }
}

エージェントはあなたに webApprovalUrl を渡します。それを開いて正確なプレビューを確認し、計画に必要なチームメイトの承認を完了します。 OTP/MFA 登録は行われません。必須です。公開が開始されると、エージェントは get_preview_status を呼び出します。 waitForChange: true ロングポーリング (デフォルトは 30 秒、最大 60 秒) 天井）。本番デプロイメントが ready に切り替わると、応答はエージェントが最終的なライブ URL として返す productionUrl が含まれます。

端末から送信されるもの

エージェントはローカルで実行されます (Claude Code、Codex、...)。
サイトコンテキストの読み取りでは、MCP トークンのスコープで許可されたデータだけが返ります。
apply_site_patch または別のアップロードツールを呼ぶと、変更ファイルが Showly に送信されます。
Showly はそれらのファイルから非公開プレビューを作成し、該当する操作をワークスペースの監査履歴に記録します。

完全なデリバリーの流れはアーキテクチャを参照してください。

よくあるエラー

missing_bearer_token — エージェントが

Authorization: Bearer mcp_… を送信していません。 npx @showly/mcp-server install を再実行し、エージェントを再起動してください。

invalid_token — トークンの有効期限が切れているか、取り消されているか、または MCP トークンではありません。

Showly ツールを再度呼び出して、ブラウザーの新しいサインインをトリガーします。エージェント新しいトークンを自動的に取得します。 (強制的に実行するには、以下の古い行を取り消します。 管理者→エージェント が最初です。)

insufficient_scope — 要求されたツールには、許可していないスコープが必要です

同意フロー中。取り消しと再承認、今回は承認します範囲。

本番公開 — publish_site は短期間の 2 ステップを使用します

ユーザーが「はい」と答えた後の確認。ワークスペースに二次レビュー担当者の承認ポリシーが有効になっている場合は、request_publish とその代わりにwebApprovalUrl。どちらのフローでも OTP/MFA 登録は必要ありません。

次のステップ

カスタムスキルの作成 — 独自のワークフローをラップします。
MCP ツールリファレンス — すべてのツールの入力と出力。
RBAC と承認 — ロール、スコープ、監査、承認ルール。