Writ Cloud

---

writ-mcp は、stdio MCP クライアント（Claude Code、Claude Desktop、Cursor、 Windsurf、Codex）を Writ に接続します。 これにより、すでに記録したブラウザワークフローを、アシスタントが呼び出せるツールとして利用できます。ワークフローの実行、収集データの読み取り、過去の結果の検索、スケジュール設定、REST エンドポイントとしての公開、サイトのクロール開始が可能です。

これは透過的な stdio↔HTTP プロキシであり、それ以外の機能はありません。すべてのツール、スキーマ、ルールはサーバー側にあるため、利用できる機能は常にインスタンスの機能と一致します。また、新しいツールを使うためにこのパッケージをアップグレードする必要はありません。依存関係はゼロ、ファイルは1つ、Node のコア機能のみで動作します。

Streamable HTTP にネイティブ対応しているクライアントでは、このプロキシは不要です。Authorization: Bearer <key> ヘッダーを付けて、/mcp エンドポイントに直接接続してください。

クイックスタート

1. API キーを取得します。 Writ アプリで、Settings → Developers → API keys を開きます。キーは wt_… の形式です。

2. サーバーを追加します。

セルフホスト型コーディネーターに接続する場合：

claude mcp add writ-selfhost -e WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcp --url https://writ.example.com

このマシン上のコーディネーターに接続する場合：

claude mcp add writ-selfhost -e WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcp --url http://localhost:8000

公開済みのワークフロー単位のエンドポイントに接続する場合（「Expose as MCP」のスラッグ URL をそのまま使用します。パスの書き換えはありません）：

claude mcp add my-tools -e WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcp --url https://mcp.example.com/mcp/my-tools

3. 動作を確認します。

claude mcp list

--url を指定しない場合は、Writ Cloud がデフォルトの接続先になります （https://api.usewrit.app）。コネクターを独自のコーディネーターに接続するには、 --url を指定してください。ステータスを参照してください。

キーはコマンドラインではなく、環境変数を介して渡してください。 --api-key も使用できますが、キーがプロセスの引数一覧に含まれ、ローカルのあらゆる プロセスから ps で読み取れるようになります。また、シェルの履歴にも記録されます。 この方法を使うと、コネクターが注意を表示します。

実行中のコーディネーターでは、Connect ページと GET /api/mcp/connect-info から、 値があらかじめ入力された次のコマンドも取得できます。

Claude Desktop / Cursor（設定ファイル）

claude_desktop_config.json（Claude Desktop）または ~/.cursor/mcp.json （Cursor）に追加します。キーが引数一覧に含まれないため、env 形式を推奨します。

{
  "mcpServers": {
    "writ-selfhost": {
      "command": "npx",
      "args": ["-y", "writ-mcp"],
      "env": {
        "WRIT_COORDINATOR_URL": "https://writ.example.com",
        "WRIT_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

npm を使用しない場合

セルフホストインストールでは、このコネクターが connectors/writ-mcp にバンドルされています。ビルド手順はないため、ディスクから直接実行できます。

node /path/to/writ/connectors/writ-mcp/index.js --url https://writ.example.com

他の Writ サーバーと共存できます。 各接続先は意図的にそれぞれ固有のスラッグで登録されます。デスクトップアプリは writ、Writ Cloud は writ-cloud、セルフホストのコーディネーターは writ-selfhost です。また、それぞれが異なるタイトルでアシスタントに識別されます。任意の組み合わせを同時に接続したままにできます。

利用できるツール

ツールはこのパッケージではなく、接続先のサーバーによって提供されるため、新しいサーバーツールはコネクターを更新しなくても利用できます。Writ Cloud では以下の39個のツールが一覧表示されます。セルフホストのコーディネーターでは、自身の列にマークされたツールが一覧表示されます。

ツール	機能	Writ Cloud	セルフホスト
writ_list_workflows	保存済みのワークフローを一覧表示します（ピン留めしたワークフローに限り、run_<name> ツールが追加されます）	はい	はい
writ_run_workflow	ワークフローを実行し、抽出されたデータが取得できるまで待機します	はい	はい
writ_pin_workflow_tool	ワークフローを専用の run_<name> ツールとしてピン留め、またはピン留め解除します。デフォルトでは無効で、上限があります。すべてのワークフローは引き続き writ_run_workflow から実行できます	はい	はい
writ_update_workflow	ワークフローの概要を確認するか、その場で編集します（設定、手順、関数、エージェントスキル）	はい	はい
writ_diagnose_http_workflow	実行中の各リクエストへの応答と、ブラウザーなしで実行されたかどうかを表示します	はい	いいえ
writ_create_http_extraction	キャプチャしたリクエストから、複数リクエストに対応するブラウザーレス抽出を作成します	はい	いいえ
writ_workflow_data	ワークフローに蓄積されたデータテーブルを読み取ります	はい	はい
writ_search_data	これまでに収集したすべてのデータを検索します	はい	はい
writ_export_data	ワークフローのデータを CSV/JSON としてエクスポートします	はい	はい
writ_workflow_runs	実行履歴とステータスを表示します	はい	はい
writ_set_schedule	ワークフローをスケジュール設定します（間隔／毎日／毎週）	はい	はい
writ_expose_workflow_api	ワークフローを呼び出し可能な REST エンドポイントとして公開します	はい	はい
writ_scrape	1 つまたは複数のページをクリーンな Markdown として読み取ります（Cloud ではリスティングの上位 N 件も読み取れます）	はい	はい
writ_crawl_site / writ_crawl_status	分散サイトクロールを開始し、状態を確認します	はい	はい
writ_crawl_files	クロールで取得した元のドキュメントを表示します（PDF、Office ファイル、画像）	はい	いいえ
writ_saved_crawls / writ_run_saved_crawl / writ_saved_crawl_data	保存済みクロール（下記参照）	はい	はい
writ_update_saved_crawl	保存済みクロールの設定を確認または変更します	はい	いいえ
writ_personas	保存済みのサインイン ID を確認し、使用できる状態にします（下記参照）	はい	はい
writ_payment	ユーザーが承認したカードで支払いを行います。Writ はユーザーの確認後に注文を確定します	はい	いいえ
writ_devices	リンク済みの Writ デスクトップを一覧表示するか、この接続先をいずれかのデスクトップに設定します	はい	いいえ
writ_create_automation	イベントまたは時刻をトリガーに、ワークフローを実行したり、通知を送信したり、エージェントを起動したりします	はい	はい
writ_list_webhooks	受信 Webhook の URL と、それらが起動するオートメーションを表示します	はい	はい
writ_create_monitor / writ_wire_monitor	ページを監視し、変更に応じて動作します	はい	はい
writ_browser_use	アシスタントがターンごとに操作する実際のブラウザーを開きます	はい	はい
writ_record_website	繰り返し実行できるタスクをワークフローとして記録します	はい	はい
writ_website_to_api	Web サイトを呼び出し可能な API に変換します	はい	はい
writ_discovery_status	API の構築状況を確認し、結果を取得します	はい	いいえ
writ_browser_act / _context / _network / _save / _cancel	ブラウザーを操作し、ページとそのネットワークリクエストを読み取り、セッションを保存または終了します	はい	はい
writ_browser_compose	セッション内で名前付き関数、入力、明示的な手順を定義します	はい	いいえ
writ_browser_ask_user	CAPTCHA、コード、判断をライブブラウザー上でユーザーに引き継ぎます	はい	いいえ
writ_browser_sessions	再開可能なブラウザーセッションを一覧表示します	はい	いいえ
writ_record_start / _act / _context / _network / _save / _cancel	互換性のために残されている、ブラウザーループの旧名称です	いいえ	はい

構築ツール（writ_browser_use、writ_record_website、writ_website_to_api、続いて writ_browser_act / _context / _network / _save / _cancel）はどちらの構成でも使えます。 どちらにも writ_build ツールはないため、writ_record_website を使用してください。 アシスタントが実際のブラウザーを開いてターンごとに操作し、セッションを再利用可能なワークフローとして保存します。 保存後のワークフローは、モデルを介さずに再実行されます。Writ Cloud では Writ のフリート上で実行され、セルフホスト型コーディネーターでは独自の fleet agent 上で実行されます。どちらの場合も、 アシスタントが頭脳となり、2 つ目のモデルキーは必要ありません。

最近の結果を再利用する（max_age）

ワークフローの実行では実際のブラウザーを操作するため、同じ質問を同一セッション中に2回尋ねると、2回分の実行と待ち時間が発生します。各ワークフローツールには、最近の回答で十分という意味の省略可能な max_age（秒）があります。

{ "name": "run_price_check", "arguments": { "sku": "B0C123", "max_age": 300 } }

• 省略または 0 — 常に新しく実行します（デフォルト。自動的に古くなることはありません）。
• N — N 秒未満の結果を再利用し、それ以外の場合は実行します。

再利用された回答には _cache: {hit: true, age_seconds: N} が付くため、アシスタントは結果がどの程度新しいかを確認できます。

max_age は Writ Cloud とセルフホスト型コーディネーターのどちらでも同じように機能し、固定されたワークフロー専用の run_<name> ツールと writ_run_workflow の両方で使えます。

保存済みクロールを呼び出す（writ_run_saved_crawl）

サイト全体のクロールは時間がかかり、利用量も計測されるため、同じ質問に答えるために再クロールするのは、アシスタントが犯しうる最もコストの高いミスです。保存済みクロールは、安定した名前が付いた保存済みのクロール設定で、同じ max_age の仕様が適用されます。

{ "name": "writ_run_saved_crawl", "arguments": { "crawl": "docs", "max_age": 86400 } }

• hit — そのクロールで収集済みのページが、インラインで即座に返されます。クロールも利用量の計測も発生しません。
• miss — 保存済みの設定でサイトを再度クロールし、writ_crawl_status でポーリングするためのクロール ID が返されます（クロールは単一のツール呼び出しより長く続きます）。

この機能は、次の3つのツールで利用できます。

ツール	機能
writ_saved_crawls	保存済みクロールを一覧表示します。サイトを再クロールする前に、ここを確認してください。
writ_run_saved_crawl	保存済みクロールを実行し、max_age の条件を満たす場合は最近のデータを再利用します。
writ_saved_crawl_data	保存済みクロールで収集済みの内容を、経過時間を問わず読み取ります。クロールは実行しません。

作成するには、writ_crawl_site に save_as を渡します。これにより設定が保存され、同時に実行されるため、そのクロールは REST からも呼び出せるようになります。同じ save_as を再利用すると、重複が増える代わりに、保存済みクロールが更新されます。保存には admin スコープの認証情報が必要です（再利用可能で呼び出し可能な設定を作成するためです）。実行に必要なのは run だけです。

ログインが必要なサイト（writ_personas）

ペルソナは、保存済みのサインイン ID です。ユーザー名、サーバー側で保護された認証情報、任意の2FA、サインイン済みの有効なセッションが含まれます。writ_personas では、ペルソナの一覧（各ペルソナの準備状況を含む）の表示、個別の情報の確認（get）、ログインワークフローの実行によるセッションの更新（sign_in）、または AI に一度サインインの流れを記録させて、以後ペルソナが自分でサインインできるようにすること（record_login）ができます。その後、アシスタントが persona_id を writ_run_workflow（および各固定された run_<name> ツール）、writ_crawl_site、または writ_scrape に渡すと、タスクはサインイン済みの状態で実行されます。Writ Cloud では writ_browser_use も対象となり、2FA コードはサーバー側で生成されます。

設計上、このコネクターができるのはペルソナの使用のみで、管理はできません。ペルソナの作成、編集、削除には認証情報が関わるためです。また、認証情報やワンタイムコードが MCP 接続を通じて送受信されることはありません。ペルソナは Writ ダッシュボードで作成します。

ツール呼び出しがタイムアウトした場合

status: "running" と retryable: true が返されます。実行はキャンセルされていません。ツールを再度呼び出すと、2回目の実行が始まります。しばらく待ってから、最初の実行結果が得られるよう十分な範囲の max_age を指定して再試行してください。

設定

フラグは環境変数より優先されます。

フラグ	環境変数	デフォルト	用途
--url	WRIT_COORDINATOR_URL / WRIT_URL	https://api.usewrit.app	接続先のベース URL です。パスがすでに /mcp または /mcp/<slug> の URL は、そのまま使用されます。
--api-key	WRIT_API_KEY	— (必須)	Authorization: Bearer に使うキーです。環境変数の使用を推奨します。
--insecure	WRIT_INSECURE_TLS=1	オフ	自己署名のローカル CA 証明書を受け入れます。プライベートネットワークでのみ使用してください。
--timeout	WRIT_MCP_TIMEOUT_MS	600000	リクエストごとのタイムアウト（ミリ秒）です。writ_run_workflow の長時間の待機も対象となります。
--help / --version	—	—	使用方法またはバージョンを表示して終了します。

ローカル CA を使った HTTPS（セルフホスト）： CA を信頼する設定を行い（推奨）、https:// アドレスを使用するか、NODE_EXTRA_CA_CERTS=/path/to/ca.pem を設定してください。--insecure は localhost のテストでのみ使用してください。証明書の検証が完全に無効になり、中間者攻撃によってキーが漏えいする危険があります。

セキュリティ

このプロセスは認証情報を扱うため、認証情報が漏えいする可能性のある要素は、利便性よりも明確さを優先しています。詳細は SECURITY.md をご覧ください。

• キーが送信されるのは --url の宛先だけです。 テレメトリ、分析、更新チェックはありません。依存関係がゼロのため、プロセス内に外部と通信する推移的なコードは存在せず、今後その状態が変われば CI がビルドを失敗させます。
• リダイレクトには追従しません。 Location ヘッダーで指定された任意のオリジンに Authorization ヘッダーを再送信すると、選択していないホストにキーを渡すことになります。3xx が返された場合は、--url に最終 URL を指定するよう促すエラーになります。
• URL 内の認証情報は、すべての診断メッセージで伏せられます。 MCP クライアントはサーバーの標準エラー出力をディスク上のログファイルに書き込みます。対策しない場合、https://user:pass@host/ が平文で記録されてしまいます。
• キーが漏えいする可能性のあるすべてのケースで、標準エラー出力に明確な警告が表示されます。 TLS 検証が無効な場合、ループバック以外のホストに平文の http:// で接続する場合、またはコマンドラインでキーを渡した場合が該当します。
• 再試行によってワークフローが二重実行されることはありません。 再試行するのは読み取り専用のメソッドのみです。tools/call は必ず一度だけ送信されます。再試行すると、コネクターから把握できない副作用が再実行される可能性があるためです。
• レスポンスのサイズは 32 MB に制限されています。 エンドポイントに問題があっても、OS にセッションを強制終了されるまでプロセスが肥大化することはありません。
• 未応答のリクエストは発生しません。 ハングした MCP クライアントはアシスタントへのサービス拒否につながるため、このコネクターはその事態を防ぐことに最大限取り組んでいます。

キーの権限を必要最小限にしてください。 実際に使うツールが追加の権限を必要としない限り、キーには workflows:read / workflows:execute のみを付与してください。

インストールしたものを検証する

リリースは CI から npm provenance 付きで公開されるため、tarball は暗号学的にビルド元のコミットおよびワークフローと結び付けられています。

npm audit signatures

トラブルシューティング

症状	原因と対処
Unauthorized: … rejected the API key	キーが間違っているか、無効になっているか、必要なスコープがありません。Settings → Developers で workflows:read / workflows:execute を指定して再作成してください。
Cannot reach …	--url が間違っているか、接続先がダウンしています。自己署名証明書を使用している場合は、上記のローカル CA に関する注意を参照してください。
… redirected (HTTP 301)	リバースプロキシによってリダイレクトされています（通常は http → https）。--url に最終的な URL を指定してください。
The API key contains characters that cannot be sent in an HTTP header	キーに改行文字または制御文字が含まれています。通常はコピー＆ペースト時に混入したものです。コピーし直してください。
ツールが一覧に表示されない	コネクターがコーディネーターに接続できなかったか、キーが拒否されました。上の行を参照してください。接続が正常であれば、ワークフローを保存する前でも静的な writ_* ツールは常に一覧に表示されます。
ワークフローに run_<name> ツールがない	派生ツールはオプトイン方式で、デフォルトでは無効です。writ_pin_workflow_tool（またはアプリの MCP ツールとして公開 スイッチ）でワークフローを固定すると、次回の tools/list で表示されます。アカウントあたり最大 20 個です。いずれの場合も、すべてのワークフローは writ_run_workflow を通じて実行されます。
クライアントが接続できず、エラーも表示されない	コネクターの stderr を確認してください。クライアントがログを記録します。Claude Code の場合：~/Library/Caches/claude-cli-nodejs/<project>/mcp-logs-<name>/。

ステータス

セルフホスト型コーディネーター	エンドツーエンドでサポートされ、検証済みです。
公開済みの /mcp/<slug> エンドポイント	サポートされています。
Writ Cloud（https://api.usewrit.app、--url を指定しない場合のデフォルト）	サポートされています。--url が渡されない場合、自動的に使用されます。

開発

npm test

開発用依存関係はありません。このテストスイートでは、Node の組み込み node:test を使用し、実際の index.js をサブプロセスとしてモック MCP サーバーに対して実行して、MCP クライアントが使用するのと同じ stdio 経路をテストします。実行時間は約 6 秒です。npm publish を実行すると、prepublishOnly によって自動的にテストが実行されます。

CONTRIBUTING.md を参照してください。次の 2 つの重要なルールに注意してください。依存関係は恒久的にゼロにすること、およびここにツールのロジックを置かないことです。

Writ のその他の要素

usewrit/writ	セルフホスト型コーディネーターです。ウェブ UI、API、データが含まれます。ここから始めてください。
usewrit/writ-agent	実際のブラウジングを行う Rust 製のフリートワーカーです。
writ-mcp（このリポジトリ）	MCP コネクターです。

ライセンス

MIT — LICENSE を参照してください。

このパッケージは、コーディネーター内ではなく MCP クライアント内で 実行されるため、どこにでも組み込めるよう、意図的に寛容なライセンスを採用しています。このパッケージが接続するコーディネーターは AGPL-3.0-only です。この 2 つのライセンスは相互に置き換えられません。