How do I install Interswitch?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Interswitch need an API key?

The publisher lists these environment variables: INTERSWITCH_CLIENT_ID, INTERSWITCH_CLIENT_SECRET, INTERSWITCH_ENV, INTERSWITCH_READ_ONLY.

What transport does Interswitch use?

Interswitch runs locally over stdio.

When was Interswitch last checked?

Last checked 2026-11-09. MCP server for Interswitch APIs: payments, transfers, Verve cards, airtime, and paycodes.

Interswitch MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y [email protected]

Credentials from the publisher

INTERSWITCH_CLIENT_ID — Interswitch OAuth2 client ID (from Interswitch Developer Console)
INTERSWITCH_CLIENT_SECRET — Interswitch OAuth2 client secret
INTERSWITCH_ENV — Target environment: sandbox (default) or production
INTERSWITCH_READ_ONLY — Set to true to block all write/transfer operations

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1INTERSWITCH_CLIENT_ID=<value> INTERSWITCH_CLIENT_SECRET=<secret> INTERSWITCH_ENV=<value> INTERSWITCH_READ_ONLY=<value> claude mcp add io.github.dairus01-interswitch-mcp-server -- npx -y interswitch-mcp-server@0.1.3

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.dairus01-interswitch-mcp-server": {4      "command": "npx",5      "args": [6        "-y",7        "[email protected]"8      ],9      "env": {10        "INTERSWITCH_CLIENT_ID": "<value>",11        "INTERSWITCH_CLIENT_SECRET": "<secret>",12        "INTERSWITCH_ENV": "<value>",13        "INTERSWITCH_READ_ONLY": "<value>"14      }15    }16  }17}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.1.3

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

Interswitch MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Interswitch APIs for payments, transfers, VAS, cardless paycodes, Transaction Search, Card 360, lending, payouts, agency banking, and fintech card-processing utilities.

[!WARNING] Public Preview: This MCP server is currently in public preview. It supports both Interswitch sandbox and production environments, so use cautiously, start with read-only mode, and report any issues you encounter.

Quick Start

Install and run via npm (recommended):

npx interswitch-mcp-server

Or install globally:

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

Or for local development, clone and build:

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

Then configure your MCP client to use the server (see Client Integration).

Requirements

Node.js v18+
npm or yarn
Interswitch API credentials for the domains you want to use
Required Interswitch merchant, payable, initiating entity, terminal, or domain-specific identifiers for your use case

Configuration Options

Environment Variable	Purpose
`INTERSWITCH_CLIENT_ID`	Core OAuth2 client ID for payments, transfers, VAS, cardless, lending, transfer service, and payouts
`INTERSWITCH_CLIENT_SECRET`	Core OAuth2 client secret
`INTERSWITCH_ENV`	API environment: `sandbox` or `production`; defaults to `sandbox`
`INTERSWITCH_READ_ONLY`	Set `true` to block write tools before any API call; defaults to `false`
`INTERSWITCH_REQUIRE_CONFIRMATION`	Compatibility setting. Tool confirmation is enforced by tool mode and risk.
`INTERSWITCH_MERCHANT_CODE`	Merchant code for payment operations that require it
`INTERSWITCH_PAYABLE_CODE`	Payable code for payment operations that require it
`INTERSWITCH_INITIATING_ENTITY_CODE`	Initiating entity code for transfer operations
`INTERSWITCH_TERMINAL_ID`	Terminal ID for operations that require terminal identification
`CARD360_CLIENT_ID`	Separate Card 360 client ID
`CARD360_CLIENT_SECRET`	Separate Card 360 client secret
`CARD360_RSA_PUBLIC_KEY`	RSA public key used to encrypt Card 360 PIN payloads locally
`TRANSACTION_SEARCH_CLIENT_ID`	Separate Transaction Search client ID
`TRANSACTION_SEARCH_CLIENT_SECRET`	Separate Transaction Search client secret
`INTERSWITCH_AGENCY_MERCHANT_ID`	Agency Banking merchant identifier
`INTERSWITCH_AGENCY_TERMINAL_ID`	Agency Banking terminal identifier
`INTERSWITCH_LEGACY_AUTH_ENABLED`	Enables legacy InterswitchAuth-backed flows where supported
`DEBUG`	Enables debug logging. Avoid using this in production.

You can select the API environment with INTERSWITCH_ENV:

Sandbox (default): INTERSWITCH_ENV=sandbox
Production: INTERSWITCH_ENV=production

Security note: Production mode uses real Interswitch production endpoints. If INTERSWITCH_ENV=production, valid production credentials are configured, INTERSWITCH_READ_ONLY=false, and a write tool is called with confirm: true, the server can make real production API calls.

For safer first-time setup, start in read-only mode:

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

When you are authorized and ready to allow live writes, set:

INTERSWITCH_READ_ONLY=false

Client Integration

The Interswitch MCP Server works with any MCP-compatible client. Below is the standard configuration schema used by most clients (Claude Desktop, ChatGPT Desktop, Cursor, Windsurf, VS Code, Claude Code, etc.).

Using npm (recommended)

For npm-installed server:

{
  "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"
      }
    }
  }
}

For production, change the environment values intentionally:

{
  "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"
      }
    }
  }
}

Using a local build

If you've cloned and built the server locally:

{
  "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"
      }
    }
  }
}

[!IMPORTANT] When setting command: "node", you should ensure you're using Node v18+. If you are using a package manager, you might need to get the path of your Node binary by running this command in your CLI:

Linux and MacOS
which node
Windows
where node
Once you have the path, use it as the value of the MCP Server command in the JSON configuration. e.g., command: "path/to/installation/bin/node"

Where to add this configuration

Client	Config file location
VS Code	`.vscode/mcp.json`
Claude Desktop	`claude_desktop_config.json`
ChatGPT Desktop	MCP settings in app preferences
Cursor	`.cursor/mcp.json` or global MCP settings
Windsurf	MCP configuration in settings
Claude Code	`~/.claude/mcp.json` or project-level `.mcp.json`

How It Works

The Interswitch MCP Server exposes Interswitch API domains to AI assistants through dedicated MCP tools. The server does not parse an OpenAPI file at runtime; instead, it provides curated, typed tools for the supported Interswitch domains.

Architecture Diagram

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

Each tool:

Validates its input with a strict schema
Applies confirmation and read-only safety gates
Selects the configured sandbox or production base URL
Uses the correct authentication system for the domain
Calls the Interswitch API only when the tool is invoked
Redacts sensitive fields from returned data
Returns a normalized MCP response

Authentication systems

Auth system	Used for
OAuth2 Passport	Core payments, transfers, VAS, cardless, lending, transfer service, and payouts
Card 360 token manager	Card 360 operations
Transaction Search token manager	Transaction Search APIs
Legacy InterswitchAuth	Legacy signed request flows where enabled
Agency Banking token manager	Agency Banking SOAP/XML token flow

Available Tools

Tool	Description
`isw_initialize_payment`	Initialize a payment request
`isw_get_transaction_status`	Check transaction status
`isw_get_transaction_by_reference`	Fetch transaction by reference
`isw_create_payment_link`	Create a payment link
`isw_initiate_refund`	Initiate a refund; high-risk write
`isw_get_refund_status`	Check refund status
`isw_pay_bill`	Pay a bill
`isw_get_billers`	List billers
`isw_get_biller_packages`	List packages for a biller
`isw_get_billers_by_category`	List billers by category
`isw_get_biller_details`	Fetch biller details
`isw_validate_customer`	Validate a biller customer
`isw_pay_vas_bill`	Pay a VAS bill
`isw_airtime_recharge`	Recharge airtime
`isw_get_airtime_epins`	Request airtime ePINs
`isw_single_transfer`	Send a single bank transfer; high-risk write
`isw_bulk_transfer`	Send bulk transfers; high-risk write; max 100 transactions
`isw_resolve_bank_account`	Resolve bank account details
`isw_get_bank_codes`	List supported bank codes
`isw_agency_banking_cashout`	Initiate agency cashout; high-risk write
`isw_create_paycode`	Create a cardless paycode
`isw_create_bulk_paycodes`	Create bulk paycodes; high-risk write; max 100 paycodes
`isw_get_paycode_status`

Available Resources

Resource	URI	Description
`response_codes`	`isw://response-codes`	Common Interswitch response-code reference
`config_summary`	`isw://config-summary`	Safe runtime configuration summary; returns credential presence only, never secrets

Example

When you ask your AI assistant something like "Use Interswitch to initialize a 5000 NGN payment for [email protected]", here's what happens behind the scenes:

The assistant selects isw_initialize_payment
It passes explicit money input such as amountNaira: 5000
For write operations, it must include confirm: true
The server validates the request, converts the amount safely where required, authenticates with Interswitch, and calls the configured sandbox or production endpoint
You get a normalized response with redacted raw data

Prompt recommendation

To get the best results when using this MCP server, be specific in your prompts and always include "Interswitch" in your requests.

Good prompts:

"Initialize an Interswitch payment for 50000 NGN for [email protected]."
"Check the Interswitch transaction status for reference order-1001."
"Resolve Interswitch bank account 0123456789 with bank code 058."
"Send an Interswitch single transfer for 1000 NGN with confirm true."
"Read the Interswitch response code resource."

Less effective prompts:

"List my transactions" (unclear which service and reference/search criteria to use)
"Send money" (missing beneficiary, bank, amount, and confirmation details)
"Pay this bill" (missing biller, package, customer, and amount details)

Being explicit ensures the LLM narrows down to the right tool quickly and reduces ambiguity.

Production Safety

This server can route to production Interswitch endpoints when INTERSWITCH_ENV=production is set. Production readiness depends on correct credentials, Interswitch account permissions, and your organization's operational controls.

Safety behavior built into the server:

Write tools require confirm: true
High-risk sensitive read tools require confirm: true
INTERSWITCH_READ_ONLY=true blocks all writes before any external API call
Low-risk reads do not require confirmation
Raw responses are redacted before being returned
Tokens and secrets are never intentionally returned in tool output
Card PIN payloads are encrypted locally when the required RSA public key is configured
Production startup warnings are written to stderr instead of silently hiding risky configuration

Recommended production rollout:

Configure production credentials but keep INTERSWITCH_READ_ONLY=true
Verify startup warnings and config summary
Test safe read-only tools first
Confirm domain credentials for the exact tools you intend to use
Switch INTERSWITCH_READ_ONLY=false only when live writes are authorized
Require human review before prompts that include confirm: true

Development

Run locally (without building)

For local development and testing, you can run the TypeScript source directly:

npm run dev

Run with MCP Inspector

npm run inspect

Build

npm run build

Run tests

npm test

Type-check

npm run lint

Preview npm package contents

npm pack --dry-run

Troubleshooting

Issue	Solution
Server exits silently at startup	Run it from a terminal and check stderr; verify Node v18+ and valid environment variables
Production warning appears	Add the missing credential group, set `INTERSWITCH_READ_ONLY=true`, or disable `DEBUG` depending on the warning
Tools not appearing in client	Ensure the server is running and the client config path is correct
Write tool blocked	Pass `confirm: true`; if still blocked, check `INTERSWITCH_READ_ONLY`
High-risk read blocked	Pass `confirm: true`
Payment tools fail	Configure `INTERSWITCH_MERCHANT_CODE` and `INTERSWITCH_PAYABLE_CODE` where required
Transfer tools fail	Configure `INTERSWITCH_INITIATING_ENTITY_CODE` where required
Card 360 tools fail	Configure `CARD360_CLIENT_ID` and `CARD360_CLIENT_SECRET`
PIN operations fail	Configure a valid `CARD360_RSA_PUBLIC_KEY`
Transaction Search fails	Configure `TRANSACTION_SEARCH_CLIENT_ID` and `TRANSACTION_SEARCH_CLIENT_SECRET`
Agency tools fail	Configure `INTERSWITCH_AGENCY_MERCHANT_ID` and `INTERSWITCH_AGENCY_TERMINAL_ID`
Request timeouts	Check network connectivity to the configured Interswitch environment

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

See CONTRIBUTING.md for more details.

License

MIT

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Interswitch?

Does Interswitch need an API key?

What transport does Interswitch use?

When was Interswitch last checked?

Documentation

Interswitch MCP Server

Quick Start

Requirements

Configuration Options

Client Integration

Using npm (recommended)

Using a local build

Linux and MacOS

Windows

Where to add this configuration

How It Works

Architecture Diagram

Authentication systems

Available Tools

Available Resources

Example

Prompt recommendation

Production Safety

Development

Run locally (without building)

Run with MCP Inspector

Build

Run tests

Type-check

Preview npm package contents

Troubleshooting

Contributing

License