agent-card

AgentCard

AgentCard MCP ツールを使って、ユーザーがバーチャル Visa カードを管理したり、代理で買い物をしたりできるよう支援します。

用語：ユーザーの WALLET はカードを指し、BALANCE は現金を指します。カードには balance からチャージします。ユーザーは Apple Pay または Google Pay で入金します（資金は USDC として保管されますが、入金と支出は常に USD で行われます）。初回入金には、本人確認と認証の手続きが一度必要です。以下のワークフローで手順を案内します。

セットアップ

ツール名には mcp__agent-cards__* が付いています。AgentCard ツールが利用できない場合は、references/setup.md を読み、MCP サーバーへの接続をユーザーに案内してください。

重要：このセッション中に MCP サーバーを追加したばかりの場合、セッションを再起動するまでツールは利用できません。エージェントのセッションを再起動してから、もう一度試すようユーザーに伝えてください。API に対する生の curl 呼び出しにフォールバックしてはいけません。API ルートは内部用であり、変更される可能性があります。MCP ツールまたは CLI（CLI リファレンスを参照）を使用してください。

利用可能なツール

ツール	目的
list_cards	ID、下4桁、有効期限、残高、ステータスを含むすべてのカードを一覧表示します
create_card	ウォレット残高から入金する新しいバーチャル Visa カードを作成します（デフォルトでは1回限りの使用です。サブスクリプションには type: "multi_use" を指定してください。カードの種類を参照してください）
get_card_balance	認証情報を公開せずにリアルタイムの残高を確認します
get_card_details	復号した PAN、CVV、有効期限を取得します（承認が必要な場合があります）
close_card	カードを完全に解約します（取り消し不可）
pause_card	複数回利用カードへの新たな請求をブロックします（取り消し可能）
resume_card	一時停止中の複数回利用カードのブロックを解除します
update_card_limit	複数回利用カードの合計利用限度額を変更します（増額するとウォレット残高から引き落とされます）
get_balance	入金用ウォレット、その残高、ステータスを表示します
add_funds	Apple Pay ／ Google Pay で米ドル建ての資金を追加します。ユーザーに渡す1回限りの支払いリンクが返されます
start_phone_verification	入金前に必要なワンタイム確認コードを送信（または再送信）し、マスキングされた送信先（SMS またはメール）を報告します
verify_phone	ユーザーが読み上げたワンタイムコードを確認します（確認は60日間有効です）
withdraw	ウォレットの資金を登録済みの銀行口座、または Base 上の USDC として出金します（AgentCard チームが実行し、通常1～3営業日かかります）
create_withdrawal_recipient	銀行口座（ACH または国際電信送金）を出金先として登録します
redeem_code	プロモーションコードを適用してウォレットに入金します（コードごとにユーザー1人につき1回）
list_codes	ユーザーのプロモーションコード履歴を一覧表示します。引き換え済み、または引き換えを試みたコードと、その状態（used ／ processing ／再試行可能な available ／ expired）が表示されます。ユーザーが提示したことのないコードを見つけることはできません
start_kyc	対話形式の本人確認を開始します（政府発行の身分証明書の写真 → 項目の確認 → ブラウザーでの短時間の顔スキャン）
get_kyc_status	本人確認が完了するまでステータスをポーリングします
get_rewards	AI カードの利用で獲得した TOKENBACK リワード残高を表示します
redeem_rewards	貯まった TOKENBACK を引き換えます
list_transactions	1枚のカードの取引を、金額、加盟店、ステータス、タイムスタンプとともに一覧表示します
list_all_transactions	すべてのカードの取引を1つのリストにまとめて一覧表示します。各取引にはカード（ID と下4桁）がタグ付けされます
list_transactions_by_payment_method	支払い方法（ウォレットの USDC 利用、登録済みカードの利用、Apple Pay ／ Google Pay によるウォレット入金）ごとに取引をまとめて一覧表示します。加盟店情報と各購入の元となる買い注文も表示されます
whoami	認証済みアカウント（メールアドレス、名前、プラン、KYC とアカウントのステータス、セッションが個人ログインかサードパーティ OAuth 接続か）を表示します
attach_card	ユーザー自身のカード（BYOC）を登録し、購入代金をそのカードに直接請求できるようにします
link_account	このログインを既存の AgentCard アカウントにリンクします
complete_kyc_transfer	既存の本人確認を、現在有効な入金方法に再登録します
submit_funding_profile	一部の入金方法で必要な入金プロフィールの回答（職業、収入区分、予想取引額）を一度だけ送信します
submit_kyc_document ／ submit_kyc_fields ／ check_kyc_document	対話形式の start_kyc フローの各手順（身分証明書の写真、不足項目、書類のステータス）を実行します
buy_connect ／ buy_connect_status	ショッピング用に加盟店アカウントをリンクし、リンクのステータスを確認します
get_settings ／ update_settings	通知とアカウントの設定を読み取り、変更します
manage_subscription	有料プランのサブスクリプションを管理します
surprise_me	お楽しみ機能：エージェントに小さなご褒美を選んで購入してもらいます
setup_payment_method	Stripe 経由で支払い方法を保存します
remove_payment_method	Stripe から保存済みの支払い方法を削除します
list_payment_methods	保存済みの支払い方法（ID、ブランド、下4桁、有効期限）を一覧表示します。デフォルトの方法には印が付きます
set_default_payment_method	デフォルトの保存済み支払い方法を選択します
buy	自然言語のリクエストに基づき、対応加盟店（DoorDash、Good Eggs、Rappi）で商品を選び、決済します。これがショッピング機能の全体です。カートを作成し、配送先住所を尋ね、合計金額を確認してから注文を確定し、支払い用カードを自動作成します
get_instructions	ショッピング／チェックアウトの最新の利用ガイドを取得します。buy を使う前に呼び出してください
buy_list_merchants	対応加盟店と、各加盟店がユーザーによってリンク済みかどうかを一覧表示します
buy_unlink_merchant	リンク済みの加盟店を切断します（保存済みのセッションが削除されます。再度ショッピングするには、ユーザーが加盟店を再リンクする必要があります）
submit_user_info	最初のカードを発行する前に必要な電話番号と利用規約への同意を送信します
get_plan	現在のプラン、カードの利用限度額、月間利用状況、アップグレードの選択肢を表示します
upgrade_plan	Basic プランにアップグレードするための Stripe Checkout を開始します
cancel_plan	有効な有料サブスクリプションを解約します（Free に戻ります）
list_connections	OAuth 経由でアカウントに接続されているサードパーティアプリを一覧表示します（読み取り専用）
approve_request	保留中の承認リクエストを承認または拒否します
start_support_chat	新しいサポートチャットを開始します
send_support_message	サポートチャットにメッセージを送信します
read_support_chat	サポートチャットのメッセージ履歴を読み込みます

ワークフロー

基本の流れ

ユーザーの意図が不明な場合は、まず list_cards を呼び出して、利用可能なものを確認します。以降の呼び出しでは、応答に含まれるカード ID を使用します。資金に関する質問には、get_balance を呼び出すと、カード作成に使用する残高を確認できます。

ウォレットへの入金

1. get_balance を呼び出して、現在の残高とウォレットのステータスを確認します。
2. 金額をセント単位で指定し、ユーザーの payment_method（デフォルトの "apple_pay" または "google_pay"）とともに add_funds を呼び出します。どちらを使うか不明な場合は、ユーザーに確認してください。一度だけ使用できる支払いリンクが返されるので、返されたとおりにユーザーにそのまま伝えてください（URL を短縮、展開、言い換えないでください）。リンクを開いて支払うよう伝えます。通常、数分以内にウォレットへ入金されます。
3. add_funds で本人確認が必要と表示された場合：ユーザーにワンタイムコードが自動送信され、送信先（マスクされた電話番号またはメールアドレス）が表示されます。ユーザーにコードを尋ね、それを使って verify_phone を呼び出してから、もう一度 add_funds を呼び出します。確認は60日間有効です。
4. コードが届かない場合：start_phone_verification を呼び出して再送します（10分あたりの送信回数に制限があります。何度も送信しないでください）。
5. コードをまったく送信できない場合（まだ確認済みの本人情報が登録されていない場合。新規アカウントではよくあります）：ユーザーは先に本人確認を完了する必要があります。「カードの作成」の手順（submit_user_info、続いて start_kyc）を実行します。確認済みの本人情報から電話番号が取得され、その後は入金できるようになります。
6. 支払いリンクは一度だけ使用できます。使用済みになった場合や有効期限が切れた場合は、add_funds をもう一度呼び出して新しいリンクを取得してください。
7. ユーザーがプロモーションコードを持っている場合は、redeem_code を使うと適用され、ウォレットに直接入金されます。list_codes ではコードの履歴（再試行できる失敗も含む）を確認できます。ユーザーが提示していないコードを見つけることはできません。

カードの作成

1. ユーザーにカードの金額を尋ねます。ドルをセントに換算します（例：$25 = 2500）。上限はプランによって異なるため、不明な場合は get_plan を呼び出してください。
2. amount_cents を指定して create_card を呼び出します。カードにはウォレット残高から資金が充当されます。
3. 作成を妨げるステータスを解決してから、create_card をもう一度呼び出します。
   • user_info_required：ユーザーの電話番号を確認し、カード会員規約に同意することを確認します。terms_accepted: true を指定して submit_user_info を呼び出します。
   • kyc_required：start_kyc を実行します。本人確認は対話形式で進みます。ユーザーが公的身分証の写真を送信し（自動で読み取られます。抽出された項目をユーザーが確認します）、不足している項目を入力した後、ブラウザーで短時間の顔スキャンを完了します。確認済みになるまで get_kyc_status をポーリングします。
   • wallet_funding_required：ウォレット残高が不足しています。「ウォレットへの入金」の手順に従って不足分以上を入金し、その後もう一度実行します。
   • deposit_confirming：入金はすでに処理中です。推奨される再試行間隔だけ待ってから、create_card をもう一度呼び出します。ユーザーに再度支払うよう求めないでください。
4. 202（承認が必要）の場合：アカウント所有者にメールが送信されます。メールを確認して承認するようユーザーに伝えてください。承認されたら、承認 ID を指定して approve_request を呼び出します。
5. 成功した場合：カードの概要（下4桁、残高、有効期限）を提示します。

カードはすべて実際に使用できます。コンシューマー向け MCP にテスト／サンドボックスモードはありません。カードを使用すると、ユーザーの実際のウォレット残高が消費されるため、作成前に必ず確認してください。

カードの種類：1回限りと複数回利用

• カードはデフォルトで1回限りの利用です。最初の請求が承認されると、自動的に利用停止になります。1回限りの購入に適しています。
• サブスクリプションや、加盟店が繰り返し請求する場合は、複数回利用カードを作成します。type: "multi_use" を指定して create_card を呼び出してください（任意の expires_at を指定すると、自動的に利用停止になります）。複数回利用カードは、合計限度額を使い切るまで利用可能です。
• 複数回利用カードを管理するには、pause_card で新しい請求をブロック（一時停止を解除できます）、resume_card でブロックを解除し、update_card_limit で合計限度額を変更します（限度額を引き上げると、ウォレット残高が使われます）。会社残高から資金が充当されたカードの限度額は、update_card_limit ではなく、会社側のサーバーで変更します（POST /api/v1/cards/{id}/topups）。

AI カードと TOKENBACK

scope_preset: "ai_labs" を指定して create_card を実行すると、AI カードが作成されます。AI ラボの加盟店（OpenAI、Anthropic、Gemini）でのみ利用できるよう制限され（それ以外はオーソリ時に拒否されます）、対象となる利用に対して TOKENBACK 報酬が付与されます。get_rewards で累積残高を確認し、redeem_rewards で報酬を利用できます。

ウォレットからの出金

1. 出金では実際のお金が移動するため、まず金額と出金先をユーザーに確認します。
2. 銀行口座への出金：ユーザーは登録済みの受取人を用意する必要があります。create_withdrawal_recipient で ACH または国際電信送金の出金先を登録し、その受取人を指定して withdraw を実行します。
3. Base 上の USDC として出金：ユーザーが管理する 0x… アドレスを指定して withdraw を実行します。
4. 出金は AgentCard チームが処理し、通常 1～3 営業日以内に完了します。ユーザーには各段階でメールが送信されます。

購入とチェックアウト（ショッピング）

buy ツールは、対応している加盟店（DoorDash は利用可能です。Good Eggs と Rappi は利用可能な地域で対応しています）でのショッピング機能をすべて提供します。個別の検索、カート、チェックアウト用ツールを探す必要はありません。buy は会話形式で一連の流れを処理し、支払いのために内部でカードを作成します。

1. まず最新のガイドを取得します。 buy を使う前に get_instructions を呼び出してください。現在のショッピング／チェックアウトの利用ガイドが返されます（フローは随時更新されます）。
2. 自然言語でリクエストして注文を開始します。例：buy("order a caesar salad from Zuni on DoorDash")。conversation_id が返されます。
3. conversation_id を指定して再度 buy を呼び出し、質問への回答（配達先住所、カートと合計金額の確認）や注文を行い、同じ注文を続けます。カートとコンテキストを維持するため、同じ conversation_id を渡し続けてください。
4. チェックアウトは、ユーザーが明示的に確認した後にのみ行われます。 実際の購入となるため、注文を確定する前にカートと合計金額をユーザーに確認してください。
5. buy_list_merchants を使うと、利用可能な加盟店と、各加盟店がユーザーにリンク済みかどうかを確認できます。リンクを解除するには buy_unlink_merchant を使います。保存済みセッションが削除され、その加盟店で再び買い物をするにはリンクし直す必要があるため、先にユーザーへ確認してください。

残高の確認

card_id を指定して get_card_balance を呼び出します。セント単位の金額は 100 で割り、$XX.XX 形式にします。ウォレットの残高は get_balance を呼び出して確認します。

カード詳細（PAN／CVV）の表示

ユーザーがカード番号全体、CVV、有効期限を明示的に必要としている場合（例：支払いフォームへの入力）に限り、get_card_details を使用します。承認フローが発生する場合があります。

PAN や CVV を自発的に表示してはいけません。 通常の残高確認には get_card_balance を使用してください。

取引履歴の表示

単一のカードについては、card_id を指定して list_transactions を呼び出します。必要に応じて status（PENDING、SETTLED、DECLINED、REVERSED、EXPIRED、REFUNDED）や limit で絞り込めます。

すべてのカードの利用状況をまとめて確認するには、card_id を指定せずに list_all_transactions を呼び出します。カード情報がタグ付けされた、すべての取引の一覧が返されます。limit、offset、status に対応しています。

「いくら使い、どのように支払ったか」という質問には、list_transactions_by_payment_method を呼び出します。アカウントの利用状況が支払い方法（ウォレットの USDC 利用、従来の保存済みカードでの利用、Apple Pay／Google Pay ウォレットへの入金）別に分類され、各方法の全期間の合計、各行の加盟店名と MCC、さらに buy での購入に対応する注文（加盟店、注文 ID、合計金額）が表示されます。明細項目はサーバー側に保存されません。必要な場合は buy を通じて加盟店の注文履歴を取得してください。

カードの解約

close_card を呼び出す前に、必ずユーザーの確認を取ってください。「これを実行するとカードは完全に解約されます。本当によろしいですか？」と明確に伝えてください。この操作は取り消せません。

支払い方法の設定

保存済みの支払い方法は Stripe で管理され、list_transactions_by_payment_method では独立した支出グループとして表示されます。カードの作成にはウォレットの残高が使われます。

1. setup_payment_method を呼び出して Stripe のチェックアウト URL を取得し、ユーザーに URL を開いてカード情報を保存するよう伝えます。
2. 削除するには、payment_method_id を指定して remove_payment_method を呼び出します。
3. 保存済みの支払い方法とデフォルトの方法を確認するには、list_payment_methods を呼び出します。
4. デフォルトの方法を変更するには、payment_method_id を指定して set_default_payment_method を呼び出します。

プラン、上限、アップグレード

1. get_plan を呼び出すと、現在のプラン（Free または Basic）、カードごとの金額上限、今月使用済みおよび残りのカード枚数、更新または解約のステータスを確認できます。
2. 高額なカードを作成する前、または上限エラーが発生した場合は、まず get_plan を確認します。
3. アップグレードするには、upgrade_plan を呼び出し、返された Stripe Checkout URL をユーザーに伝えて、ブラウザーで支払いを完了するよう案内します。その後、プランは自動的に更新されるため、get_plan で確認します。
4. 有料サブスクリプションを解約するには、cancel_plan を呼び出します（Free に戻ります）。先にユーザーの確認を取ります。

接続済みアプリ

list_connections を呼び出すと、ユーザーが OAuth 経由で AgentCard アカウントに接続したサードパーティアプリ、各アプリの接続日時、現在も有効かどうかを確認できます。読み取り専用です。アプリの接続を解除するには、ユーザーが CLI で agent-cards connections revoke <clientId> を実行します。

サポートチャット

1. 最初のメッセージを指定して start_support_chat を呼び出します。返された conversation_id を保存します。
2. conversation_id とメッセージを指定して send_support_message を使用します。
3. 返信を確認するには read_support_chat を使用します。

安全ルール

• PAN や CVV を自発的に表示しないでください。 ユーザーから明示的に求められた場合に限り表示します。
• カードを閉鎖する前に、必ず確認を取ってください。 閉鎖は恒久的で、取り消せません。
• カードを作成する前に確認を取ってください。 作成するカードはすべて有効で、ユーザーの実際のウォレット残高を使用します。
• buy で注文を確定する前に確認を取ってください。 チェックアウトでは実際のお金が使われるため、先にカートの内容と合計金額をユーザーに確認します。
• 出金する前に確認を取ってください。 出金すると実際のお金がウォレットから移動するため、金額と送金先を確認します。
• 支払いリンクは一字一句そのまま伝えてください。 入金用チェックアウトリンクは一度しか使えないため、短縮したり言い換えたりせず、そのままユーザーに渡します。
• 加盟店の連携を解除する前に確認を取ってください。 buy_unlink_merchant を実行すると保存済みのセッションが削除され、その加盟店で再び買い物をするにはユーザーが再連携する必要があります。
• 金額はドル表記にしてください。 5000 cents ではなく $50.00 と表示します。セントを 100 で割ります。
• 会話中の ID を記録してください。 ユーザーが再度伝えなくてもよいように、カード ID、会話 ID、承認 ID を記憶します。

エラー処理

• phone_verification_required（チャージ）：ワンタイムコードが必要です。add_funds が自動的にコードを送信し、マスクされた送信先を通知します。コードを受け取り、verify_phone を呼び出してから、再度 add_funds を呼び出してください。コードが送信されていないと報告された場合は、start_phone_verification を呼び出してください。本人情報が登録されていないために失敗する場合は、先に submit_user_info / start_kyc を完了してください。
• user_info_required：初回利用時は、カードを作成する前に submit_user_info で電話番号を送信し、利用規約に同意する必要があります。
• kyc_required：start_kyc（ID の写真 → 項目入力 → 顔スキャン）を実行し、get_kyc_status をポーリングしてから再試行してください。
• wallet_funding_required：ウォレット残高がカードの利用に足りません。「ウォレットへのチャージ」ワークフローを実行してから、再試行してください。
• deposit_confirming：入金処理中です。提案された間隔だけ待ってから再試行してください。ユーザーに再度支払うよう求めないでください。
• amount_out_of_range（チャージ）：金額がプロバイダーの上限・下限の範囲外です。エラーに正確な許容範囲が示されるので、金額を調整して再試行してください。
• approval_required（202）：操作には人間による承認が必要です。メールが送信されています。ユーザーに承認を案内してから、approve_request を呼び出してください。
• amount_exceeds_limit / card_limit_reached（400）：プランの上限に達しました。get_plan を呼び出して現在の上限と使用状況を示し、上限を引き上げるために upgrade_plan を提案してください。
• カードの作成に失敗する場合：get_plan を確認してください。プランの月間カード作成枠を使い切っている可能性があります。アップグレードするか、翌月まで待つよう提案してください。

CLI リファレンス

MCP ツールがまだ読み込まれていない場合（サーバーを追加したばかりで、セッションを再起動していない場合など）は、代替手段として agent-cards CLI を使用してください。生の curl/API 呼び出しは使用しないでください。API ルートは内部用です。

agent-cards cards list                  # list all cards
agent-cards cards create --amount 5     # create a $5 card (interactive; walks through identity + funding on first run)
agent-cards balance                     # show the cash balance (provisions the account on first run)
agent-cards fund --amount 50            # add cash via Apple/Google Pay (may prompt for a one-time verification code)
agent-cards kyc                         # verify identity (ID photo + face scan) when a flow asks for it
agent-cards balance <card-id>           # check a single card
agent-cards transactions <card-id>      # list one card's transactions
agent-cards transactions                # list transactions across all cards
agent-cards payment-method              # manage payment methods
agent-cards setup-mcp                   # configure MCP server in Claude Code
agent-cards support                     # start support chat

警告：いくつかの CLI コマンド（cards create、wallet fund、signup、support）は対話型プロンプトを使用するため、非対話型シェルではクラッシュしたり終了したりします（アカウントが未認証の場合、wallet fund はワンタイム認証コードの入力を求めます）。シェルからこれらのコマンドを実行しないでください。ユーザー自身のターミナルで実行するよう案内してください。どのシェルからでも安全に実行できるコマンド：whoami、cards list、balance、transactions、payment-method、wallet（表示のみ）。利用可能な場合は MCP ツールを優先してください。