PayMCP

PayMCP is an MCP server that audits Razorpay payment integrations in Next.js App Router + TypeScript projects.

It helps AI coding agents and developers detect common payment-integration mistakes before they become security or production problems.

PayMCP is verification-first and read-only:

• 🔍 Inspects your project statically

• 🔐 Detects common payment-security mistakes

• 📊 Produces a deterministic engineering score

• 🧾 Returns redacted evidence

• 🧪 Provides Test Mode readiness checks

• 🛠️ Explains audit findings

• 💡 Suggests fixes without modifying your files

Important: A PayMCP static PASS is not a payment, compliance, security, or production certification.

What PayMCP Does

A typical Razorpay integration has several places where things can go wrong:

                    Your Next.js App
                           │
            ┌──────────────┼──────────────┐
            │              │              │
       Create Order     Checkout      Webhook
            │              │              │
            ▼              ▼              ▼
       Razorpay API      Client       Your Server
                           │
                           ▼
                    Verify Signature
                           │
                           ▼
                       Fulfill

PayMCP examines your implementation and looks for problems such as:

• Razorpay secrets exposed to the client

• Hardcoded API keys

• Client-controlled payment amounts

• Missing payment signature verification

• Missing webhook verification

• Incorrect webhook-body handling

• Incorrect webhook-secret configuration

• Client-side fulfillment before verification

• Fulfillment before payment confirmation

• Missing idempotency protection

• Capture confirmation problems

• Test/Live environment mixing

• Unsafe refund authorization

Supported Stack

PayMCP V0.1 currently focuses on:

Quick Start

If you only want to get PayMCP running, follow these steps.

Step 1 — Install Node.js

PayMCP is a Node.js application.

Install a current supported Node.js version from:

Node.js

Check your installation:

node --version
npm --version

Step 2 — Install PayMCP

Related MCP server: shipcheck-mcp

Option A — Recommended: npx

npx -y paymcp-security

This downloads and runs the published PayMCP package directly. No global installation is required.

Option B — Global installation

npm install -g paymcp-security

Then run:

paymcp-security

If paymcp-security has not yet been published to npm, use the GitHub installation method below.

Step 3 — Install from GitHub

For development or pre-publication use:

git clone https://github.com/SKSAMIMGOOD/PayMCP.git
cd PayMCP
npm install

Build the project:

npm run build

Start the MCP server:

node dist/index.js

You normally do not need to manually start this process when your MCP client is configured to launch PayMCP for you.

Step 4 — Connect PayMCP to Your MCP Client

PayMCP uses the MCP stdio transport.

Your MCP client needs to know:

1. What command to run

2. Which PayMCP executable to use

3. Where the project being audited is located

The exact configuration format depends on the MCP client.

Option A — Using npx

After PayMCP is published to npm:

{
  "mcpServers": {
    "paymcp": {
      "command": "npx",
      "args": ["-y", "paymcp-security"]
    }
  }
}

This allows the MCP client to launch PayMCP using npx.

Option B — Using a global installation

If you installed:

npm install -g paymcp-security

use:

{
  "mcpServers": {
    "paymcp": {
      "command": "paymcp-security"
    }
  }
}

Option C — Using the local GitHub build

If you cloned the repository and built it locally:

npm run build

your MCP configuration can point directly to:

dist/index.js

Example:

{
  "mcpServers": {
    "paymcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/PayMCP/dist/index.js"
      ]
    }
  }
}

Windows example

{
  "mcpServers": {
    "paymcp": {
      "command": "node",
      "args": [
        "C:\\Users\\YourName\\PayMCP\\dist\\index.js"
      ]
    }
  }
}

macOS/Linux example

{
  "mcpServers": {
    "paymcp": {
      "command": "node",
      "args": [
        "/Users/YourName/PayMCP/dist/index.js"
      ]
    }
  }
}

Use an absolute path for the local build.

Step 5 — Restart Your MCP Client

After adding PayMCP to your MCP configuration:

1. Save the configuration.

2. Completely restart your MCP client.

3. Open your Next.js project.

4. Check that PayMCP is available as an MCP server/tool.

The exact UI and configuration location varies between MCP clients.

Step 6 — Give PayMCP Your Project Root

PayMCP intentionally does not automatically scan your computer.

Every filesystem operation requires an explicit:

projectRoot

For example:

C:\Users\YourName\Projects\my-store

or:

/Users/YourName/projects/my-store

This is an important part of PayMCP's security model.

Why?

Instead of giving the MCP server broad access like:

C:\

you give it only:

C:\Users\YourName\Projects\my-store

PayMCP then restricts project file access to that supplied root.

Your First Audit

Once PayMCP is connected, open the Next.js project you want to inspect.

Then ask your AI coding agent something like:

Audit my Razorpay payment integration using PayMCP. Use my current project as the projectRoot and explain every security finding.

Your MCP client should use:

audit_payment_integration

with the appropriate project root.

Conceptually:

{
  "projectRoot": "/absolute/path/to/my-nextjs-project"
}

PayMCP will inspect the project without modifying it.

What the Audit Returns

The audit provides structured results containing information such as:

Audit
├── Findings
│   ├── severity
│   ├── confidence
│   ├── rule
│   └── redacted evidence
│
├── Engineering Score
│
├── Test Mode Readiness
│
└── Caveats

The evidence is deliberately redacted before it is returned over MCP.

Understanding the PayMCP Tools

PayMCP provides several MCP tools.

1. list_payment_providers

Shows the payment providers and technology stacks supported by PayMCP.

Current V0.1 support includes:

Razorpay
Next.js App Router
TypeScript

Use this when you want to check whether your project is supported.

2. get_payment_requirements

Returns the security and architecture requirements PayMCP expects for a Razorpay + Next.js integration.

Useful before implementing a payment system.

Example request to your AI agent:

Show me the Razorpay payment requirements supported by PayMCP.

3. audit_payment_integration

This is the main static auditing tool.

It examines the project for known payment-integration problems.

Example:

Audit my Razorpay integration and show me all high-confidence security findings.

It can identify issues involving:

• Client-visible secrets

• Hardcoded keys

• Client-controlled amounts

• Signature verification

• Webhooks

• Fulfillment

• Idempotency

• Capture confirmation

• Environment configuration

• Refund authorization

Important

This tool:

Reads project → Analyzes code → Returns findings

It does not:

Modify files
Start your application
Contact Razorpay
Process payments

4. test_payment_integration

This checks the architecture and readiness of the payment integration.

It is a static/readiness check, not a real payment test.

Example:

Check whether my Razorpay integration is ready for Test Mode.

It does not contact Razorpay or your running application.

5. test_payment_transaction

This is different from the static audit.

It performs a controlled Test Mode runtime validation against an already-running application.

Important restrictions:

• Requires an explicit base URL

• Uses secure host-environment credentials

• Never accepts secrets as tool arguments

• Never starts your project commands

• Does not perform uncontrolled live transactions

• Stops for manual checkout

For example, your application might already be running at:

http://localhost:3000

Then the runtime test can validate the controlled payment flow.

Static vs Runtime

                 PayMCP
                    │
          ┌─────────┴─────────┐
          │                   │
      STATIC AUDIT       RUNTIME TEST
          │                   │
          ▼                   ▼
    Read source code      Running app
          │                   │
          ▼                   ▼
    Find architecture     Test controlled
       problems            Test Mode flow

A static PASS and runtime result are separate pieces of evidence.

6. generate_payment_integration

This provides a deterministic, self-audited dry-run implementation plan.

It does not write source files.

Think of it as:

Requirements
     ↓
Implementation plan
     ↓
Self-audit
     ↓
File/change plan

It is useful when you want to plan a Razorpay integration before actually implementing it.

Example:

Generate a Razorpay payment integration plan for this Next.js project, but do not modify any files.

7. debug_payment

This explains existing audit findings.

Example:

Explain the Razorpay security findings from the PayMCP audit and tell me why each one matters.

It is:

• Read-only

• Deterministic

• Static

It does not modify your project or contact Razorpay.

8. suggest_payment_fix

This creates a read-only, evidence-based plan that an AI coding agent can use to manually fix an issue.

Example:

Suggest fixes for the payment audit findings, but don't modify my files.

The important distinction is:

PayMCP
   │
   ├── Detects problem
   ├── Explains problem
   └── Suggests fix
             │
             ▼
      AI coding agent
             │
             ▼
       Developer approves
             │
             ▼
       Code is modified

PayMCP itself does not modify your project.

Recommended Workflow

For a real project, I recommend using the tools in this order:

        ┌─────────────────────┐
        │  Existing Next.js   │
        │      project         │
        └──────────┬──────────┘
                   │
                   ▼
       ┌───────────────────────┐
       │ list_payment_providers│
       └───────────┬───────────┘
                   │
                   ▼
       ┌───────────────────────┐
       │ get_payment_requirements
       └───────────┬───────────┘
                   │
                   ▼
       ┌───────────────────────┐
       │ audit_payment_        │
       │ integration            │
       └───────────┬───────────┘
                   │
                   ▼
             Findings?
              /      \
            YES       NO
             │         │
             ▼         ▼
       debug_payment  Test Mode
             │        readiness
             ▼
       suggest_payment_fix
             │
             ▼
       Developer/AI agent
          applies fixes
             │
             ▼
       Run audit again
             │
             ▼
       test_payment_transaction
             │
             ▼
       Manual Test Mode checkout

Example Prompts

You don't need to manually understand MCP JSON to use PayMCP.

Your AI coding agent can invoke the appropriate tools based on your request.

Basic audit

Audit my Razorpay integration using PayMCP.

Security audit

Perform a security-focused audit of my Razorpay payment integration. Identify secrets, signature verification, webhook, amount manipulation, and fulfillment issues.

Explain findings

Explain every PayMCP finding in simple terms and tell me what could go wrong in production.

Fix planning

Create a safe implementation plan to fix all PayMCP findings. Do not modify my files.

Test readiness

Check whether my Razorpay integration is ready for Test Mode.

Re-audit after changes

Re-run the PayMCP audit and compare the current implementation against the previous findings.

Security Model

PayMCP is designed to minimize filesystem and credential exposure.

Project access

Filesystem reads are restricted to the supplied:

projectRoot

PayMCP rejects:

• Directory traversal

• Symlink escapes

Files PayMCP does not read

.env files are excluded.

Dependency/build directories and binaries are also skipped.

Individual file reads are capped at:

1 MB

Secrets

PayMCP does not require you to put payment secrets into MCP tool arguments.

Never put Razorpay secrets into source code.

Your Razorpay Key Secret should remain server-side and should be managed through environment variables or an appropriate secrets-management system.

PayMCP's audit is designed to detect unsafe secret exposure without intentionally exposing the secret itself.

Important: What PayMCP Does NOT Do

PayMCP is not a payment gateway.

It does not:

• Process payments

• Hold money

• Store Razorpay credentials

• Perform live transactions

• Replace Razorpay

• Guarantee production security

• Guarantee PCI/compliance status

• Automatically modify your application

• Deploy your application

• Host your application

The relationship is:

Razorpay
    │
    │ Payment processing
    ▼
Your Next.js application
    │
    │ Source code
    ▼
PayMCP
    │
    ├── Audit
    ├── Verify architecture
    ├── Explain findings
    └── Suggest fixes

Test Mode

PayMCP supports a deliberately constrained Test Mode runtime workflow.

For development:

Use Razorpay Test Mode
        ↓
Create Test Mode keys
        ↓
Configure your application
        ↓
Run your application
        ↓
Use PayMCP static audit
        ↓
Use PayMCP runtime validation
        ↓
Complete manual checkout when requested

Do not use Live Mode credentials for development.

Development

Clone the repository:

git clone https://github.com/SKSAMIMGOOD/PayMCP.git
cd PayMCP

Install dependencies:

npm install

Run type checking:

npm run typecheck

Run tests:

npm test

Build:

npm run build

Run the built server:

node dist/index.js

Audit Rules

The P0 static rules cover areas including:

• Client-visible secrets

• Hardcoded key literals

• Client-controlled amounts

• Missing payment verification

• Missing webhook verification

• Raw webhook-body misuse

• Webhook secret configuration

• Client-side fulfillment

• Pre-verification fulfillment

• Idempotency

• Capture confirmation

• Environment mixing

• Refund authorization

Findings include confidence levels because static source inspection cannot prove every aspect of runtime behavior.

Static Analysis Limitations

Static analysis has limits.

For example, PayMCP can identify code patterns that strongly indicate missing signature verification.

However, source inspection alone cannot prove:

"the production webhook always behaves correctly"

or:

"the Razorpay dashboard is configured correctly"

Therefore PayMCP reports confidence levels and caveats.

Think of the result as:

Engineering evidence
        ≠
Production certification

Troubleshooting

PayMCP does not appear in my MCP client

Check:

1. Node.js is installed.

2. PayMCP builds successfully.

3. The MCP configuration is valid.

4. The executable/path is correct.

5. You restarted the MCP client.

6. The path to dist/index.js is absolute when using a local build.

npx paymcp-security does not work

If the npm package has not yet been published, use the GitHub installation:

git clone https://github.com/SKSAMIMGOOD/PayMCP.git
cd PayMCP
npm install
npm run build
node dist/index.js

Then configure your MCP client to use the local build.

Audit cannot access my project

Make sure the MCP request contains an explicit:

projectRoot

and that it points to the root directory of your project.

For example:

C:\Users\YourName\Projects\my-shop

not:

C:\

Why doesn't PayMCP read my .env file?

This is intentional.

PayMCP is designed to avoid reading .env files and exposing credentials through the MCP interface.

You should never need to send your Razorpay Key Secret to PayMCP as a tool argument.

Frequently Asked Questions

Does PayMCP modify my code?

No.

The audit, testing, debugging, and suggestion workflows are designed to be read-only.

Does PayMCP contact Razorpay?

Static auditing does not contact Razorpay.

The controlled test_payment_transaction workflow is specifically designed for Test Mode runtime validation and is separate from the static audit.

Does PayMCP store my Razorpay credentials?

No.

PayMCP does not provide credential storage or hosted credential management.

Can I use PayMCP with any payment provider?

Not currently.

V0.1 is intentionally focused on:

Razorpay + Next.js App Router + TypeScript

Does a PASS mean my payment system is secure?

No.

A PASS means PayMCP did not identify the problems covered by its current static rules/readiness checks.

It is not a security certification, compliance certification, or guarantee that your production payment system is safe.

Documentation

Detailed documentation:

• Agent Audit Workflow

• Generator

• Runtime Testing

Repository

GitHub:

PayMCP on GitHub

License

MIT License.

Runtime validation is documented in runtime-testing.md. A static PASS and runtime result remain separate evidence.

License

MIT