Alternative Payments

Alternative Payments MCP サーバー

AI アシスタントに、Alternative Payments の顧客、請求書、支払いリクエスト、取引、支払い、Webhook への読み取りと安全な書き込みアクセスを提供する Model Context Protocol（MCP） サーバーです。

Wyre Technology がメンテナンスしています。

機能

このサーバーでは、意図的に資金を移動しません。読み取りと安全な書き込み（顧客、請求書、ホスト型の支払いリンクの作成）を提供します。カードや銀行口座に請求を行う直接的な支払い作成（POST /payments）は実装していません。

破壊的な操作を行う3つのツール（ap_archive_customer、ap_archive_invoice、ap_delete_webhook）は、実行前に対話形式での確認が必要です。

ドメイン	ツール
顧客	ap_list_customers、ap_get_customer、ap_list_customer_users、ap_create_customer、ap_add_customer_user、ap_archive_customer ⚠
請求	ap_list_invoices、ap_get_invoice、ap_get_invoice_payment_link、ap_get_invoice_pdf_link、ap_create_invoice、ap_create_payment_request、ap_get_payment_request、ap_archive_invoice ⚠
支払い	ap_list_transactions、ap_get_transaction、ap_list_payouts、ap_get_payout、ap_list_payout_transactions
Webhook	ap_list_webhooks、ap_list_webhook_events、ap_create_webhook、ap_retry_webhooks、ap_delete_webhook ⚠

さらに、探索ツール ap_navigate と ap_status もあります。

認証

Alternative Payments はOAuth 2.0 クライアントクレデンシャルを使用します。Partner Dashboard で API キー（client_id / client_secret）を生成してください。

.env.example をコピーします。stdio トランスポートは以下の環境変数を読み取り、CONDUIT_S2S_SECRET は使用しません。

• ALTERNATIVE_PAYMENTS_CLIENT_ID
• ALTERNATIVE_PAYMENTS_CLIENT_SECRET
• ALTERNATIVE_PAYMENTS_ENVIRONMENT（production または demo、既定値は production）

サーバーはこれらを使用してベアラートークンを自動的に取得し、有効期限が切れる前に更新します。

HTTP サービス間認証

MCP_TRANSPORT=http の場合、CONDUIT_S2S_SECRET が必要です。値が空、または既知のプレースホルダー（changeme、your-s2s-secret、secret、placeholder、その他のサンプル値）の場合、プロセスはエラーをログに記録し、ゼロ以外の終了コードで終了します。シークレットが表示されることはありません。この変数が未設定の場合、Compose は起動しません。

シークレットなしで起動するのは、ローカル開発時に限り MCP_ALLOW_INSECURE_DEV=1 を設定してください。プロセスは警告を大きくログに出力し、X-Gateway-S2S を検証せず、127.0.0.1 のみにバインドします。このモードでは、ループバック以外の MCP_HTTP_HOST（0.0.0.0 を含む）は無視され、その上書きについてログに記録されます。プレースホルダーのシークレットは引き続き拒否されます。

実際の CONDUIT_S2S_SECRET が設定されている場合は、MCP_HTTP_HOST が適用されます。MCP_HTTP_HOST が未設定の場合、サーバーは従来の既定値を維持し、0.0.0.0 にバインドします。コンテナーイメージと Compose は 0.0.0.0 および AUTH_MODE=gateway を設定します。前段にプロキシがない場合は、ポートをループバックにバインドして公開してください。

実際のシークレットを設定している場合、すべての /mcp リクエストに次のヘッダーを含める必要があります。

X-Gateway-S2S: t=<unix seconds>,v1=<hex hmac-sha256>

v1 は、CONDUIT_S2S_SECRET をキーとして ASCII 文字列 t=<unix seconds> から生成した HMAC-SHA256 の 16 進数表現です。タイムスタンプはサーバーの時計から300秒以内でなければなりません。ヘッダーがないか無効な場合、ベンダーの認証情報を読み取る前に 401 を返します。

ゲートウェイモード（AUTH_MODE=gateway）

すべての /mcp リクエストに、次のヘッダーも含める必要があります。

• X-Alternative-Payments-Client-ID
• X-Alternative-Payments-Client-Secret
• X-Alternative-Payments-Environment（任意：production または demo）

クライアント ID またはシークレットがないリクエストには 401 が返され、プロセス環境の ALTERNATIVE_PAYMENTS_CLIENT_ID / ALTERNATIVE_PAYMENTS_CLIENT_SECRET にはフォールバックしません。リポジトリに含まれる Compose サービスには、固定のベンダー認証情報は設定されていません。

シングルテナント HTTP（AUTH_MODE=env）

/mcp では引き続き、有効な X-Gateway-S2S ヘッダーが必要です。リクエストにクライアント ID とクライアントシークレットのヘッダーが含まれていない場合、ベンダーの認証情報は ALTERNATIVE_PAYMENTS_* 環境変数から取得されます。

/health は常に 200 を返します。認証は不要で、ベンダーの認証情報も読み取りません。

クイックスタート

Claude Code（CLI）：

claude mcp add alternative-payments \
  -e ALTERNATIVE_PAYMENTS_CLIENT_ID=your-client-id \
  -e ALTERNATIVE_PAYMENTS_CLIENT_SECRET=your-client-secret \
  -- npx -y github:WYRE-AI/alternative-payments-mcp

Docker（HTTP トランスポート、ゲートウェイモード）：

イメージはコンテナ内で 0.0.0.0 をリッスンし、デフォルトで AUTH_MODE=gateway に設定されています。ポートをループバックインターフェースに公開し、S2S シークレットを渡してください。ゲートウェイモードでは、Alternative Payments の認証情報はリクエストごとにヘッダーで渡され、環境変数からは読み取られません。

docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  ghcr.io/wyre-ai/alternative-payments-mcp:latest

Compose は CONDUIT_S2S_SECRET が未設定の場合、起動を拒否します。また、AUTH_MODE=gateway を設定し、127.0.0.1:8080:8080 を公開します。ベンダーの認証情報は固定値として渡しません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

ゲートウェイは各 /mcp 呼び出しに署名します。

t=$(date +%s)
sig=$(printf 't=%s' "$t" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS -X POST http://127.0.0.1:8080/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "X-Gateway-S2S: t=${t},v1=${sig}" \
  -H "X-Alternative-Payments-Client-ID: $ALTERNATIVE_PAYMENTS_CLIENT_ID" \
  -H "X-Alternative-Payments-Client-Secret: $ALTERNATIVE_PAYMENTS_CLIENT_SECRET" \
  -H "X-Alternative-Payments-Environment: production" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要です。そのうえで、ALTERNATIVE_PAYMENTS_CLIENT_ID と ALTERNATIVE_PAYMENTS_CLIENT_SECRET を使用します。これはゲートウェイの Compose サービスとは別の設定です。

docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e ALTERNATIVE_PAYMENTS_CLIENT_ID="$ALTERNATIVE_PAYMENTS_CLIENT_ID" \
  -e ALTERNATIVE_PAYMENTS_CLIENT_SECRET="$ALTERNATIVE_PAYMENTS_CLIENT_SECRET" \
  ghcr.io/wyre-ai/alternative-payments-mcp:latest

シークレットを使用しないローカル HTTP は、開発環境専用です。127.0.0.1 にバインドし、警告をログに出力します。

MCP_ALLOW_INSECURE_DEV=1 npm run start:http

トランスポート

• stdio（デフォルト）：node dist/index.js。CONDUIT_S2S_SECRET は使用しません。
• HTTP（MCP_TRANSPORT=http）：MCP_HTTP_PORT（デフォルトは 8080）でストリーミング可能な HTTP を使用し、 /mcp と /health のエンドポイントを提供します。リクエストごとに新しいステートレスサーバーが作成されます。 これは WYRE MCP Gateway に必要です。MCP_ALLOW_INSECURE_DEV=1 が設定されていない限り、 CONDUIT_S2S_SECRET に有効なシークレットが設定されるまで、起動時にリッスンを開始しません。

開発

npm install
npm run build
npm test
npm run lint

ライセンス

Apache-2.0