セットアップ
AI アシスタントを Waafir に接続するのに必要なのは URL 1 つだけです。アシスタントに URL を貼り付け、求められたら Waafir にサインインします。トークンを作成したりコピーしたりする必要はありません。このページでは、サインイン、各アシスタントでのサーバー追加手順、そしてアシスタントがサインインできない場合に代わりに個人用アクセストークンで接続する方法を説明します。
基本
URL。 1 つの URL ですべての Waafir ツールを利用できます。
https://app.waafir.io/api/mcp/waafirアドオン → 設定 → AIアシスタント に、お使いのデプロイメント用の URL がコピーボタン付きで表示されます。別のデプロイメントをお使いの場合は https://app.waafir.io を置き換えてください。
サインイン。 アシスタントが初めてこの URL を使用すると、ブラウザで Waafir が開きます。通常どおりサインインし、同意画面を確認します。
- どの組織か:複数の組織に所属している場合、アシスタントがどの組織で作業するか。
- どのデータルームか:すべてのデータルームか、選択したものだけか。
- 何ができるか:読み取り・書き込み・管理者のいずれか(ご自身のロールで許可されている範囲を超えることはありません)、およびドキュメントへの署名や組織外への送信を許可するかどうか。
- 本人確認。 二要素認証を設定している場合、トークンの作成時と同様に、承認のたびにまずコードの入力が求められます。
承認すると、ブラウザからアシスタントに戻ります。接続は アドオン → 設定 → AIアシスタント に表示され、そこでアクセスできる範囲を確認したり、接続を取り消したりできます。接続を参照してください。
Unverified app "…"。 自身が管理する Web アドレスで身元を示すアシスタントは、claude.ai のようにそのアドレスで表示されます。自ら選んだ名前で自己登録したアシスタントは Unverified app "<its name>" と表示されます。Waafir はその作成者を確認できないため、ご自身で接続を開始した場合にのみ承認してください。
ツール一覧に表示されるもの。 ツール名はその領域で始まります:dataroom_、esign_、redact_、translate_。一覧には、接続と組織が使用できるツールだけが表示されます。読み取り専用の接続には書き込みツールは表示されず、電子署名ツールは組織が E-Signatures アドオンまたは有効なサブスクリプションを保有している場合にのみ表示されます。接続の一覧には、署名や組織外への送信など、付与していない権限を必要とするツールも含まれます。アシスタントがそのようなツールを呼び出すと、Waafir は呼び出しを拒否し、アシスタントは今度はその権限を選択肢に含めて、再度の承認を求めます。トークンは再度求めることができないため、トークンの一覧にはそれらのツールは含まれません。一覧にないツールでも、アシスタントがあえて呼び出した場合は、理由を添えて拒否されます。
アシスタントの接続
以下の各セクションでは、各アシスタント固有のサーバー追加手順と、そのドキュメントへのリンクを示します(各リンクの最終確認日は 2026 年 10 月 23 日)。これらのアシスタントはいずれも Waafir のサインインでのテストがまだ行われていないため、各セクションにはトークンによる代替手段も併記しています。
Claude(claude.ai および Claude Desktop)
Waafir では未テストです。 Customize → Connectors を開き、Add → Add custom connector を選択して名前を付け、URL を貼り付けて続行します。サインインはオンのままにし、Claude に求められたら Waafir にサインインします。チャットで使用するには、+ → Connectors でオンにします。Team または Enterprise プランでは、オーナーが Organization settings → Connectors でコネクタを追加します。(Claude のガイド)
サインインがうまくいかない場合は、代わりにトークンを使ったリクエストヘッダー Authorization: Bearer <token> を追加してください(代わりにトークンで接続するを参照)。
ChatGPT
Waafir では未テストです。 ChatGPT でリモート MCP サーバーを利用する場所はアプリによって異なります。デスクトップアプリでは Settings → MCP servers → Add server を開いて URL を貼り付け、求められたら Waafir にサインインします。(OpenAI のガイド)
ChatGPT がサインインできない場合は、代わりにトークンを使用してください。
Claude Code
Waafir では未テストです。
claude mcp add --transport http waafir https://app.waafir.io/api/mcp/waafir次に Claude Code 内で /mcp を実行し(またはシェルから claude mcp login waafir を実行し)、ブラウザで Waafir にサインインします。すべてのプロジェクトで使用するには --scope user を追加します。アドオン → 設定 → AIアシスタント に、このコマンドがコピーできる状態で用意されています。(Claude Code のガイド)
Cursor
Waafir では未テストです。 URL を .cursor/mcp.json(すべてのプロジェクトで使う場合は ~/.cursor/mcp.json)に追加し、Cursor に求められたら Waafir にサインインします。
{
"mcpServers": {
"waafir": {
"url": "https://app.waafir.io/api/mcp/waafir"
}
}
}Cursor がサインインできない場合は、代わりにトークンで接続するに示すトークンヘッダーを追加してください。
VS Code
Waafir では未テストです。 コマンドパレットから MCP: Add Server を実行し、HTTP を選択して URL を貼り付け、id に waafir を指定します。VS Code に求められたら Waafir にサインインします。(VS Code のガイド)
Gemini CLI
Waafir では未テストです。
gemini mcp add --transport http waafir https://app.waafir.io/api/mcp/waafir次に /mcp auth waafir を実行し、ブラウザでサインインします。サインインにはローカルのブラウザが必要なため、ほとんどのリモート SSH セッションでは機能しません。その場合はトークンを使用してください。(Gemini CLI のガイド)
Codex
Waafir では未テストです。
codex mcp add waafir --url https://app.waafir.io/api/mcp/waafir
codex mcp login waafir代わりにトークンで接続する
アシスタントがサインインできない場合やスクリプトでは、個人用アクセストークンを使用します。すべてのリクエストは、Authorization ヘッダーで bearer トークン としてトークンを送信します。
Authorization: Bearer waafir_pat_...実際のトークンを共有ファイルやリポジトリにコミットしないでください。パスワードと同様に扱ってください。アドオン → 設定 → APIトークン に、コピーしてそのまま使えるスニペットがあります。
領域サーバー。 waafir のほかに 4 つの領域サーバーも引き続き提供されているため、既存の設定はそのまま動作します。各領域サーバーは自分の領域のツールだけを同じ方法でフィルターして一覧表示し、従来のツール名(dataroom_list_files ではなく list_files)を維持します。waafir に接続する場合、これらは必要ありません。
| サーバー | URL |
|---|---|
waafir-redact | https://app.waafir.io/api/mcp/waafir-redact |
waafir-translate | https://app.waafir.io/api/mcp/waafir-translate |
waafir-dataroom | https://app.waafir.io/api/mcp/waafir-dataroom |
waafir-esign | https://app.waafir.io/api/mcp/waafir-esign |
サーバー名のない /api/mcp エンドポイントは存在しません。サーバー名のセグメントは必須で、これがないリクエストは 404 を返します。waafir-esign は有料サービスです。E-Signatures アドオンまたは有効なサブスクリプションがない場合、その URL は ADDON_NOT_PURCHASED エラーを返します。waafir では、同じ組織には単に esign_ ツールが表示されません。
Claude Code。 シェルの履歴に残らないよう、まずトークンを環境変数に格納します。
export WAAFIR_PAT=... # the token you copied at issuance
claude mcp add --transport http waafir https://app.waafir.io/api/mcp/waafir \
--header "Authorization: Bearer $WAAFIR_PAT"この設定をプロジェクトで共有するには、同じエントリをプロジェクトの .mcp.json に記述します。Claude Code は各ユーザーの環境から ${WAAFIR_PAT} を展開するため、トークンを含めずにファイルをコミットできます。
{
"mcpServers": {
"waafir": {
"type": "http",
"url": "https://app.waafir.io/api/mcp/waafir",
"headers": {
"Authorization": "Bearer ${WAAFIR_PAT}"
}
}
}
}Claude Desktop の設定ファイル。 claude_desktop_config.json が起動するのはローカルサーバーです。各エントリは実行する command であり、リモートの url ではありません。このファイルから Waafir に接続するには、mcp-remote ブリッジ(Node.js が必要)を実行します。これはリモートサーバーに転送し、トークンをヘッダーとして追加します。
{
"mcpServers": {
"waafir": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://app.waafir.io/api/mcp/waafir",
"--header",
"Authorization:${WAAFIR_AUTH}"
],
"env": {
"WAAFIR_AUTH": "Bearer YOUR_WAAFIR_PAT"
}
}
}
}Authorization:${WAAFIR_AUTH} 引数にスペースを含めないようにし、Claude Desktop を再起動してください。
Cursor、および URL とヘッダーを指定できるその他のクライアント。
{
"mcpServers": {
"waafir": {
"url": "https://app.waafir.io/api/mcp/waafir",
"headers": {
"Authorization": "Bearer YOUR_WAAFIR_PAT"
}
}
}
}領域サーバーも同じ方法で追加でき、エントリのキーと URL を変更するだけです。
ツールの呼び出し
接続後、クライアントはサーバーのツールを一覧取得し(MCP の tools/list)、あなたに代わってツールを呼び出します。ツールを手動で呼び出す必要はありません。AI クライアントに何かを依頼すると(「このデータルームのファイルを一覧表示して」「この段落をフランス語に翻訳して」)、クライアントが適切なツールを選んで呼び出し、各サーバーのリファレンスに記載された引数を渡します。ツールの仕様については、waafir-redact、waafir-translate、waafir-dataroom、waafir-esign の各リファレンスを参照してください。
問題が発生したとき
失敗は2 つの異なる層で発生し、その見え方は異なります。これを誤解することが、ここで最もよくある統合上の誤りです。HTTP ステータスだけで分岐するクライアントは、2 つ目の種類の失敗をすべて見逃してしまいます。
第 1 層 — ツールが実行される前にリクエストが拒否された
これらは JSON-RPC 形式のエラー本文を伴う、実際の HTTP エラーステータス です。リクエストがツールにまったく到達しなかったことを意味します。
-
404 — 不明な MCP サーバー。 URL のサーバー名セグメントが
waafir、waafir-redact、waafir-translate、waafir-dataroom、waafir-esignのいずれでもありません。多くの場合、入力ミスか、サーバー名のない/api/mcpだけを指定しています。URL を修正してください。 -
402 — アドオン未購入。 そのサーバーは有料サービス(現時点では
waafir-esign)ですが、組織がアドオンも有効なサブスクリプションも保有していません。組織の管理者は、請求設定からアドオンまたはプランを購入できます。利用資格のない組織は、そのサーバーのツールを一覧表示することさえできません。waafirが 402 を返すことはありません。代わりに有料ツールを非表示にし、そのツールを呼び出すと第 2 層でQUOTA_EXCEEDEDとして拒否され、そのツールを名指しするメッセージが返されます。このメッセージにはADDON_NOT_PURCHASEDも含まれます。 -
401 — 未認証。 認証情報がない、形式が不正、取り消し済み、または期限切れです。接続の場合は、アシスタントから再度サインインしてください。ほとんどのアシスタントは 401 を受け取ると自動的にこれを行います。取り消された接続や 30 日間使用されなかった接続は、改めてサインインする必要があります。トークンの場合は、
Authorizationヘッダーが存在すること、およびトークンが アドオン → 設定 → APIトークン でまだ有効であることを確認してください。取り消されているか期限切れの場合は、新しいトークンを発行してください。この動作より前のデプロイメントでは、トークンがない場合や形式が不正な場合に、代わりに 403CSRF validation failed: missing Originを返します。このサーフェスでは、これもトークンがないか形式が不正であることを意味します。 -
403 — 禁止。 認証情報が入口で拒否されました。接続や PAT ではなく、ログイン済みのブラウザセッションが使用された(このサーフェスではセッションは受け付けられません)か、組織が IP 許可リスト を適用していて、リクエストがその範囲外のアドレスから送信されました。
-
429 — リクエストが多すぎます。 MCP のレート制限に達しました。ここでの制限は、IP アドレスや組織を単位とするものではありません。予算はトークン単位なので、同じ組織の同僚や同じネットワーク上の 2 台目のクライアントがそれを消費することはありません。制限はトークンごとに 1 分あたり 60 リクエストです。カウントはトークンを照合する前に行われるため、形式が不正なトークン、取り消し済みのトークン、期限切れのトークンでも消費されます。また、同じトークンによる MCP 以外での Waafir API への呼び出しも、同じ 60 回にカウントされます。サインインによる接続の 60 回は接続単位でもカウントされるため、アシスタントがサインインを更新したときに取得する新しいトークンで 60 回が新たに始まるわけではありません。
レスポンスには
Retry-Afterヘッダーがなく、区別するためのコードもありません(このサーフェスの 429 はすべて同じに見えます)。そのため、連続して再試行するのではなく、独自のスケジュールでバックオフしてください。1 つのトークンでは余裕が足りない場合は、2 つ目を発行してください。制限はトークン単位です。
第 2 層 — ツールが実行され、拒否した
拒否のほとんどはこの層で発生し、これは HTTP エラーではありません。 HTTP レスポンスは 200 で、JSON-RPC エンベロープは成功エンベロープです。失敗はツールの結果の中で伝えられます。結果には isError: true が設定され、テキストコンテンツは次のとおりです。
{ "error": { "code": "CONFLICT", "message": "…" } }error.code で分岐してください。コードは次のとおりです。
| コード | 意味 |
|---|---|
INVALID_ARGUMENT | 引数がない、形式が不正、または有効な id ではありません。修正して再試行してください |
FORBIDDEN | トークンは有効ですが、この呼び出しは許可されていません |
NOT_FOUND | そのようなレコードが存在しないか、あなたのものではありません |
CONFLICT | 理解され許可されていますが、データルームが実行できる状態にありません |
TOO_LARGE | 入力がサイズ制限を超えています。分割してください |
QUOTA_EXCEEDED | 従量制の割り当てを使い切りました。誰かが購入またはアップグレードする必要があります |
UPSTREAM_ERROR / UNAVAILABLE | 一時的なダウンストリームの障害です。後で再試行してください |
INTERNAL | 予期しない障害です。再試行せず、エスカレーションしてください |
このうち 2 つは誤解されがちです。
- スコープが低すぎる場合の
FORBIDDEN。readの接続やトークンには書き込みツールは表示されませんが、それでも呼び出したクライアントはツールによって拒否されるため、HTTP 403 ではなく、ペイロード内のFORBIDDENとしてここに届きます。特定のデータルームに制限されたトークンが、許可リスト外のデータルームをdataroom_idとして指定した場合も同様です。ファイルやフォルダーの id を受け取るほとんどのツールは、そのようなルーム内の項目に対しては、存在しない id の場合とまったく同じようにNOT_FOUNDを返します。アシスタントから再度サインインして適切なスコープまたはデータルームを付与するか、適切なスコープを持つトークンを発行してください。 CONFLICT。 呼び出しは理解され許可されていますが、データルームが実行できる状態にありません。たとえば、フォルダー名がすでに使われている、ファイル名がその後に別の現存ファイルに使われている、復元しようとしている項目のコンテナーがまだ削除されたままである、あるいはアップロードが完了していない、といった場合です。CONFLICTは認可の問題ではないため、再度サインインしたりトークンを再発行したりしても解決しません。妨げとなっているレコードがある場合はメッセージにそのレコードが示されるので、対処してから再試行してください。各ツールが返しうる競合はwaafir-dataroomリファレンスに記載されています。
まだチェック中のファイル。 Waafir は、新しくアップロードされたファイルと新しいバージョンを、コンテンツを提供する前にすべてチェックします。それまでの間、ファイルのコンテンツを読み取るツールは、error.reason: "ACTIVATION_PENDING" とメッセージ This file is still being checked. Try again shortly. を伴う UNAVAILABLE を返します。これは一時的なものです。少し待ってからもう一度呼び出してください。
どちらの層でも、明確な拒否は、Waafir が処理しない呼び出しに対する想定どおりの安全な結果です。要求よりも少ない処理を黙って行うのではなく、リクエストを失敗させます。