interswitch-mcp-server

Interswitch MCP サーバー

Model Context Protocol (MCP) サーバーです。AI アシスタントが、決済、送金、VAS、カードレス決済コード、Transaction Search、Card 360、融資、支払い処理、代理店バンキング、フィンテックのカード処理ユーティリティ向けの Interswitch APIs と連携できるようにします。

警告

パブリックプレビュー： この MCP サーバーは現在、パブリックプレビュー中です。Interswitch のサンドボックス環境と本番環境の両方に対応しているため、慎重に使用し、まず読み取り専用モードで開始し、発生した問題を報告してください。

クイックスタート

npm でインストールして実行します（推奨）：

npx interswitch-mcp-server

または、グローバルにインストールします：

npm install -g interswitch-mcp-server
interswitch-mcp-server

または、ローカル開発の場合は、クローンしてビルドします：

git clone https://github.com/Dairus01/Interswitch-mcp-server.git
cd Interswitch-mcp-server
npm install
npm run build

次に、MCP クライアントがこのサーバーを使用するように設定します（クライアント統合を参照）。

要件

• Node.js v18+
• npm または yarn
• 使用するドメインの Interswitch API 認証情報
• ユースケースに応じて必要となる Interswitch の加盟店、支払い可能対象、開始エンティティ、端末、またはドメイン固有の識別子

設定オプション

環境変数	用途
INTERSWITCH_CLIENT_ID	決済、送金、VAS、カードレス、融資、送金サービス、支払い処理向けのコア OAuth2 クライアント ID
INTERSWITCH_CLIENT_SECRET	コア OAuth2 クライアントシークレット
INTERSWITCH_ENV	API 環境：sandbox または production。デフォルトは sandbox です
INTERSWITCH_READ_ONLY	true に設定すると、API 呼び出しの前に書き込みツールをブロックします。デフォルトは false です
INTERSWITCH_REQUIRE_CONFIRMATION	互換性設定です。ツールの確認はツールのモードとリスクに基づいて適用されます
INTERSWITCH_MERCHANT_CODE	必要とする決済処理向けの加盟店コード
INTERSWITCH_PAYABLE_CODE	必要とする決済処理向けの支払い可能コード
INTERSWITCH_INITIATING_ENTITY_CODE	送金処理向けの開始エンティティコード
INTERSWITCH_TERMINAL_ID	端末の識別が必要な処理向けの端末 ID
CARD360_CLIENT_ID	Card 360 専用のクライアント ID
CARD360_CLIENT_SECRET	Card 360 専用のクライアントシークレット
CARD360_RSA_PUBLIC_KEY	Card 360 の PIN ペイロードをローカルで暗号化するために使用する RSA 公開鍵
TRANSACTION_SEARCH_CLIENT_ID	Transaction Search 専用のクライアント ID
TRANSACTION_SEARCH_CLIENT_SECRET	Transaction Search 専用のクライアントシークレット
INTERSWITCH_AGENCY_MERCHANT_ID	代理店バンキングの加盟店識別子
INTERSWITCH_AGENCY_TERMINAL_ID	代理店バンキングの端末識別子
INTERSWITCH_LEGACY_AUTH_ENABLED	対応している場合、従来の InterswitchAuth を利用するフローを有効にします
DEBUG	デバッグログを有効にします。本番環境では使用しないでください。

INTERSWITCH_ENV で API 環境を選択できます。

1. サンドボックス（デフォルト）： INTERSWITCH_ENV=sandbox
2. 本番： INTERSWITCH_ENV=production

セキュリティに関する注意： 本番モードでは、Interswitch の実際の本番エンドポイントを使用します。INTERSWITCH_ENV=production が設定され、有効な本番認証情報が構成され、INTERSWITCH_READ_ONLY=false で、書き込みツールの呼び出し時に confirm: true が指定されている場合、サーバーは実際の本番 API 呼び出しを実行できます。

初めての設定をより安全に行うため、まず読み取り専用モードで開始してください。

INTERSWITCH_ENV=production \
INTERSWITCH_READ_ONLY=true \
INTERSWITCH_CLIENT_ID=your_production_client_id \
INTERSWITCH_CLIENT_SECRET=your_production_client_secret \
interswitch-mcp-server

承認を得て、実際の書き込みを許可する準備ができたら、次のように設定します。

INTERSWITCH_READ_ONLY=false

クライアント統合

Interswitch MCP サーバーは、MCP 互換クライアントであればどれでも動作します。以下は、ほとんどのクライアント（Claude Desktop、ChatGPT Desktop、Cursor、Windsurf、VS Code、Claude Code など）で使用される標準設定スキーマです。

npm を使用する（推奨）

npm でインストールしたサーバーの場合：

{
  "mcpServers": {
    "interswitch": {
      "command": "npx",
      "args": ["-y", "interswitch-mcp-server"],
      "env": {
        "INTERSWITCH_ENV": "sandbox",
        "INTERSWITCH_READ_ONLY": "true",
        "INTERSWITCH_CLIENT_ID": "your_client_id",
        "INTERSWITCH_CLIENT_SECRET": "your_client_secret",
        "INTERSWITCH_MERCHANT_CODE": "your_merchant_code",
        "INTERSWITCH_PAYABLE_CODE": "your_payable_code",
        "INTERSWITCH_INITIATING_ENTITY_CODE": "your_entity_code"
      }
    }
  }
}

本番環境では、環境変数の値を意図的に変更してください。

{
  "mcpServers": {
    "interswitch": {
      "command": "npx",
      "args": ["-y", "interswitch-mcp-server"],
      "env": {
        "INTERSWITCH_ENV": "production",
        "INTERSWITCH_READ_ONLY": "true",
        "INTERSWITCH_CLIENT_ID": "your_production_client_id",
        "INTERSWITCH_CLIENT_SECRET": "your_production_client_secret",
        "INTERSWITCH_MERCHANT_CODE": "your_production_merchant_code",
        "INTERSWITCH_PAYABLE_CODE": "your_production_payable_code",
        "INTERSWITCH_INITIATING_ENTITY_CODE": "your_production_entity_code"
      }
    }
  }
}

ローカルビルドを使用する

サーバーをローカルにクローンしてビルドした場合：

{
  "mcpServers": {
    "interswitch": {
      "command": "node",
      "args": ["/path/to/Interswitch-mcp-server/dist/index.js"],
      "env": {
        "INTERSWITCH_ENV": "sandbox",
        "INTERSWITCH_READ_ONLY": "true",
        "INTERSWITCH_CLIENT_ID": "your_client_id",
        "INTERSWITCH_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

重要

command: "node" を設定する場合は、Node v18 以降を使用していることを確認してください。パッケージマネージャーを使用している場合は、CLI で次のコマンドを実行して、Node バイナリのパスを取得する必要がある場合があります。

Linux および MacOS

which node

Windows

where node

パスを取得したら、JSON 設定の MCP サーバーコマンドの値として使用します。例：command: "path/to/installation/bin/node"

この設定を追加する場所

クライアント	設定ファイルの場所
VS Code	.vscode/mcp.json
Claude Desktop	claude_desktop_config.json
ChatGPT Desktop	アプリの環境設定にある MCP 設定
Cursor	.cursor/mcp.json またはグローバル MCP 設定
Windsurf	設定内の MCP 設定
Claude Code	~/.claude/mcp.json またはプロジェクトレベルの .mcp.json

仕組み

Interswitch MCP サーバーは、専用の MCP ツールを通じて Interswitch API の各ドメインを AI アシスタントに公開します。このサーバーは実行時に OpenAPI ファイルを解析するのではなく、サポート対象の Interswitch ドメイン向けに厳選された、型付きのツールを提供します。

アーキテクチャ図

graph TD
    subgraph MCP Server
        A[Interswitch MCP Server]
        B[Tool Registry]
        C[Resource Registry]
    end

    subgraph Auth Layer
        D[OAuth2 Passport Manager]
        E[Card 360 Token Manager]
        F[Transaction Search Manager]
        G[Agency Banking Token Manager]
        H[Legacy Auth Manager]
    end

    subgraph Core Services
        I[Payments Service]
        J[VAS Services]
        K[Transfers Service]
        L[Cardless Services]
        M[Transaction Search Service]
        N[Card 360 Service]
        O[Lending Service]
        P[Transfer Service]
        Q[Payouts Service]
        R[Agency Service]
        S[Fintech Utilities]
    end

    subgraph Safety Layer
        J1[Confirmation Gate]
        J2[Read-Only Mode]
        J3[Redaction System]
        J4[Audit Logging]
    end

    A --> B
    A --> C
    A --> D
    A --> E
    A --> F
    A --> G
    A --> H
    B --> I
    B --> J
    B --> K
    B --> L
    B --> M
    B --> N
    B --> O
    B --> P
    B --> Q
    B --> R
    B --> S
    I --> J1
    J --> J1
    K --> J1
    L --> J1
    M --> J1
    N --> J1
    O --> J1
    P --> J1
    Q --> J1
    R --> J1
    S --> J1
    J1 --> J2
    J2 --> J3
    J3 --> J4
    J4 --> Z[External APIs]
    
    style MCP Server fill:#f0f8ff,stroke:#333,stroke-width:2px
    style Auth Layer fill:#e6f7e6,stroke:#333,stroke-width:1px
    style Core Services fill:#f9f9f9,stroke:#666,stroke-width:1px
    style Safety Layer fill:#fff0f0,stroke:#c33,stroke-width:1px
    style Z fill:#d4d4d4,stroke:#999,stroke-dasharray: 5 5

各ツールは次の処理を行います。

1. 厳密なスキーマで入力を検証します
2. 確認および読み取り専用の安全性チェックを適用します
3. 設定されたサンドボックスまたは本番環境のベース URL を選択します
4. ドメインに適した認証システムを使用します
5. ツールが呼び出された場合にのみ Interswitch API を呼び出します
6. 返されるデータから機密フィールドをマスキングします
7. 正規化された MCP レスポンスを返します

認証システム

認証システム	用途
OAuth2 Passport	コア決済、送金、VAS、カードレス、融資、送金サービス、および支払い
Card 360 token manager	Card 360 の操作
Transaction Search token manager	Transaction Search API
Legacy InterswitchAuth	有効化されている場合のレガシー署名付きリクエストフロー
Agency Banking token manager	Agency Banking の SOAP/XML トークンフロー

利用可能なツール

ツール	説明
isw_initialize_payment	支払いリクエストを初期化します
isw_get_transaction_status	取引のステータスを確認します
isw_get_transaction_by_reference	参照番号で取引を取得します
isw_create_payment_link	支払いリンクを作成します
isw_initiate_refund	返金を開始します。高リスクな書き込み操作です
isw_get_refund_status	返金のステータスを確認します
isw_pay_bill	請求書を支払います
isw_get_billers	請求事業者の一覧を取得します
isw_get_biller_packages	請求事業者のパッケージ一覧を取得します
isw_get_billers_by_category	カテゴリー別に請求事業者の一覧を取得します
isw_get_biller_details	請求事業者の詳細を取得します
isw_validate_customer	請求事業者の顧客を検証します
isw_pay_vas_bill	VAS の請求書を支払います
isw_airtime_recharge	エアタイムをチャージします
isw_get_airtime_epins	エアタイムの ePIN をリクエストします
isw_single_transfer	単一の銀行振込を実行します。高リスクな書き込み操作です
isw_bulk_transfer	一括振込を実行します。高リスクな書き込み操作です。最大 100 件の取引に対応します
isw_resolve_bank_account	銀行口座の詳細を解決します
isw_get_bank_codes	対応する銀行コードの一覧を取得します
isw_agency_banking_cashout	エージェントバンキングの現金引き出しを開始します。高リスクな書き込み操作です
isw_create_paycode	カード不要のペイコードを作成します
isw_create_bulk_paycodes	ペイコードを一括作成します。高リスクな書き込み操作です。最大 100 件のペイコードに対応します
isw_get_paycode_status	ペイコードのステータスを確認します
isw_deactivate_paycode	ペイコードを無効化します
isw_transaction_search_quick_search	クイック検索フィールドで取引を検索します
isw_transaction_search_reference_search	取引の参照番号で検索します
isw_transaction_search_bulk_search	複数の取引を検索します
isw_get_transaction_details	取引の詳細情報を取得します
isw_create_card	カードを作成します。高リスクな書き込み操作です
isw_retry_card_creation	カードの作成を再試行します
isw_initiate_card_data_prep	カードデータの準備を開始します
isw_fetch_data_prep_request	データ準備リクエストを取得します
isw_fetch_prepared_cards	準備済みカードを取得します
isw_bulk_card_production	カードの一括発行を開始します。高リスクな書き込み操作です
isw_reissue_card_pin	カード PIN を再発行します。高リスクな書き込み操作です
isw_change_card_pin	カード PIN を変更します。高リスクな書き込み操作です
isw_get_pin	対応している場合、PIN 関連の応答を取得します。高リスクな読み取り操作です
isw_block_card	カードを停止します。高リスクな書き込み操作です
isw_unblock_card	カードの停止を解除します。高リスクな書き込み操作です
isw_block_prepaid_card	プリペイドカードを停止します。高リスクな書き込み操作です
isw_unblock_prepaid_card	プリペイドカードの停止を解除します。高リスクな書き込み操作です
isw_link_card_to_account	カードを口座に紐付けます。高リスクな書き込み操作です
isw_check_prepaid_balance	プリペイドカードの残高を確認します
isw_check_debit_balance	デビットカードの残高を確認します
isw_confirm_prepaid_sufficient	プリペイドカードの残高が十分であることを確認します
isw_confirm_debit_sufficient	デビットカードの残高が十分であることを確認します
isw_fetch_cards_by_issuer	発行会社別にカードを取得します
isw_fetch_single_card_by_pan	PAN を指定して単一のカードを取得します（マスキングあり）
isw_fetch_cards_by_account	口座別にカードを取得します
isw_fetch_customer_card_details	顧客のカード詳細を取得します
isw_fetch_request_logs	Card 360 のリクエストログを取得します
isw_validate_card	カードデータを検証します
isw_request_nano_loan	少額融資をリクエストします。高リスクな書き込み操作です
isw_salary_lending	給与貸付のフローを開始します。高リスクな書き込み操作です
isw_value_financing	バリューファイナンスのフローを開始します。高リスクな書き込み操作です
isw_get_customer_demographics	顧客の人口統計情報を取得します
isw_get_financial_history	顧客の財務履歴を取得します
isw_get_financial_history_average	財務履歴の平均値を取得します
isw_get_financial_habits	顧客の財務習慣を取得します
isw_credit_inquiry	信用照会を実行します
isw_complete_credit	OTP を使用して信用取引を完了します。高リスクな書き込み操作です
isw_requery_transfer	振込のステータスを再照会します
isw_get_receiving_institutions	支払い先金融機関の一覧を取得します
isw_get_payout_channels	支払いチャネルの一覧を取得します
isw_agency_get_token	Agency Banking トークンを取得／キャッシュします
isw_fintech_validate_debit_payload	デビットのペイロード構造を検証します
isw_fintech_validate_reversal_payload	取消のペイロード構造を検証します
isw_fintech_validate_enquiry_payload	照会のペイロード構造を検証します
isw_fintech_validate_place_lien_payload	リエン設定のペイロード構造を検証します
isw_fintech_validate_debit_lien_payload	リエン引き落としのペイロード構造を検証します
isw_fintech_compute_mac	MAC を計算します。シークレットを受け取るため、高リスクです
isw_fintech_build_response	フィンテックの応答ペイロードを構築します。シークレットが指定された場合は高リスクです

利用可能なリソース

リソース	URI	説明
response_codes	isw://response-codes	Interswitch の一般的なレスポンスコードのリファレンス
config_summary	isw://config-summary	安全なランタイム設定の概要。認証情報の有無のみを返し、秘密情報は一切返しません

例

AI アシスタントに 「Interswitch を使って [email protected] の支払いを 5000 NGN で開始して」 のように依頼すると、内部では次のように処理されます。

1. アシスタントが isw_initialize_payment を選択します
2. amountNaira: 5000 のような明示的な金額入力を渡します
3. 書き込み操作では、confirm: true を含める必要があります
4. サーバーがリクエストを検証し、必要に応じて金額を安全に変換し、Interswitch で認証して、設定されたサンドボックスまたは本番環境のエンドポイントを呼び出します
5. 生データがマスキングされた、正規化済みのレスポンスが返されます

プロンプトの推奨事項

この MCP サーバーを使用する際に最良の結果を得るには、プロンプトを具体的にし、リクエストには必ず「Interswitch」を含めてください。

効果的なプロンプト：

• 「[email protected] のユーザーに 50000 NGN の Interswitch 支払いを開始してください。」
• 「参照番号 order-1001 の Interswitch 取引ステータスを確認してください。」
• 「銀行コード 058 で Interswitch の銀行口座 0123456789 を照会してください。」
• 「confirm true で 1000 NGN の Interswitch 単一振込を送信してください。」
• 「Interswitch のレスポンスコードのリソースを読み取ってください。」

あまり効果的でないプロンプト：

• 「自分の取引を一覧表示して」（どのサービスを使うのか、どの参照情報や検索条件を使うのかが不明確です）
• 「送金して」（受取人、銀行、金額、確認情報がありません）
• 「この請求書を支払って」（請求元、パッケージ、顧客、金額の情報がありません）

明示的に指定すると、LLM が適切なツールをすばやく特定し、曖昧さを減らせます。

本番環境の安全性

このサーバーは、INTERSWITCH_ENV=production が設定されている場合、本番環境の Interswitch エンドポイントにルーティングできます。本番環境での使用準備には、正しい認証情報、Interswitch アカウントの権限、組織の運用管理体制が必要です。

サーバーに組み込まれている安全対策：

• 書き込みツールには confirm: true が必要です
• 高リスクの機密読み取りツールには confirm: true が必要です
• INTERSWITCH_READ_ONLY=true にすると、外部 API 呼び出しの前にすべての書き込みがブロックされます
• 低リスクの読み取りには確認が不要です
• 生のレスポンスは返却前にマスキングされます
• トークンや秘密情報がツールの出力に意図的に含まれることはありません
• 必要な RSA 公開鍵が設定されている場合、カード PIN のペイロードはローカルで暗号化されます
• リスクのある設定を黙って隠すことなく、本番環境での起動時の警告が stderr に出力されます

本番環境への推奨導入手順：

1. 本番環境の認証情報を設定しますが、INTERSWITCH_READ_ONLY=true のままにします
2. 起動時の警告と設定概要を確認します
3. まず安全な読み取り専用ツールをテストします
4. 使用する予定のツールについて、ドメイン認証情報を確認します
5. 本番環境での書き込みが承認された場合に限り、INTERSWITCH_READ_ONLY=false に切り替えます
6. confirm: true を含むプロンプトは、人間によるレビューを必須にします

開発

ビルドせずにローカルで実行する

ローカルでの開発とテストでは、TypeScript のソースを直接実行できます。

npm run dev

MCP Inspector で実行する

npm run inspect

ビルド

npm run build

テストを実行する

npm test

型チェック

npm run lint

npm パッケージの内容をプレビューする

npm pack --dry-run

トラブルシューティング

問題	解決策
起動時にサーバーが何も表示せず終了する	ターミナルから実行して標準エラーを確認してください。Node v18+ と有効な環境変数が設定されていることを確認してください
本番環境に関する警告が表示される	不足している認証情報グループを追加するか、INTERSWITCH_READ_ONLY=true を設定するか、警告の内容に応じて DEBUG を無効にしてください
クライアントにツールが表示されない	サーバーが実行中であり、クライアントの設定ファイルのパスが正しいことを確認してください
書き込みツールがブロックされる	confirm: true を渡してください。それでもブロックされる場合は、INTERSWITCH_READ_ONLY を確認してください
高リスクの読み取りがブロックされる	confirm: true を渡してください
決済ツールが失敗する	必要に応じて INTERSWITCH_MERCHANT_CODE と INTERSWITCH_PAYABLE_CODE を設定してください
送金ツールが失敗する	必要に応じて INTERSWITCH_INITIATING_ENTITY_CODE を設定してください
Card 360 ツールが失敗する	CARD360_CLIENT_ID と CARD360_CLIENT_SECRET を設定してください
PIN 操作が失敗する	有効な CARD360_RSA_PUBLIC_KEY を設定してください
Transaction Search が失敗する	TRANSACTION_SEARCH_CLIENT_ID と TRANSACTION_SEARCH_CLIENT_SECRET を設定してください
Agency ツールが失敗する	INTERSWITCH_AGENCY_MERCHANT_ID と INTERSWITCH_AGENCY_TERMINAL_ID を設定してください
リクエストがタイムアウトする	設定済みの Interswitch 環境へのネットワーク接続を確認してください

コントリビューション

プルリクエストを歓迎します。大きな変更を行う場合は、まず Issue を作成して、変更したい内容について相談してください。

詳しくは CONTRIBUTING.md をご覧ください。

ライセンス

MIT