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

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

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.