Interswitch MCP Server

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

You can select the API environment with INTERSWITCH_ENV:

1. Sandbox (default): INTERSWITCH_ENV=sandbox
2. 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

`sh

which node

`

### Windows

`sh

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

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:

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

Authentication systems

Available Tools

| isw_check_debit_balance | Check debit card balan