Raposa Aval — human approval

raposa-mcp

Raposa Aval は、DC ESCRYPT（https://raposa.group）が提供する、人間による承認を行う MCP サーバーです。 エージェントに、重要な操作を実行する前に、指名された人間から明示的な承認を得るという、誠実な機能を提供します。API は EU のインフラから提供され、承認はハッシュチェーン型の監査ログに記録されるため、監査担当者向けにエクスポートできます。

https://dcescrypt.com · ドキュメント · サンドボックスキーを取得

1 · 承認をフェイルクローズにすることが重要な理由

request_human_approval(action, context, risk) は次を返します。

{approved: true|false, decided_by, decided_at, comment, status, …}

approved が true になるのは、承認権限を持つ人間が Approve を押した場合のみです。拒否、期限切れ、タイムアウトなど、それ以外の結果ではすべて approved: false が返されます。応答がないことは、決して同意を意味しません。

結果	approved	意味
approved	true	指名された人間が期限内に承認しました
rejected	false	指名された人間が拒否しました。続行しないでください
expired	false	判断がないまま TTL が経過しました。続行しないでください。この ID に対する判断が届くことはありません
timeout	false	wait_sec 以内に応答がありませんでした。リクエストは TTL まで開いたままです。後で get_approval を使って確認してください

エージェントは approved に基づいて分岐する必要があります。ツールの結果にキーやシークレットが漏れることはありません。 判断済みの承認は最終的なものであり、同じ ID に対する二度目の判断は HTTP 409 で拒否されます。 すべての判断はハッシュチェーン型の監査ログに記録されます（/v1/audit/verify、/v1/audit/export）。

2 · アーキテクチャ

Agent ──tool call──▶ MCP server (raposa-mcp) ──HTTPS, Bearer RAPOSA_API_KEY──▶ Raposa Aval API
                                                                             │
                                                          approval created (status: pending)
                                                                             │
                     human sees it: e-mail link · web console · Slack · Telegram
                                                                             │
     agent ◀── polls get_approval / webhook callback ◀── decision (approve|reject)

• MCP サーバーが保持するのはクライアント API キーのみです。環境から RAPOSA_API_KEY を読み取り、ツールの入力や出力に含めることはありません。
• 承認は API キーごとにスコープ設定されます。ある顧客が別の顧客のリクエストを読み取ったり判断したりすることはできません。他の顧客の ID には 404 Approval not found が返され、判断できるのはオペレーターキーのみです。
• 判断には承認者の身元とコメントが記録されます。再度の判断は拒否されます。

3 · API キーの取得

1. https://raposa.group/start/ で無料のサンドボックスに登録します（月 100 件の承認）。
2. 「Raposa — your sandbox key」という件名のメールが届きます。メールには有効期限 24 時間の一度限りの取得リンクが含まれています。リンクを開くとキーが一度だけ表示され、再利用はできません。期限切れまたは使用済みのリンクは 410 gone で拒否されます。
3. 取得リンク自体が認証情報です。24 時間以内に最初にリンクを開いた人がキーを所有します。このメールはシークレットとして扱い、転送したり、リンクをチケットやチャットに貼り付けたりしないでください。開く前にリンクが漏えいした可能性がある場合は、[email protected] までご連絡ください。未取得のリンクは 24 時間で自動的に失効します。取得済みのキーは、アカウントページまたはサポートを通じて失効させ、再発行できます。
4. キーを MCP サーバーの環境に設定します（以下を参照）。

サンドボックスでは本番データは不要です。同じ手順で、決済後に有料プランのキーも自動的に発行されます。

4 · インストール（安全な手順）

このサーバーは stdio MCP サーバーです。コマンドは uvx raposa-mcp です（公開済みリリースを固定するには raposa-mcp==0.1.2 を指定してください）。

4.1 キーをコマンドライン経由で渡さない

RAPOSA_API_KEY=<value> をチャット、シェルコマンド、スクリーンショット、リポジトリに書き込まないでください。 シークレットを MCP プロセスに渡す方法として、次の 2 つがサポートされています。

シークレットマネージャーからのエクスポート（1Password CLI。同様のツールでも同じ方法を使えます）：

# ~/.zshrc or ~/.bash_profile — resolved at login from your own vault
export RAPOSA_API_KEY="$(op read 'op://Dev-API/<your-item>/key')"

展開は MCP クライアントを起動するシェル内で行われます。キーがリテラル引数として表示されることはありません（リテラル引数にすると、ps、シェル履歴、クラッシュログに表示されます）。

プレーンな環境変数を使う方法： 値を制限付き権限のファイルに保存し、シェルプロファイルから source します。どの方法を選ぶ場合も、変わらないルールは、MCP プロセスが引数として受け取るのではなく、親プロセスの環境から変数を継承することです。

4.2 Claude Code

Claude Code は MCP 設定で ${VAR} の展開をサポートしています。プレースホルダーは設定ファイルに保存され、サーバーの起動時に環境変数から解決されます（MCP のドキュメント）。

claude mcp add raposa -e RAPOSA_API_KEY='${RAPOSA_API_KEY}' -- uvx raposa-mcp
claude mcp get raposa    # shows the ${...} reference — never the secret itself

シングルクォートが重要です。付けないと、Claude Code が保存する前にシェルがプレースホルダーを解決します。claude mcp get raposa を実行すれば、設定にシークレットが含まれていないことを確認できます。

4.3 汎用 MCP stdio 設定（.mcp.json、その他のクライアント）

{
  "mcpServers": {
    "raposa": {
      "command": "uvx",
      "args": ["raposa-mcp"],
      "env": { "RAPOSA_API_KEY": "${RAPOSA_API_KEY}" }
    }
  }
}

4.4 シークレットを使わずに確認する

# 1 · the stored placeholder is a reference, never the value:
claude mcp get raposa | grep -F '${RAPOSA_API_KEY}'     # prints the line — good
claude mcp get raposa | grep -F '<the key>'             # prints nothing — good
# 2 · end to end: list the tools (the server only runs when it can read the key):
#     three tools — create_approval, get_approval, request_human_approval
# 3 · a controlled read of a non-existent id must answer a 404 "Approval not
#     found", never a missing-environment error — that proves the key arrived

5 · ツールのリファレンス

3 つのツールはすべて、次の引数を正確に受け取ります（制限はクライアント側とサーバー側の両方で適用されます）。

create_approval

承認リクエストを作成し、待機せずに ID をすぐに返します。webhook_url と併用するか、get_approval でポーリングします。

パラメーター	型	必須	備考
action	string	はい	≤ 200 文字
context	string	はい	≤ 4000 文字
risk	string	はい	low | medium | high
requested_by	string	いいえ	≤ 200 文字、デフォルトは mcp-agent
expires_in_sec	integer	いいえ	60–2592000（デフォルトは 86400 = 24 時間）
webhook_url	string (URL)	いいえ	署名付きの判断コールバックの POST 先

{"id": "…", "status": "pending"} を返します。

get_approval

パラメーター	型	必須
approval_id	string (UUID)	はい

すべての終端状態で同じ形式を返します。

{"id": "…", "status": "approved|rejected|expired|pending", "approved": true|false,
 "decided_by": "…", "decided_at": "…", "comment": "…", "message": "…"}

approved が true になるのは、status == "approved" の場合のみです。

request_human_approval

create_approval と同じパラメーター（webhook_url は除く）に、次のパラメーターが加わります。

パラメーター	型	必須	備考
wait_sec	integer	いいえ	ポーリングの待機時間（5 秒間隔）、デフォルトは 600

人間による判断が行われると、get_approval と同じ形式を返します。期限に達すると、{"status": "timeout", "approved": false, "id": "…", "message": "Not approved — nobody answered in Ns. The request is still open; check later with get_approval."} を返します。ただし、リクエストは TTL が切れるまで実際にオープン状態のままです。コンソールで後から判断するか、後で get_approval を使って確認できます。

6 · 実例

実際の出力（サンドボックス、uvx raposa-mcp==0.1.2）：

create_approval → すぐに返ります：

{"id": "79d647c1-…", "status": "pending"}

保留中の get_approval：

{"id": "79d647c1-…", "status": "pending", "approved": false,
 "decided_by": null, "comment": null, "message": "Still waiting for a human."}

人間が承認した場合（メールのリンクまたはコンソール経由）：

{"id": "79d647c1-…", "status": "approved", "approved": true,
 "decided_by": "<approver>", "decided_at": "2026-10-20T…", "comment": "owner mcp e2e approve",
 "message": "Approved by a human — proceed."}

人間が却下した場合：

{"status": "rejected", "approved": false, "message": "Rejected by a human — do not proceed."}

TTL が経過し、誰も判断しなかった場合：

{"status": "expired", "approved": false,
 "message": "Not approved — the request expired before anyone decided."}

wait_sec=8 を指定した request_human_approval で、誰も応答しなかった場合：

{"id": "ed2e963e-…", "status": "timeout", "approved": false, "decided_by": null,
 "message": "Not approved — nobody answered in 8s. The request is still open; check later with get_approval."}

実際に表示されるエラー形式：

他のクライアントの ID または不明な ID に対する get_approval — 他のクライアントのキーに対して、ID の存在が確認されることはありません。

Raposa API 404 on GET /v1/approvals/<id>: {"detail":"Approval not found"}

一度判断された承認は変更されません。2 回目の判断は API に拒否されます。

Raposa API 409 on POST /v1/approvals/<id>/decision

7 · 各ロールが持つ権限

ロール	権限	範囲
client（MCP キー）	自身の承認を作成、読み取り、ポーリングし、Webhook を受け取る	自身の承認のみ。別のクライアントの ID は 404
operator（人間による判断経路）	判断、一覧表示、監査チェーンの検証、監査ログのエクスポート	キー設定に応じて、1 顧客単位または全体
owner	内部プラン：月間承認数無制限、自身のアカウントのキー管理	クォータは無制限ですが、権限は無制限ではありません。同じレート制限、分離、監査が適用されます

ここに記載した内容によって、MCP クライアントキーが管理者用の認証情報になるわけではありません。管理機能（オペレーターコンソール）は独立した認証が必要な場所であり、MCP キーではアクセスできません。

8 · MCP Rush のホスト型リスティング

同じサーバーが MCP Rush のホスト型インフラストラクチャでも公開されています： darius-ceponas/raposa-aval-human-approval-mcp — リリース 0.1.1、ツール 3 件、スキャンおよび検証済み（信頼スコア 96/100、グレード A）。 ゲートウェイは稼働中で、購入者のトークンを含まない呼び出しは拒否されます。

正直な状況： ホスト型リリースは応答しますが、実際の購入者認証情報を使ったゲートウェイのエンドツーエンド呼び出しは、まだ検証できていません。購入者が必要なゲートウェイキーを発行するマーケットプレイスの Access ページは、執筆時点でアクセスできず、公開者は MCP Rush サポートに報告済みです。この問題が解決するまでは、§ 4 の直接 uvx インストールがサポート対象の方法です。この README では、ゲートウェイのエンドツーエンド動作を保証していません。

9 · トラブルシューティング

症状	原因	対処方法
RAPOSA_API_KEY is not set. Get a free sandbox key at …	変数が MCP プロセスに渡されていません	クライアントを起動するシェルでエクスポートしてください。claude mcp add で空の値ではなく ${VAR} のプレースホルダーを使用したことを確認してください
直接 API を呼び出したときの HTTP 401 Invalid API key	キーが無効化されているか、入力が間違っています	保管庫から値を読み直してください。アカウントページからキーをローテーションしてください
正しい ID に対する 404 Approval not found	別のキーの承認であるか、ID の入力が間違っています	承認はテナントごとに分離されています。承認を作成したキーを使用してください
429 … Rate limit exceeded (60/min for your plan)	キーごとの分単位のレート制限（不正利用防止機能で、すべてのプランで有効です）	Retry-After に従ってください。エージェントの処理をまとめてください
2 回目の判断で 409	承認がすでに終端状態に達しています	終端状態の判断は確定しており、変更できません
起きている人がいない状態で timeout	5 秒間隔のポーリングで wait_sec が経過しました	リクエストは TTL まで開いたままです。担当者に確認してから get_approval を実行してください
初回の呼び出しでクライアントが約 1 分間ハングします	ホスト型サーバー／ゲートウェイサーバーのコールドスタート、またはパッケージキャッシュが原因です	再試行してください。2 回目の呼び出しは高速です
クレームリンクに 410 gone と表示されます	1 回限りのリンクがすでに開かれたか、有効期限（24 時間）が切れています	キーはすでに一度表示されています。再登録すると新しいリンクを受け取れます

10 · 開発

このリポジトリは MCP パッケージそのものです：

pip install -e ".[test]" && pytest -q

モックされたトランスポートに対して 11 件の契約テストを実行します。ツールがスキーマとともに一覧表示されること、承認／拒否／タイムアウト／期限切れがすべてフェイルクローズで読み戻されること、作成時に待たずに ID が返されること、API エラーが握りつぶされず報告されること、未知のリスクが API に到達しないこと、キーがない場合は明確なエラーが出る一方でツール一覧は引き続き動作することを検証します。

バックエンド API（クォータ、キーのローテーション、1 回限りのクレームリンク、テナント分離、パネルスコープ、レート制限、ウェブフック、Stripe、Slack／Telegram チャネル、監査チェーン）は、独自のテストスイートを持つ別のリポジトリです。これらの pytest 実行では、バックエンド API はテストされません。

• ソースと課題：https://github.com/agentlabbusiness/raposa-mcp
• ドキュメント：https://raposa.group/docs/
• 法務：MIT License — © DC ESCRYPT SL（LICENSE を参照）
• お問い合わせ：[email protected]

Raposa Aval は DC ESCRYPT の製品です。