> ## Documentation Index
> Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Use the Cashfree Payments MCP Server to let AI agents query transactions, settlements, and reports, and call Payment Gateway APIs through the Model Context Protocol.

The Cashfree Payments MCP Server enables AI tools and agents to interact with your Cashfree account using natural language. Built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), it connects AI clients such as Claude, ChatGPT, Cursor, and Claude Code directly to your Merchant Dashboard and Payment Gateway, so you can perform account operations without logging in to the Merchant Dashboard manually.

You can use the MCP Server to:

* Query the full lifecycle of any transaction by ID.
* Check your unsettled balance and next settlement date in real time.
* Generate and download settlement reconciliation reports using a natural language prompt.
* Evaluate on-demand settlement eligibility and calculate exact withdrawal charges.
* Create payment links directly from your AI client.
* Combine with other MCP-compatible tools such as Gmail, WhatsApp, or GitHub to build end-to-end payment workflows.

## Set up the MCP Server

### Prerequisites

Before you begin, ensure you have the following:

* An active Cashfree Payments merchant account with owner-level access.
* The **Claude Desktop** application or a **ChatGPT** account that supports connectors or apps.
* Network access to `https://mcp.cashfree.com` from your AI client.

Connect to the Cashfree-managed remote MCP Server over HTTPS using Claude, ChatGPT, Cursor, or Claude Code. You only need to configure the endpoint URL in your AI client and authenticate using your Cashfree account. Select your AI client to get started.

<AccordionGroup>
  <Accordion title="Claude Desktop" description="Add Cashfree as a custom connector inside Claude Desktop." icon="https://mintcdn.com/cashfreepayments-d00050e9/Akq7t_Lh0XZPNAh6/static/logo/claude-color.svg?fit=max&auto=format&n=Akq7t_Lh0XZPNAh6&q=85&s=46d9e5cd7ef4faa08d2cb063913eec42" width="16" height="16" data-path="static/logo/claude-color.svg">
    <Note>
      This integration requires the **Claude Desktop** application and is not available in the Claude web app. Whether connector access requires a paid plan depends on Anthropic's current policy. Check your Claude account settings if the connection is blocked.
    </Note>

    Follow these steps to add Cashfree as a custom connector in Claude Desktop and authenticate with your merchant account.

    <Steps>
      <Step title="Open connectors in Claude Desktop">
        1. Log in to the **Claude Desktop** application.
        2. In the left navigation, select **Customise**.
        3. Select **Connectors**.
        4. Select the **+** icon, then select **Add custom connector**.
      </Step>

      <Step title="Add the Cashfree connector">
        1. Enter a name for the connector.

        2. In the **MCP Server URL** field, enter the following URL:

           ```
           https://mcp.cashfree.com/mcp
           ```

        3. Select **Add**.
      </Step>

      <Step title="Authenticate with Cashfree">
        1. Select **Connect**. You are redirected to the **Cashfree Merchant Dashboard**.
        2. Log in with the merchant account that should have access.
        3. Complete the authentication flow and return to Claude Desktop. When the connection is successful, Cashfree tools are available in your Claude session.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="ChatGPT" description="Connect via ChatGPT's Developer mode apps." icon="openai" iconType="brands">
    Follow these steps to add the Cashfree MCP server through ChatGPT's Developer mode and connect your merchant account.

    <Steps>
      <Step title="Enable Developer mode">
        1. Log in to ChatGPT.
        2. Select your profile icon, then select **Settings**.
        3. Select **Apps** and scroll to **Advanced settings**.
        4. Enable **Developer mode**.
      </Step>

      <Step title="Create the Cashfree app">
        1. Go back to **Settings > Apps** and select **Create App**.

        2. Enter a name for the app, for example, **Cashfree Payments**.

        3. In the **MCP Server URL** field, enter the following URL:

           ```
           https://mcp.cashfree.com
           ```

        4. In the **Authentication** field, select **OAuth**.

        5. Select **Advanced OAuth settings** and confirm that all OAuth endpoints are auto-filled.

        6. Select the **I understand and want to continue** checkbox.

        7. Select **Create App**.
      </Step>

      <Step title="Connect and authenticate">
        1. Select the newly added app from the list.
        2. Select **Connect**. You are redirected to the Cashfree Merchant Dashboard.
        3. Log in with the merchant account that should have access. After authentication, Cashfree tools are available in your ChatGPT session.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Cursor" description="Add the Cashfree MCP server via the mcp.json configuration file." icon="https://mintcdn.com/cashfreepayments-d00050e9/Akq7t_Lh0XZPNAh6/static/logo/CUBE_25D.svg?fit=max&auto=format&n=Akq7t_Lh0XZPNAh6&q=85&s=ecc5c6c22042180d614bd099d8d157b0" width="467" height="533" data-path="static/logo/CUBE_25D.svg">
    Follow these steps to add the Cashfree MCP server to Cursor using the `mcp.json` configuration file and authenticate with your merchant account.

    <Steps>
      <Step title="Open MCP settings in Cursor">
        1. Open Cursor and select the gear icon to open **Settings**.
        2. Select **Tools & Integrations** in the left sidebar.
        3. Under **MCP Tools**, select **Add Custom MCP**. This opens the `mcp.json` configuration file.
      </Step>

      <Step title="Add the Cashfree MCP server">
        Add the following configuration to `mcp.json` and save the file:

        ```json theme={"dark"}
        {
          "mcpServers": {
            "cashfree": {
              "url": "https://mcp.cashfree.com/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Authenticate with Cashfree">
        1. Return to **Settings > Tools & Integrations**.
        2. Find the Cashfree entry under **MCP Tools** and select **Needs login**.
        3. A browser window opens and redirects you to the Cashfree Merchant Dashboard.
        4. Log in with the merchant account that should have access. After authentication, Cashfree tools are available in your Cursor session.
      </Step>
    </Steps>

    <Note>
      Cursor handles the OAuth flow automatically. If the browser window does not open, copy the URL from the terminal prompt and open it manually.
    </Note>
  </Accordion>

  <Accordion title="Claude Code" description="Add the server with a single CLI command." icon="https://mintcdn.com/cashfreepayments-d00050e9/Akq7t_Lh0XZPNAh6/static/logo/claude-color.svg?fit=max&auto=format&n=Akq7t_Lh0XZPNAh6&q=85&s=46d9e5cd7ef4faa08d2cb063913eec42" width="16" height="16" data-path="static/logo/claude-color.svg">
    Follow these steps to add the Cashfree MCP server to Claude Code using the CLI and authenticate with your merchant account.

    <Steps>
      <Step title="Add the Cashfree MCP server">
        Run the following command in your terminal:

        ```bash theme={"dark"}
        claude mcp add --transport http cashfree https://mcp.cashfree.com/mcp
        ```
      </Step>

      <Step title="Authenticate with Cashfree">
        1. In your Claude Code session, run the `/mcp` command.
        2. Select **cashfree** from the list of servers, then select **Login**.
        3. A browser window opens and redirects you to the Cashfree Merchant Dashboard.
        4. Log in with the merchant account that should have access. After authentication, Cashfree tools are available in your Claude Code session.
      </Step>
    </Steps>

    <Note>
      Claude Code stores your authentication token securely in your system keychain (macOS) or a credentials file. To revoke access, run `/mcp`, select the server, and select **Clear authentication**.
    </Note>
  </Accordion>
</AccordionGroup>

<Note>
  A connected client is an application that has completed the OAuth handshake. Disconnecting a client immediately revokes the refresh token tied to that authorisation grant.
</Note>

## Verify your setup

After completing the configuration, follow these steps to confirm the MCP Server is working correctly.

1. Restart your MCP client to apply the configuration.
2. Confirm that the Cashfree tools load without errors in your AI client.
3. Run a test prompt such as: "Show me the full lifecycle of a recent transaction." A successful response confirms that the connection is active.

## Available tools

The MCP Server exposes tools grouped by product area. Use these tools to interact with the Merchant Dashboard and Payment Gateway from your AI agent or development environment.

<AccordionGroup>
  <Accordion title="Merchant dashboard tools" icon="chart-line-up">
    Use these tools to monitor and manage your merchant account directly from your AI agent. You can search transactions and orders, track settlement timelines, check unsettled balances, calculate on-demand withdrawal charges, and generate or download reconciliation reports, all without opening the Merchant Dashboard.

    #### Transaction tools

    The following tools let you query individual transactions, search orders, and retrieve the payment methods available on your account.

    | Tool name                 | Description                                             |
    | ------------------------- | ------------------------------------------------------- |
    | `get_transaction_details` | View the complete lifecycle of a single transaction.    |
    | `search_transactions`     | Search for payment transactions matching given filters. |
    | `search_orders`           | Search for orders matching given filters.               |
    | `get_payment_modes`       | Retrieve the merchant's available payment method codes. |
    | `search_product_docs`     | Search across Cashfree Payments product documentation.  |

    #### Settlement tools

    The following tools cover standard scheduled settlements and on-demand instant withdrawals.

    | Tool name                                    | Description                                                            |
    | -------------------------------------------- | ---------------------------------------------------------------------- |
    | `get_unsettled_amount`                       | Get the total unsettled amount held by Cashfree.                       |
    | `get_next_settlement_date`                   | Get the merchant's next settlement date and holiday information.       |
    | `search_standard_settlements`                | Search standard (scheduled) settlements with filtering and pagination. |
    | `get_standard_settlement_details`            | Get the real-time transfer timeline for specific settlements.          |
    | `get_on_demand_settlement_activation_status` | Get the on-demand settlement activation status.                        |
    | `get_on_demand_daily_limit`                  | Get the on-demand settlement maximum daily limit.                      |
    | `get_on_demand_eligible_funds`               | Get eligible funds for an on-demand settlement withdrawal.             |
    | `get_on_demand_charges`                      | Calculate exact charges for a specific on-demand withdrawal amount.    |
    | `search_on_demand_settlements`               | Search on-demand (instant withdrawal) settlements.                     |
    | `get_instant_settlement_rates`               | Get instant and on-demand settlement charge rates.                     |
    | `get_merchant_free_trial_credits`            | Get merchant free trial credits for on-demand settlements.             |
    | `search_vendor_settlements`                  | Search vendor (split) settlements with filtering and pagination.       |
    | `get_vendor_settlement_details`              | Get the real-time transfer timeline for specific vendor settlements.   |
    | `get_settlement_recon_routes`                | Get settlement reconciliation gateway routes.                          |

    #### Report tools

    The following tools let you generate, check the status of, and download settlement and summary reports.

    | Tool name                 | Description                                                 |
    | ------------------------- | ----------------------------------------------------------- |
    | `list_reports`            | List all previously generated reports for this merchant.    |
    | `generate_recon_report`   | Generate a settlement reconciliation report asynchronously. |
    | `generate_summary_report` | Generate a summary or download report asynchronously.       |
    | `get_report_status`       | Get report status and details (polling endpoint).           |
    | `download_report`         | Download a completed report with an auto-shortened URL.     |
  </Accordion>

  <Accordion title="Payment gateway tools" icon="credit-card">
    Use these tools to manage the full payment lifecycle through your AI agent. You can create and cancel payment links, place and retrieve orders, fetch payment details, process refunds, and simulate payments in a sandbox environment.

    The following table lists all available Payment Gateway tools.

    | Tool name                       | Description                                                                |
    | ------------------------------- | -------------------------------------------------------------------------- |
    | `cancel_payment_link`           | Cancel an active payment link. Payments cannot be made after cancellation. |
    | `create_order`                  | Create an order to obtain a `payment_session_id`.                          |
    | `create_payment_link`           | Create a new payment link.                                                 |
    | `create_refund`                 | Initiate a refund for a payment.                                           |
    | `fetch_payment_link_details`    | View details and the current status of a payment link.                     |
    | `fetch_simulation`              | Retrieve details of a simulated payment.                                   |
    | `get_order`                     | Fetch details of an order using the order ID.                              |
    | `get_order_extended`            | Get additional order data, such as address, cart, and customer details.    |
    | `get_orders_for_a_payment_link` | View all orders associated with a payment link.                            |
    | `get_payment_by_id`             | View payment details using a payment ID.                                   |
    | `get_payments_for_an_order`     | View all payment attempts associated with an order.                        |
    | `get_refund`                    | Retrieve details of a specific refund.                                     |
    | `simulate_payment`              | Simulate a payment (requires a valid pre-created order).                   |
  </Accordion>
</AccordionGroup>

## Use cases

The following use cases show how merchants can use the MCP Server to handle real operational tasks using natural language, without opening the Cashfree Merchant Dashboard or writing any code.

### Transaction and order management

The following scenarios show how the MCP Server helps you search, trace, and investigate transactions and orders.

<AccordionGroup>
  <Accordion title="Trace a failed customer payment instantly">
    A customer contacts your support team reporting that their payment did not go through. Instead of logging in and navigating the dashboard, ask your AI agent: "Show me the full lifecycle of transaction TXN123456." The agent uses `get_transaction_details` to retrieve every state the transaction passed through, including the failure reason, payment mode, and timestamp.
  </Accordion>

  <Accordion title="Find all failed orders in a date range">
    Your support team receives multiple complaints after a payment gateway outage. Ask your AI agent: "Find all failed orders between 10 AM and 2 PM today." The agent uses `search_transactions` and `search_orders` with the relevant filters and returns a list you can act on immediately.
  </Accordion>

  <Accordion title="Check which payment methods are currently active">
    Before launching a promotional campaign that offers cashback on UPI payments, ask your AI agent: "What payment methods are available for my account?" The agent uses `get_payment_modes` to return the current list of active payment method codes for your merchant account.
  </Accordion>
</AccordionGroup>

### Settlement and cash flow

The following scenarios show how the MCP Server helps you monitor unsettled balances, track settlement timelines, and evaluate on-demand withdrawal options in real time.

<AccordionGroup>
  <Accordion title="Check your cash position at the end of the day">
    Before closing the books for the day, ask your AI agent: "How much is unsettled right now, and when will it reach my bank?" The agent uses `get_unsettled_amount` and `get_next_settlement_date` to return your current unsettled balance, the next settlement date, and any bank holiday delays.
  </Accordion>

  <Accordion title="Reconcile last week's settlements">
    Your finance team needs to verify that all settlements for the previous week matched expected amounts. Ask your AI agent: "Show me all standard settlements from Monday to Friday last week." The agent uses `search_standard_settlements` with a date filter and returns a paginated list. For each settlement, you can follow up with `get_standard_settlement_details` to see the real-time transfer timeline.
  </Accordion>

  <Accordion title="Decide whether to withdraw funds on demand">
    Your business needs cash urgently before the next scheduled settlement. Ask your AI agent: "How much can I withdraw on demand right now, and what will it cost me to withdraw ₹1,00,000?" The agent uses `get_on_demand_eligible_funds` to return available funds and then uses `get_on_demand_charges` to calculate the exact fee for the amount specified, so you can make an informed decision before initiating a withdrawal.
  </Accordion>

  <Accordion title="Review on-demand settlement costs before enabling the feature">
    Your finance team wants to understand the cost of instant settlements before recommending them to leadership. Ask your AI agent: "What are the current instant settlement rates, and do I have any free trial credits remaining?" The agent uses `get_instant_settlement_rates` and `get_merchant_free_trial_credits` to return both values.
  </Accordion>
</AccordionGroup>

### Reporting

The following scenarios show how the MCP Server helps you generate, track, and download settlement and summary reports using a natural language prompt.

<AccordionGroup>
  <Accordion title="Generate a month-end reconciliation report without logging in">
    At the end of the month, your accounts team needs a full settlement reconciliation report. Ask your AI agent: "Generate a settlement reconciliation report for the month of May." The agent uses `generate_recon_report` to trigger the report, polls `get_report_status` until it is ready, and then uses `download_report` to return a download link. No manual steps or dashboard access are required.
  </Accordion>

  <Accordion title="Download a summary report for a specific date range">
    Your operations manager needs a summary of all transactions for a quarterly review. Ask your AI agent: "Generate a summary report for Q1." The agent uses `generate_summary_report`, polls for completion, and returns the download link.
  </Accordion>

  <Accordion title="List all previously generated reports">
    Before generating a new report, your team wants to check whether one already exists. Ask your AI agent: "Show me all reports generated in the last 30 days." The agent uses `list_reports` to return the full list with their statuses and generation dates.
  </Accordion>
</AccordionGroup>

### Payments and collections

The following scenarios show how the MCP Server helps you create and manage payment links, process refunds, and handle disputes directly from your AI client.

<AccordionGroup>
  <Accordion title="Create a payment link and share it instantly">
    A sales representative needs to collect payment from a customer immediately, without raising an invoice or setting up a checkout page. Ask your AI agent: "Create a ₹5,000 payment link for customer Rahul Sharma, valid for 24 hours, with the description 'Order #ORD-2025-441'." The agent uses `create-payment-link` to generate the link instantly. The representative can then share it over WhatsApp, SMS, or email. No dashboard login or additional integration is required.
  </Accordion>

  <Accordion title="Check the status of a payment link">
    A customer says they received a payment link but are unsure whether it is still active. Ask your AI agent: "What is the current status of payment link PLK123456? Has it been paid?" The agent uses `fetch-payment-link-details` to return the link status, expiry time, and whether a successful payment has been recorded against it.
  </Accordion>

  <Accordion title="Find all orders placed through a payment link">
    After running a sale campaign using a single payment link shared across multiple customers, ask your AI agent: "Show me all orders placed through payment link PLK123456." The agent uses `get-orders-for-a-payment-link` to return every order associated with that link, including order IDs, amounts, and statuses. You can use this to reconcile collections from the campaign.
  </Accordion>

  <Accordion title="Cancel a payment link before it is used">
    A payment link was created with the wrong amount or sent to the wrong customer. Ask your AI agent: "Cancel payment link PLK123456 immediately." The agent uses `cancel-payment-link` to deactivate the link. No further payments can be made against it after cancellation.
  </Accordion>

  <Accordion title="Investigate a customer dispute about a payment">
    A customer insists they completed a payment, but your system shows the order as unpaid. Ask your AI agent: "Show me all payment attempts for order ORD789." The agent uses `get-payments-for-an-order` to return every attempt, including status, payment mode, and failure reason, so you can identify whether the payment succeeded, failed, or is pending.
  </Accordion>

  <Accordion title="Process a refund and track its status">
    A customer requests a refund for a returned product. Ask your AI agent: "Initiate a full refund for payment PAY456." The agent uses `create-refund` to submit the refund request. To check progress, ask: "What is the status of the refund for PAY456?" The agent uses `get-refund` to return the current status and expected credit date.
  </Accordion>

  <Accordion title="Respond to a chargeback dispute">
    Your finance team receives a chargeback for an order the customer claims was not delivered. Ask your AI agent: "Show me all disputes for order ORD321." The agent uses `get-disputes-by-order-id` to retrieve the dispute details. If delivery was confirmed, ask: "Submit evidence to contest dispute DSP001, and attach the delivery confirmation." The agent uses `submit-evidence-to-contest-the-dispute-by-dispute-id` to file the response.
  </Accordion>

  <Accordion title="Test a payment flow in sandbox">
    Before going live with a new checkout integration, ask your AI agent: "Simulate a successful UPI payment for order ORD\_TEST\_001." The agent uses `simulate-payment` to trigger the simulation and `fetch-simulation` to return the result, so you can verify your integration without processing a real payment.
  </Accordion>
</AccordionGroup>