Juspay MCP Tools

A Model Context Protocol (MCP) server to interact with Juspay APIs. This package enables AI agents and other tools to leverage Juspay's capabilities for core payment processing and merchant dashboard interactions.

Table of Contents

• Juspay MCP Tools
  • Table of Contents
  • Introduction
  • Key Features
  • Getting Started
    • Prerequisites
    • Installation
    • Quick Start
    • Docker Images
  • Usage with Claude and Other AI Assistants
    • Juspay Payments MCP
    • Juspay Dashboard MCP
  • Configuration
    • Environment Variables
    • Running Both Core and Dashboard APIs
  • Architecture
  • Available Tools
    • Juspay Payments Tools
      • Order Management
      • Payment Processing
      • Customer Management
      • Card Management
      • UPI Payments
      • Offers and Wallets
    • Juspay Dashboard Tools
      • Gateway Management
      • Reporting
      • User Management
      • Settings Management
      • Advanced Querying
  • Troubleshooting
    • Common Issues
    • Debugging Tips
  • Contributing
    • Development Environment
  • License

Introduction

The Juspay MCP (Model Context Protocol) server provides a standardized interface for AI agents and applications to interact with Juspay's payment processing infrastructure and merchant dashboard.

Model Context Protocol is an emerging standard for enabling AI models and agents to interact with external tools and APIs in a structured, discoverable way. This allows AI assistants like Claude to perform complex payment operations and dashboard management tasks through natural language.

Key Features

• Dual API Coverage: Provides tools for both Juspay's Core Payment APIs and Dashboard APIs.

• MCP Integration: Enables seamless integration with LLMs and AI agents via the Model Context Protocol.

• Configurable Modes: Run the server specifically for Core APIs or Dashboard APIs using an environment variable.

Getting Started

Installation

Nix

# 1. Clone the repository
git clone https://github.com/juspay/juspay-mcp.git
cd juspay-mcp

# 2. Installing dependencies and setting up the environment
nix develop

Quick Start

1. Set up your environment variables (see Configuration section)
2. Start the server:

# With Nix to run the MCP server
nix run

# For standard HTTP server (normally)
python ./juspay_mcp/main.py

# For STDIO mode via nix
nix run .#stdio

# For STDIO mode via nix (standard method)
python ./juspay_mcp/stdio.py

Docker Images

Nix will build the docker image and copy it to the Docker Registry.

# Build main MCP image
nix run .#docker.copyToDockerDaemon

# Build SSE-enabled MCP image
nix run .#docker-sse.copyToDockerDaemon

# Build dashboard MCP image
nix run .#docker-dashboard.copyToDockerDaemon

# Build dashboard SSE-enabled MCP image
nix run .#docker-dashboard-sse.copyToDockerDaemon

Viewing Images

# List all juspay images
docker images | grep juspay

# List all Docker images
docker images

Running Images

# Run main MCP server
docker run -it juspay-mcp:latest

# Run SSE-enabled MCP server
docker run -it juspay-mcp-sse:latest

# Run dashboard MCP server
docker run -it juspay-dashboard-mcp:latest

# Run dashboard SSE-enabled MCP server
docker run -it juspay-dashboard-mcp-sse:latest

# Run with port mapping (example)
docker run -it -p 8080:8080 juspay-mcp-sse:latest

Clean Up

# Remove specific image
docker rmi juspay-mcp:latest

Usage with Claude and Other AI Assistants

Juspay Payments MCP

Add the following to your claude_desktop_config.json or equivalent configuration:

{
  "mcpServers": {
    "juspay-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--pull=always",
        "--rm",
        "-i",
        "-e",
        "JUSPAY_API_KEY",
        "-e",
        "JUSPAY_MERCHANT_ID",
        "-e",
        "JUSPAY_ENV",
        "juspaydotin/juspay-mcp:latest"
      ],
      "env": {
        "JUSPAY_API_KEY": "your_juspay_api_key",
        "JUSPAY_MERCHANT_ID": "your_juspay_merchant_id",
        "JUSPAY_ENV": "sandbox | production"
      }
    }
  }
}

Please replace the your_juspay_api_key and your_juspay_merchant_id with your api key and merchant id. Default values for JUSPAY_ENV is sandbox.

Juspay Dashboard MCP

{
  "mcpServers": {
    "juspay-dashboard-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--pull=always",
        "--rm",
        "-i",
        "-e",
        "JUSPAY_WEB_LOGIN_TOKEN",
        "-e",
        "JUSPAY_ENV",
        "juspaydotin/juspay-dashboard-mcp:latest"
      ],
      "env": {
        "JUSPAY_WEB_LOGIN_TOKEN": "your_juspay_web_login_token",
        "JUSPAY_ENV": "sandbox | production"
      }
    }
  }
}

Please replace the your_juspay_web_login_token with your dashboard login token.

Configuration

Environment Variables

Create a .env file in the project root or set these variables in your environment:

# --- Required Juspay Credentials for Payments ---
JUSPAY_API_KEY="your_juspay_api_key"
JUSPAY_MERCHANT_ID="your_juspay_merchant_id"

# --- Required Juspay Credentials for Dashboard ---
JUSPAY_WEB_LOGIN_TOKEN="your_juspay_web_login_token"

# --- Required Server Mode ---
# Determines which set of tools the server will expose.
# Options: "CORE" (default), "DASHBOARD"
JUSPAY_MCP_TYPE="CORE"

# --- Optional: Juspay Environment ---
# Set to "production" to use live API endpoints.
# Options: "sandbox" (default), "production"
JUSPAY_ENV="sandbox"

# --- Optional: Include Response Schemas ---
# When set to "true", tool descriptions will include JSON schemas for responses
# Options: "false" (default), "true"
INCLUDE_RESPONSE_SCHEMA="false"

Running Both Core and Dashboard APIs

The server runs either Core or Dashboard tools per instance, controlled by JUSPAY_MCP_TYPE. To access both sets simultaneously, run two separate server instances with different JUSPAY_MCP_TYPE values and ports:

# Terminal 1: Run Core API server
JUSPAY_MCP_TYPE=CORE python main.py --port 8080

# Terminal 2: Run Dashboard API server
JUSPAY_MCP_TYPE=DASHBOARD python main.py --port 8001

Architecture

The Juspay MCP server consists of two primary modules:

1. juspay_mcp: Handles core payment processing functionality including orders, transactions, refunds, customers, cards, UPI, and more.

2. juspay_dashboard_mcp: Provides access to merchant dashboard features like gateway management, reporting, user management, and settings.

Each module:

• Defines API schemas in api_schema/ directory
• Implements API handlers in api/ directory
• Exposes tools via the tools.py file
• Manages configuration in config.py

The MCP server translates AI assistant requests into properly formatted API calls to Juspay's backend services, handling authentication, request formatting, and response parsing automatically.

Available Tools

Juspay Payments Tools

Order Management

Tool Name	Description
create_order_juspay	Creates a new order in Juspay payment system.
update_order_juspay	Updates an existing order in Juspay.
order_status_api_juspay	Retrieves the status of a specific Juspay order using its order_id.
order_fulfillment_sync_juspay	Updates the fulfillment status of a Juspay order.

Payment Processing

Tool Name	Description
session_api_juspay	Creates a new Juspay session for a given order.
create_txn_juspay	Creates an order and processes payment in a single API call.
create_moto_txn_juspay	Creates an order with MOTO (Mail Order/Telephone Order) authentication.
create_refund_juspay	Initiates a refund for a specific Juspay order using its order_id.
create_txn_refund_juspay	Initiates a refund based on transaction ID (instead of order ID).

Customer Management

Tool Name	Description
create_customer_juspay	Creates a new customer in Juspay with the provided details.
get_customer_juspay	Retrieves customer details using the Juspay customer ID.
update_customer_juspay	Updates an existing customer in Juspay with the provided details.

Card Management

Tool Name	Description
add_card_juspay	Adds a new card to the Juspay system for a customer.
list_cards_juspay	Retrieves all stored cards for a specific customer.
delete_card_juspay	Deletes a saved card from the Juspay system.
update_card_juspay	Updates details for a saved card.
get_card_info_juspay	Retrieves information about a specific card BIN (Bank Identification Number).
get_bin_list_juspay	Retrieves a list of eligible BINs for a specific authentication type.
get_saved_payment_methods	Retrieves a customer's saved payment methods.

UPI Payments

Tool Name	Description
upi_collect	Creates a UPI Collect transaction for requesting payment from a UPI ID.
verify_vpa	Verifies if a UPI Virtual Payment Address (VPA) is valid.
upi_intent	Creates a UPI Intent transaction for payment using UPI apps.

Offers and Wallets

Tool Name	Description
list_offers_juspay	Lists available offers for a given order with optional coupon code.
get_offer_order_status_juspay	Retrieves the status of an order along with offer details.
list_wallets	Fetches all wallets linked to the given customer.

Juspay Dashboard Tools

Gateway Management

Tool Name	Description
juspay_list_configured_gateway	Gets all configured gateways for the merchant.
juspay_get_gateway_scheme	Provides detailed configuration info for a gateway (fields, payment methods).
juspay_get_gateway_details	Returns detailed information about a specific configured gateway (mga_id required).
juspay_list_gateway_scheme	Returns a list of all available payment gateways that can be configured.
juspay_gateway_downtime	Retrieves downtime information for a gateway (order_id required).
juspay_get_merchant_gateways_pm_details	Fetches all gateways and their supported payment methods for the merchant.

Reporting

Tool Name	Description
juspay_report_details	Returns detailed information for a specific report ID.
juspay_list_report	Lists all reports configured by the merchant.
juspay_list_orders_v4	Retrieves orders within a time range (dashboard perspective).
juspay_get_order_details	Returns complete details for a given order ID (dashboard perspective).
juspay_list_payment_links_v1	Retrieves payment links created within a time range.

User Management

Tool Name	Description
juspay_get_user	Fetches details for a specific user by user ID.
juspay_list_users_v2	Retrieves a list of users associated with a merchant, with optional pagination.

Settings Management

Tool Name	Description
juspay_get_conflict_settings	Retrieves conflict settings configuration for payment processing.
juspay_get_general_settings	Retrieves general configuration settings for the merchant.
juspay_get_mandate_settings	Retrieves mandate-related settings for recurring payments.
juspay_get_priority_logic_settings	Fetches all configured priority logic rules.
juspay_get_routing_settings	Provides details of success rate-based routing thresholds.
juspay_get_webhook_settings	Retrieves webhook configuration settings for the merchant.
juspay_list_surcharge_rules	Returns a list of all configured surcharge rules.

Advanced Querying

Tool Name	Description
q_api	Generic Query API for various dashboard data domains (refer to q_api.py for details).

Troubleshooting

Common Issues

1. Authentication Failures

   • Ensure your API keys are correct and have appropriate permissions
   • Verify you're using the right environment (sandbox/production)

2. Request Validation Errors

   • Check that all required fields are present in your request
   • Validate format of values (e.g., proper phone number format, valid email)

3. Connection Issues

   • Check network connectivity
   • Verify firewall settings allow outbound connections to Juspay endpoints

Debugging Tips

1. Inspect the server logs for error messages and request/response details.

2. For MCP communication issues, verify that your AI assistant platform is correctly configured to send and receive MCP-formatted messages.

Contributing

We welcome contributions to the Juspay MCP server! Here's how you can contribute:

1. Fork the repository and create your feature branch

   git checkout -b feature/amazing-feature
   

2. Make your changes and ensure they follow our coding standards

   • Use type annotations where appropriate
   • Add docstrings to new functions and classes
   • Follow PEP 8 style guidelines

3. Add tests for any new functionality

4. Submit a pull request with a clear description of the changes and their benefits

Development Environment

Nix

# Enter in the development shell (with all dependencies)
nix develop

# Run tests
nix run .#test

# Run juspay-mcp
nix run

License

This project is licensed under the Apache License 2.0. See the LICENSE file for the full license text.

Copyright 2025 Juspay Technologies Private Limited.