How to integrate Razorpay MCP with LlamaIndex

This guide walks you through connecting Razorpay to LlamaIndex using the Composio tool router. By the end, you'll have a working Razorpay agent that can list recent razorpay payment failures, create payment link for invoice, fetch refund status for customer through natural language commands. This guide will help you understand how to give your LlamaIndex agent real control over a Razorpay account through Composio's Razorpay MCP server. Before we dive in, let's take a quick look at the key ideas and tools involved.

Razorpay logoRazorpay
Api KeyOauth2

Razorpay is a payment gateway and financial services platform for Indian businesses. It helps companies accept payments, manage refunds, send invoices, and run payouts.

42 Tools

Introduction

This guide walks you through connecting Razorpay to LlamaIndex using the Composio tool router. By the end, you'll have a working Razorpay agent that can list recent razorpay payment failures, create payment link for invoice, fetch refund status for customer through natural language commands.

This guide will help you understand how to give your LlamaIndex agent real control over a Razorpay account through Composio's Razorpay MCP server.

Before we dive in, let's take a quick look at the key ideas and tools involved.

Also integrate Razorpay with

TL;DR

Here's what you'll learn:
  • Set your OpenAI and Composio API keys
  • Install LlamaIndex and Composio packages
  • Create a Composio Tool Router session for Razorpay
  • Connect LlamaIndex to the Razorpay MCP server
  • Build a Razorpay-powered agent using LlamaIndex
  • Interact with Razorpay through natural language

What is LlamaIndex?

LlamaIndex is a data framework for building LLM applications. It provides tools for connecting LLMs to external data sources and services through agents and tools.

Key features include:

  • ReAct Agent: Reasoning and acting pattern for tool-using agents
  • MCP Tools: Native support for Model Context Protocol
  • Context Management: Maintain conversation context across interactions
  • Async Support: Built for async/await patterns

What is the Razorpay MCP server, and what's possible with it?

The Razorpay MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Razorpay account. It provides structured and secure access to your payments, orders, customers, invoices, payment links, settlements, and disputes, so your agent can collect payments, manage billing, review transactions, reconcile settlements, and monitor disputes on your behalf.

  • Payment collection and tracking: Have your agent create orders and payment links, review incoming payments, and cancel payment links that are no longer needed.
  • Customer and payment method management: Let the agent create customers, retrieve customer records, and review their saved payment methods.
  • Invoice and item management: Direct your agent to create billing items and invoices, update draft invoices, issue them to customers, and resend invoice notifications by email or SMS.
  • Transaction and settlement review: Instruct your agent to review orders, payments, and invoices, or retrieve settlement reconciliation reports for a specific date or month.
  • Dispute monitoring: Have your agent list payment disputes so your team can review and follow up on contested transactions.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step10 STEPS
1

Prerequisites

Before you begin, make sure you have:
  • Python 3.8/Node 16 or higher installed
  • A Composio account with the API key
  • An OpenAI API key
  • A Razorpay account and project
  • Basic familiarity with async Python/Typescript
2

Getting API Keys for OpenAI, Composio, and Razorpay

OpenAI API key (OPENAI_API_KEY)
  • Go to the OpenAI dashboard
  • Create an API key if you don't have one
  • Assign it to OPENAI_API_KEY in .env
Composio API key and user ID
  • Log into the Composio dashboard
  • Copy your API key from Settings
    • Use this as COMPOSIO_API_KEY
  • Pick a stable user identifier (email or ID)
    • Use this as COMPOSIO_USER_ID
3

Installing dependencies

npm install @composio/llamaindex @llamaindex/openai @llamaindex/tools @llamaindex/workflow dotenv

Create a new Typescript project and install the necessary dependencies:

  • @composio/llamaindex: Composio's LlamaIndex integration
  • @llamaindex/openai: OpenAI LLM integration
  • @llamaindex/tools: MCP client for LlamaIndex
  • @llamaindex/workflow: Workflow framework for LlamaIndex
  • dotenv: Environment variable management
4

Set environment variables

bash
OPENAI_API_KEY=your-openai-api-key
COMPOSIO_API_KEY=your-composio-api-key
COMPOSIO_USER_ID=your-user-id

Create a .env file in your project root:

These credentials will be used to:

  • Authenticate with OpenAI's GPT-5 model
  • Connect to Composio's Tool Router
  • Identify your Composio user session for Razorpay access
5

Import modules

import "dotenv/config";
import readline from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";

import { Composio } from "@composio/core";

import { mcp } from "@llamaindex/tools";
import { agent as createAgent } from "@llamaindex/workflow";
import { openai } from "@llamaindex/openai";

dotenv.config();

Create a new file called razorpay_llamaindex_agent.ts and import the required modules:

Key imports:

  • dotenv.config loads .env at runtime
  • readline gives us a simple CLI chat loop
  • Composio is the main Composio SDK client
  • mcp connects to an MCP endpoint
  • createAgent builds a LlamaIndex agent
  • openai configures the LLM backend
6

Load environment variables and initialize Composio

const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
const COMPOSIO_API_KEY = process.env.COMPOSIO_API_KEY;
const COMPOSIO_USER_ID = process.env.COMPOSIO_USER_ID;

if (!OPENAI_API_KEY) throw new Error("OPENAI_API_KEY is not set");
if (!COMPOSIO_API_KEY) throw new Error("COMPOSIO_API_KEY is not set");
if (!COMPOSIO_USER_ID) throw new Error("COMPOSIO_USER_ID is not set");

What's happening:

This ensures missing credentials cause early, clear errors before the agent attempts to initialise.

7

Create a Tool Router session and build the agent function

async function buildAgent() {

  console.log(`Initializing Composio client...${COMPOSIO_USER_ID!}...`);
  console.log(`COMPOSIO_USER_ID: ${COMPOSIO_USER_ID!}...`);

  const composio = new Composio({
    apiKey: COMPOSIO_API_KEY,
    provider: new LlamaindexProvider(),
  });

  const session = await composio.create(
    COMPOSIO_USER_ID!,
    {
      toolkits: ["razorpay"],
    },
  );

  const mcpUrl = session.mcp.url;
  console.log(`Composio Tool Router MCP URL: ${mcpUrl}`);

  const server = mcp({
    url: mcpUrl,
    clientName: "composio_tool_router_with_llamaindex",
    requestInit: {
      headers: {
        "x-api-key": COMPOSIO_API_KEY!,
      },
    },
    // verbose: true,
  });

  const tools = await server.tools();

  const llm = openai({ apiKey: OPENAI_API_KEY, model: "gpt-5" });

  const agent = createAgent({
    name: "composio_tool_router_with_llamaindex",
        description : "An agent that uses Composio Tool Router MCP tools to perform actions.",
    systemPrompt:
      "You are a helpful assistant connected to Composio Tool Router."+
"Use the available tools to answer user queries and perform Razorpay actions." ,
    llm,
    tools,
  });

  return agent;
}

What's happening here:

  • We create a Composio client using your API key and configure it with the LlamaIndex provider
  • We then create a tool router MCP session for your user, specifying the toolkits we want to use (in this case, razorpay)
  • The session returns an MCP HTTP endpoint URL that acts as a gateway to all your configured tools
  • LlamaIndex will connect to this endpoint to dynamically discover and use the available Razorpay tools.
  • The MCP tools are mapped to LlamaIndex-compatible tools and plug them into the Agent.
8

Create an interactive chat loop

async function chatLoop(agent: ReturnType<typeof createAgent>) {
  const rl = readline.createInterface({ input, output });

  console.log("Type 'quit' or 'exit' to stop.");

  while (true) {
    let userInput: string;

    try {
      userInput = (await rl.question("\nYou: ")).trim();
    } catch {
      console.log("\nAgent: Bye!");
      break;
    }

    if (!userInput) {
      continue;
    }

    const lower = userInput.toLowerCase();
    if (lower === "quit" || lower === "exit") {
      console.log("Agent: Bye!");
      break;
    }

    try {
      process.stdout.write("Agent: ");

      const stream = agent.runStream(userInput);
      let finalResult: any = null;

      for await (const event of stream) {
        // The event.data contains the streamed content
        const data: any = event.data;

        // Check for streaming delta content
        if (data?.delta) {
          process.stdout.write(data.delta);
        }

        // Store final result for fallback
        if (data?.result || data?.message) {
          finalResult = data;
        }
      }

      // If no streaming happened, show the final result
      if (finalResult) {
        const answer =
          finalResult.result ??
          finalResult.message?.content ??
          finalResult.message ??
          "";
        if (answer && typeof answer === "string" && !answer.includes("[object")) {
          process.stdout.write(answer);
        }
      }

      console.log(); // New line after streaming completes
    } catch (err: any) {
      console.error("\nAgent error:", err?.message ?? err);
    }
  }

  rl.close();
}

What's happening:

  • We're creating a direct terminal interface to chat with Razorpay
  • The LLM's responses are streamed to the CLI for faster interaction.
  • The agent uses context to maintain conversation history
  • The agent processes the request, selects appropriate Razorpay tools, and returns a result
  • We extract the answer from the result data structure and display it to the user
  • You can type 'quit' or 'exit' to stop the chat loop gracefully
  • Agent responses and any errors are streamed in a clear, readable format
9

Define the main entry point

async function main() {
  try {
    const agent = await buildAgent();
    await chatLoop(agent);
  } catch (err) {
    console.error("Failed to start agent:", err);
    process.exit(1);
  }
}

main();

What's happening here:

  • We're orchestrating the entire application flow
  • The agent gets built with proper error handling
  • Then we kick off the interactive chat loop so you can start talking to Razorpay
10

Run the agent

npx ts-node llamaindex-agent.ts

When prompted, authenticate and authorise your agent with Razorpay, then start asking questions.

Complete Code

Here's the complete code to get you started with Razorpay and LlamaIndex:

import "dotenv/config";
import readline from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";

import { Composio } from "@composio/core";
import { LlamaindexProvider } from "@composio/llamaindex";

import { mcp } from "@llamaindex/tools";
import { agent as createAgent } from "@llamaindex/workflow";
import { openai } from "@llamaindex/openai";

dotenv.config();

const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
const COMPOSIO_API_KEY = process.env.COMPOSIO_API_KEY;
const COMPOSIO_USER_ID = process.env.COMPOSIO_USER_ID;

if (!OPENAI_API_KEY) {
    throw new Error("OPENAI_API_KEY is not set in the environment");
  }
if (!COMPOSIO_API_KEY) {
    throw new Error("COMPOSIO_API_KEY is not set in the environment");
  }
if (!COMPOSIO_USER_ID) {
    throw new Error("COMPOSIO_USER_ID is not set in the environment");
  }

async function buildAgent() {

  console.log(`Initializing Composio client...${COMPOSIO_USER_ID!}...`);
  console.log(`COMPOSIO_USER_ID: ${COMPOSIO_USER_ID!}...`);

  const composio = new Composio({
    apiKey: COMPOSIO_API_KEY,
    provider: new LlamaindexProvider(),
  });

  const session = await composio.create(
    COMPOSIO_USER_ID!,
    {
      toolkits: ["razorpay"],
    },
  );

  const mcpUrl = session.mcp.url;
  console.log(`Composio Tool Router MCP URL: ${mcpUrl}`);

  const server = mcp({
    url: mcpUrl,
    clientName: "composio_tool_router_with_llamaindex",
    requestInit: {
      headers: {
        "x-api-key": COMPOSIO_API_KEY!,
      },
    },
    // verbose: true,
  });

  const tools = await server.tools();

  const llm = openai({ apiKey: OPENAI_API_KEY, model: "gpt-5" });

  const agent = createAgent({
    name: "composio_tool_router_with_llamaindex",
    description:
      "An agent that uses Composio Tool Router MCP tools to perform actions.",
    systemPrompt:
      "You are a helpful assistant connected to Composio Tool Router."+
"Use the available tools to answer user queries and perform Razorpay actions." ,
    llm,
    tools,
  });

  return agent;
}

async function chatLoop(agent: ReturnType<typeof createAgent>) {
  const rl = readline.createInterface({ input, output });

  console.log("Type 'quit' or 'exit' to stop.");

  while (true) {
    let userInput: string;

    try {
      userInput = (await rl.question("\nYou: ")).trim();
    } catch {
      console.log("\nAgent: Bye!");
      break;
    }

    if (!userInput) {
      continue;
    }

    const lower = userInput.toLowerCase();
    if (lower === "quit" || lower === "exit") {
      console.log("Agent: Bye!");
      break;
    }

    try {
      process.stdout.write("Agent: ");

      const stream = agent.runStream(userInput);
      let finalResult: any = null;

      for await (const event of stream) {
        // The event.data contains the streamed content
        const data: any = event.data;

        // Check for streaming delta content
        if (data?.delta) {
          process.stdout.write(data.delta);
        }

        // Store final result for fallback
        if (data?.result || data?.message) {
          finalResult = data;
        }
      }

      // If no streaming happened, show the final result
      if (finalResult) {
        const answer =
          finalResult.result ??
          finalResult.message?.content ??
          finalResult.message ??
          "";
        if (answer && typeof answer === "string" && !answer.includes("[object")) {
          process.stdout.write(answer);
        }
      }

      console.log(); // New line after streaming completes
    } catch (err: any) {
      console.error("\nAgent error:", err?.message ?? err);
    }
  }

  rl.close();
}

async function main() {
  try {
    const agent = await buildAgent();
    await chatLoop(agent);
  } catch (err: any) {
    console.error("Failed to start agent:", err?.message ?? err);
    process.exit(1);
  }
}

main();

Conclusion

You've successfully connected Razorpay to LlamaIndex through Composio's Tool Router MCP layer. Key takeaways:
  • Tool Router dynamically exposes Razorpay tools through an MCP endpoint
  • LlamaIndex's ReActAgent handles reasoning and orchestration; Composio handles integrations
  • The agent becomes more capable without increasing prompt size
  • Async Python provides clean, efficient execution of agent workflows
You can easily extend this to other toolkits like Gmail, Notion, Stripe, GitHub, and more by adding them to the toolkits parameter.
TOOLS

Supported Tools

Every Razorpay action and event your agent gets out of the box.

Cancel Invoice

Tool to cancel an existing Razorpay invoice.

Cancel Payment Link

Tool to cancel a specific payment link.

Create an Order

Tool to create a Razorpay order with specified amount and currency.

Create Contact

Tool to create a contact for payouts in RazorpayX.

Create Customer

Tool to create a new customer in Razorpay.

Create an Invoice

Tool to create an invoice for billing customers.

Create Item

Tool to create an item that can be used in Razorpay invoices.

Create Payment Link

Tool to create a payment link for collecting payments via a shareable URL.

Delete Invoice

Tool to delete an invoice in Razorpay.

Delete item

Tool to delete an existing item from Razorpay.

Fetch All Customers

Tool to retrieve a paginated list of all customers from Razorpay.

Fetch All Invoices

Tool to fetch all invoices with pagination and filtering support.

Fetch All Payment Links

Tool to fetch all payment links with pagination and filtering support.

Fetch All Payments

Tool to retrieve all payments from your Razorpay account with pagination and time filtering support.

Fetch all refunds for a payment

Tool to retrieve all refunds for a specific payment using the Razorpay API.

Fetch a Payment Link

Tool to retrieve details of a specific payment link by its ID.

Fetch Invoice by ID

Tool to fetch a specific invoice by its ID from Razorpay.

Fetch All Orders

Tool to retrieve a paginated list of all orders from Razorpay.

Fetch Order by ID

Tool to fetch details of a specific Razorpay order using its order ID.

Fetch payments by order

Tool to fetch all payments made for a particular order.

Fetch All Refunds

Tool to retrieve all refunds created by you using the Razorpay API.

Get Contact

Tool to retrieve details of a specific contact by ID in RazorpayX.

Retrieve Customer

Tool to retrieve details of a specific customer by their ID.

Get Fund Account

Tool to retrieve details of a specific fund account by its ID.

Get Item

Tool to retrieve complete details of a specific Razorpay item by its ID.

Get Settlement Reconciliation Report

Tool to fetch settlement reconciliation report for a specific date or month from Razorpay.

Get Transfer Reversals

Tool to fetch all reversals for a specific transfer using the Razorpay Route API.

Issue an Invoice

Tool to issue a draft Razorpay invoice to send it to the customer.

List Customer Tokens

Tool to retrieve all tokens (saved payment methods) for a customer.

List Disputes

Tool to retrieve a list of all disputes with pagination support.

List Fund Accounts

Tool to retrieve a list of all fund accounts from RazorpayX with pagination support.

List Fund Validations

Tool to fetch all fund account validation transactions from RazorpayX with pagination support.

List Items

Tool to retrieve a list of all items from Razorpay with pagination support.

List Payment Downtimes

Tool to fetch all active payment method downtimes from Razorpay.

Notify Payment Link

Tool to send or resend notification for a payment link via SMS or email.

Send/Resend Invoice Notification

Tool to send or resend an invoice notification via email or SMS.

Update Contact

Tool to update an existing contact's details in RazorpayX.

Update Customer

Tool to update an existing customer's details in Razorpay.

Update Invoice

Tool to update an existing draft invoice in Razorpay.

Update Item

Tool to update an existing item's details in Razorpay.

Update Order

Tool to update an existing order in Razorpay.

Update payment link

Tool to update an existing payment link in Razorpay.

FAQ

Frequently asked questions

With a standalone Razorpay MCP server, the agents and LLMs can only access a fixed set of Razorpay tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Razorpay and many other apps based on the task at hand, all through a single MCP endpoint.

Yes, you can. LlamaIndex fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Razorpay tools.

Yes, absolutely. You can configure which Razorpay scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Razorpay data and credentials are handled as safely as possible.

Start with Razorpay.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Razorpay tool your agent needs.Free to start.

Start building