agent-auth-mcp

Agent Auth MCP ツール

Agent Auth プロバイダーと連携するための Agent Auth MCP ツールを利用できます。エージェント認証に関する操作では、HTTP リクエストを直接送信したり、独自のコードを書いたりするのではなく、常にこれらの MCP ツールを優先して使用してください。

MCP サーバーの起動

MCP サーバーは CLI の一部です：

auth-agent mcp

または、プロバイダーを事前設定して起動します：

auth-agent mcp --url https://api.example.com

Cursor / Claude Desktop の設定

{
  "mcpServers": {
    "auth-agent": {
      "command": "npx",
      "args": ["@auth/agent-cli", "mcp", "--url", "https://api.example.com"]
    }
  }
}

利用可能なツール

MCP サーバーは 17 個のツールを公開しています。以下の番号付きワークフローに従ってください。

ステップ 1：検出 — プロバイダーを探す

ツール	パラメーター	使用するタイミング
list_providers	（なし）	最初に呼び出してください。 検出済み／設定済みのプロバイダーをすべて一覧表示します。
search_providers	intent（必須）	名前または用途でディレクトリを検索します（例：「ウェブアプリをデプロイする」、「vercel」）。
discover_provider	url（必須）	特定の URL でプロバイダーを検索します。list/search で見つからなかった場合にのみ使用してください。

必ず list_providers から始めてください。 結果が空の場合は、search_providers または discover_provider を使用してください。

ステップ 2：機能 — 利用可能な機能を確認する

ツール	パラメーター	使用するタイミング
list_capabilities	provider（必須）、query、agent_id、limit、cursor	プロバイダーの機能を一覧表示します。
describe_capability	provider、name（必須）、agent_id	入力スキーマを含む完全な定義を取得します。実行前に必ず呼び出してください。

ステップ 3：接続 — エージェントを認証する

ツール	パラメーター	使用するタイミング
connect_agent	provider（必須）、capabilities、mode、name、reason、preferred_method、login_hint、binding_message、force_new	エージェントをプロバイダーに接続します。agent_id を返します。

主なパラメーター：

• capabilities — リクエストする機能名の配列です。
• mode — "delegated"（ユーザーに代わって動作する、デフォルト）または "autonomous"（独立して動作する）です。
• preferred_method — "device_authorization"（デフォルト。ブラウザーを開きます）または "ciba"（バックチャネル通知）です。
• login_hint — CIBA フローで使用するユーザーのメールアドレスです。
• force_new — 既存の接続がある場合でも、新しい接続を作成します。

ステップ 4：エージェントを使用する

ツール	パラメーター	使用する場面
execute_capability	agent_id、capability（必須）、arguments	許可された機能を実行します。
agent_status	agent_id（必須）	エージェントのステータス、許可、制約を確認します。
sign_jwt	agent_id（必須）、capabilities、audience	手動で使用するエージェント JWT に署名します。
request_capability	agent_id、capabilities（必須）、reason、preferred_method、login_hint、binding_message	追加の機能をリクエストします。
disconnect_agent	agent_id（必須）	エージェントを失効させます。
reactivate_agent	agent_id（必須）	期限切れのエージェントを再有効化します。

ホスト管理

ツール	パラメーター	使用する場面
enroll_host	provider、enrollment_token（必須）、name	ワンタイムトークンでホストを登録します。
rotate_agent_key	agent_id（必須）	エージェントのキーペアをローテーションします。
rotate_host_key	issuer（必須）	プロバイダーのホストキーペアをローテーションします。

ワークフローの例

プロバイダーに接続して機能を実行する標準的なワークフローは次のとおりです。

1. list_providers
   → See what providers are already known

2. search_providers({ intent: "deploy web apps" })
   → Find a provider if none are known (or discover_provider with a URL)

3. list_capabilities({ provider: "https://api.example.com" })
   → See what the provider offers

4. describe_capability({ name: "deploy_app", provider: "https://api.example.com" })
   → Understand the input schema before executing

5. connect_agent({ provider: "https://api.example.com", capabilities: ["deploy_app"], name: "deploy-bot" })
   → Authenticate and get an agent_id
   → If approval is required, the user will be prompted

6. agent_status({ agent_id: "..." })
   → Confirm the agent is active and capabilities are granted

7. execute_capability({ agent_id: "...", capability: "deploy_app", arguments: { app: "my-app", env: "production" } })
   → Run the capability with the correct arguments

重要なルール

• Agent Auth エンドポイントに生の HTTP リクエストを送信しないでください。 常に MCP ツールを使用してください。
• 必ず最初に list_providers を呼び出してください。 これにより、すでに構成されている内容を確認できます。
• 必ず execute_capability の前に describe_capability を呼び出してください。 入力スキーマが必要です。
• connect_agent の後には必ず agent_status を呼び出してください。 エージェントは承認待ちの場合があります。
• connect_agent が返す agent_id を保存してください。以降のすべてのツールで必要になります。
• エージェントの権限を制限するには、接続時に制約を使用してください。capabilities パラメーターに、name と constraints フィールドを含むオブジェクトとして渡します。
• 承認フローに対応してください。 connect_agent が承認情報（デバイスコード URL または CIBA）を返した場合、エージェントが有効になる前にユーザーが承認する必要があります。agent_status をポーリングして確認してください。
• エラーは { error: "message", code: "error_code" } のような構造化オブジェクトを返します。内容を確認し、再試行するか、適宜調整してください。

機能の制約

接続時に、機能に制約を設定してエージェントが実行できることを制限できます。

{
  "provider": "https://api.example.com",
  "capabilities": [
    "read_data",
    {
      "name": "transfer_money",
      "constraints": {
        "amount": { "max": 1000, "min": 1 },
        "currency": { "in": ["USD", "EUR"] }
      }
    }
  ]
}

制約の種類：eq（完全一致）、min／max（数値の範囲）、in／not_in（許可／ブロックする値）。

CLI と MCP の使い分け

• MCP ツールを使用する場合：MCP 対応環境（Cursor、Claude Code、Claude Desktop）内で操作するときです。ツールはすでに利用可能で、統合されています。
• CLI を使用する場合：ターミナルから直接実行するとき、スクリプトを使うとき、または MCP が利用できないときです。
• どちらも同じ操作を提供し、同じストレージ（~/.agent-auth/）を共有します。