{ "$comment": "Razorpay MCP Server Card \u2014 comprehensive descriptor for AI agents and developer tools. Covers authentication, deployment, tools, configuration, use cases, and FAQs.", "schema_version": "0.1.0", "name": "Razorpay MCP Server", "description": "Official Razorpay MCP server. Enables AI assistants to execute payment operations via natural language \u2014 create orders, issue refunds, manage payment links, generate QR codes, reconcile settlements, and more. 39 tools spanning the full Razorpay payments stack.", "version": "1.0.0", "serverUrl": "https://mcp.razorpay.com/mcp", "tools": [ "capture_payment", "fetch_payment", "fetch_payment_card_details", "fetch_all_payments", "update_payment", "create_payment_link", "create_payment_link_upi", "fetch_all_payment_links", "fetch_payment_link", "send_payment_link", "update_payment_link", "create_order", "fetch_order", "fetch_all_orders", "update_order", "fetch_order_payments", "create_refund", "fetch_refund", "fetch_all_refunds", "update_refund", "fetch_multiple_refunds_for_payment", "fetch_specific_refund_for_payment", "create_qr_code", "fetch_qr_code", "fetch_all_qr_codes", "fetch_qr_codes_by_customer_id", "fetch_qr_codes_by_payment_id", "fetch_payments_for_qr_code", "close_qr_code", "fetch_all_settlements", "fetch_settlement_with_id", "fetch_settlement_recon_details", "create_instant_settlement", "fetch_all_instant_settlements", "fetch_instant_settlement_with_id", "fetch_all_payouts", "fetch_payout_by_id", "detect_stack", "integrate_razorpay_checkout" ], "serverInfo": { "name": "Razorpay MCP Server", "version": "1.0.0", "description": "Official Razorpay MCP server. Enables AI assistants to execute payment operations via natural language \u2014 create orders, issue refunds, manage payment links, generate QR codes, reconcile settlements, and more. 39 tools spanning the full Razorpay payments stack.", "homepage": "https://razorpay.com", "icon": "https://razorpay.com/favicon.png", "documentation": "https://razorpay.com/docs/build/llm-docs/mcp-server.md", "toolsReference": "https://razorpay.com/docs/build/llm-docs/mcp-server/tools-reference.md", "source": "https://github.com/razorpay/razorpay-mcp-server", "supportedClients": [ "Claude Desktop", "Cursor", "Visual Studio Code", "any MCP-compatible client" ] }, "transport": { "remote": { "type": "http", "url": "https://mcp.razorpay.com/mcp", "description": "Hosted by Razorpay. Recommended for most users \u2014 zero infrastructure, automatic updates." }, "local": { "type": "stdio", "description": "Self-hosted via Docker or built from source. Enables local-only tools (create_refund, close_qr_code, create_instant_settlement).", "docker": "razorpay/razorpay-mcp-server:latest", "source": "https://github.com/razorpay/razorpay-mcp-server" } }, "authentication": { "primary": { "type": "http_basic", "description": "HTTP Basic Auth using Razorpay API keys. Base64-encode key_id:key_secret and pass as Authorization header. This is the primary and recommended method.", "header": "Authorization: Basic ", "encodeCommand": "echo -n 'key_id:key_secret' | base64", "keysUrl": "https://dashboard.razorpay.com/app/keys", "testKeys": "Keys prefixed with rzp_test_ \u2014 use for development and testing", "liveKeys": "Keys prefixed with rzp_live_ \u2014 use for production" }, "oauth2": { "type": "oauth2", "flow": "authorization_code", "pkce": true, "pkceMethod": "S256", "authorizationUrl": "https://mcp.razorpay.com/authorize", "tokenUrl": "https://mcp.razorpay.com/token", "registrationUrl": "https://mcp.razorpay.com/register", "discoveryUrl": "https://mcp.razorpay.com/.well-known/oauth-authorization-server", "tokenEndpointAuthMethod": "client_secret_post", "scopes": [ "read_only" ], "docs": "https://razorpay.com/docs/build/llm-docs/mcp-server/oauth.md", "note": "OAuth endpoints are MCP protocol endpoints \u2014 not browser-navigable. Visiting them directly in a browser will show an error. Use these URLs only in MCP client configuration." } }, "deployment": { "remote": { "recommended": true, "description": "Hosted by Razorpay. No infrastructure to manage, automatic updates, supports all remote tools.", "docs": "https://razorpay.com/docs/build/llm-docs/mcp-server/remote.md", "prerequisites": [ "Node.js (for npx mcp-remote)", "Razorpay API keys" ], "setup": { "claude_desktop": { "configFile": "~/Library/Application Support/Claude/claude_desktop_config.json", "config": { "mcpServers": { "rzp-mcp-server": { "command": "npx", "args": [ "mcp-remote", "https://mcp.razorpay.com/mcp", "--header", "Authorization: Basic " ] } } } }, "cursor": { "config": { "mcpServers": { "rzp-mcp-server": { "command": "npx", "args": [ "mcp-remote", "https://mcp.razorpay.com/mcp", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Basic " } } } } }, "vscode": { "config": { "mcp": { "inputs": [ { "type": "promptString", "id": "merchant_token", "description": "Razorpay Merchant Token (base64-encoded key_id:key_secret)", "password": true } ], "servers": { "razorpay-remote": { "command": "npx", "args": [ "mcp-remote", "https://mcp.razorpay.com/mcp", "--header", "Authorization: Basic ${input:merchant_token}" ] } } } } } } }, "local": { "recommended": false, "description": "Self-hosted via Docker. Required for local-only tools: create_refund, close_qr_code, create_instant_settlement.", "docs": "https://razorpay.com/docs/build/llm-docs/mcp-server/local.md", "prerequisites": { "required": [ "Docker", "Razorpay API keys" ], "sourceBuildsOnly": [ "Git", "Golang" ] }, "buildInstructions": { "docker": [ "git clone https://github.com/razorpay/razorpay-mcp-server.git", "cd razorpay-mcp-server", "docker build -t razorpay-mcp-server:latest ." ], "fromSource": [ "git clone https://github.com/razorpay/razorpay-mcp-server.git", "cd razorpay-mcp-server", "go build -o razorpay-mcp-server ./cmd/razorpay-mcp-server" ] }, "setup": { "claude_desktop": { "configFile": "~/Library/Application Support/Claude/claude_desktop_config.json", "config": { "mcpServers": { "razorpay-mcp-server": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "RAZORPAY_KEY_ID", "-e", "RAZORPAY_KEY_SECRET", "razorpay-mcp-server:latest" ], "env": { "RAZORPAY_KEY_ID": "your_razorpay_key_id", "RAZORPAY_KEY_SECRET": "your_razorpay_key_secret" } } } } }, "vscode": { "config": { "mcp": { "inputs": [ { "type": "promptString", "id": "razorpay_key_id", "description": "Razorpay Key ID", "password": false }, { "type": "promptString", "id": "razorpay_key_secret", "description": "Razorpay Key Secret", "password": true } ], "servers": { "razorpay": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "RAZORPAY_KEY_ID", "-e", "RAZORPAY_KEY_SECRET", "razorpay-mcp-server:latest" ], "env": { "RAZORPAY_KEY_ID": "${input:razorpay_key_id}", "RAZORPAY_KEY_SECRET": "${input:razorpay_key_secret}" } } } } } } } } }, "configuration": { "docs": "https://razorpay.com/docs/build/llm-docs/mcp-server/configuration.md", "environmentVariables": [ { "name": "RAZORPAY_KEY_ID", "type": "string", "required": true, "description": "Your Razorpay API key ID" }, { "name": "RAZORPAY_KEY_SECRET", "type": "string", "required": true, "description": "Your Razorpay API key secret" }, { "name": "TOOLSETS", "type": "string", "required": false, "default": "all", "description": "Comma-separated list of toolsets to enable. Options: payments, payment_links, orders, refunds, qr_codes, settlements, payouts, checkout" }, { "name": "READ_ONLY", "type": "boolean", "required": false, "default": false, "description": "Run server in read-only mode \u2014 disables all write/create/update operations" }, { "name": "LOG_FILE", "type": "string", "required": false, "description": "Path to log file for server logs" } ], "commandLineFlags": [ { "flag": "--key / -k", "description": "Razorpay API key ID" }, { "flag": "--secret / -s", "description": "Razorpay API key secret" }, { "flag": "--toolsets / -t", "description": "Comma-separated list of toolsets to enable" }, { "flag": "--read-only", "description": "Enable read-only mode" }, { "flag": "--log-file / -l", "description": "Path to log file" } ] }, "capabilities": { "tools": true, "resources": false, "prompts": false, "streaming": false }, "tools": { "total": 39, "note": "Tools marked localOnly:true require local server deployment. All others work on both remote and local.", "categories": { "payments": { "description": "Core payment lifecycle operations \u2014 capture, fetch, update payments", "tools": [ { "name": "capture_payment", "description": "Change a payment status from authorised to captured", "localOnly": false }, { "name": "fetch_payment", "description": "Fetch payment details by payment ID (pay_*)", "localOnly": false }, { "name": "fetch_payment_card_details", "description": "Fetch card details used for a payment", "localOnly": false }, { "name": "fetch_all_payments", "description": "Fetch all payments with filtering and pagination", "localOnly": false }, { "name": "update_payment", "description": "Update the notes field of a payment", "localOnly": false } ] }, "payment_links": { "description": "Create, send, and manage shareable payment links", "tools": [ { "name": "create_payment_link", "description": "Create a new standard payment link", "localOnly": false }, { "name": "create_payment_link_upi", "description": "Create a new UPI-specific payment link", "localOnly": false }, { "name": "fetch_all_payment_links", "description": "Fetch all payment links", "localOnly": false }, { "name": "fetch_payment_link", "description": "Fetch details of a specific payment link by ID (plink_*)", "localOnly": false }, { "name": "send_payment_link", "description": "Send a payment link to a customer via SMS or email", "localOnly": false }, { "name": "update_payment_link", "description": "Update a standard payment link", "localOnly": false } ] }, "orders": { "description": "Order creation and lifecycle management. Order creation must be server-side only.", "tools": [ { "name": "create_order", "description": "Create a payment order (order_*). Must be done server-side \u2014 never from client-side code.", "localOnly": false }, { "name": "fetch_order", "description": "Fetch order details by order ID (order_*)", "localOnly": false }, { "name": "fetch_all_orders", "description": "Fetch all orders with filtering", "localOnly": false }, { "name": "update_order", "description": "Update an order", "localOnly": false }, { "name": "fetch_order_payments", "description": "Fetch all payments made against a specific order", "localOnly": false } ] }, "refunds": { "description": "Refund initiation and tracking. create_refund requires local server deployment.", "tools": [ { "name": "create_refund", "description": "Create a full or partial refund for a captured payment. Speed: normal (5-7 days) or optimum (instant if supported). Must be within 180 days of capture.", "localOnly": true }, { "name": "fetch_refund", "description": "Fetch refund details by refund ID (rfnd_*)", "localOnly": false }, { "name": "fetch_all_refunds", "description": "Fetch all refunds with filtering", "localOnly": false }, { "name": "update_refund", "description": "Update the notes field of a refund", "localOnly": false }, { "name": "fetch_multiple_refunds_for_payment", "description": "Fetch all refunds associated with a specific payment", "localOnly": false }, { "name": "fetch_specific_refund_for_payment", "description": "Fetch a specific refund for a specific payment", "localOnly": false } ] }, "qr_codes": { "description": "QR code payment generation and management. close_qr_code requires local server.", "tools": [ { "name": "create_qr_code", "description": "Create a QR code for UPI or card payments", "localOnly": false }, { "name": "fetch_qr_code", "description": "Fetch QR code details by QR code ID", "localOnly": false }, { "name": "fetch_all_qr_codes", "description": "Fetch all QR codes", "localOnly": false }, { "name": "fetch_qr_codes_by_customer_id", "description": "Fetch QR codes associated with a specific customer", "localOnly": false }, { "name": "fetch_qr_codes_by_payment_id", "description": "Fetch QR codes associated with a specific payment", "localOnly": false }, { "name": "fetch_payments_for_qr_code", "description": "Fetch all payments received via a specific QR code", "localOnly": false }, { "name": "close_qr_code", "description": "Close a QR code to stop accepting new payments", "localOnly": true } ] }, "settlements": { "description": "Settlement tracking and reconciliation. create_instant_settlement requires local server.", "tools": [ { "name": "fetch_all_settlements", "description": "Fetch all settlements", "localOnly": false }, { "name": "fetch_settlement_with_id", "description": "Fetch settlement details by settlement ID", "localOnly": false }, { "name": "fetch_settlement_recon_details", "description": "Fetch the settlement reconciliation report for detailed line-item breakdown", "localOnly": false }, { "name": "create_instant_settlement", "description": "Create an instant settlement to transfer funds to your bank account immediately", "localOnly": true }, { "name": "fetch_all_instant_settlements", "description": "Fetch all instant settlements", "localOnly": false }, { "name": "fetch_instant_settlement_with_id", "description": "Fetch a specific instant settlement by ID", "localOnly": false } ] }, "payouts": { "description": "Read-only payout operations via RazorpayX. Creating payouts requires direct REST API calls.", "tools": [ { "name": "fetch_all_payouts", "description": "Fetch all payouts for a RazorpayX account number", "localOnly": false }, { "name": "fetch_payout_by_id", "description": "Fetch payout details by payout ID (pout_*)", "localOnly": false } ] }, "checkout": { "description": "AI-assisted checkout integration \u2014 detect project stack and generate Razorpay Checkout code", "tools": [ { "name": "detect_stack", "description": "Detect the project language and framework for checkout integration guidance", "localOnly": false }, { "name": "integrate_razorpay_checkout", "description": "Generate Razorpay Checkout integration code tailored to the detected stack", "localOnly": false } ] } }, "localOnlyTools": [ "create_refund", "close_qr_code", "create_instant_settlement" ] }, "rateLimiting": { "throttleStatusCode": 429, "errorMessage": "The server is processing too many requests and is unable to process your request. Retry after some time.", "recommendedStrategy": "exponential backoff with jitter", "note": "Razorpay does not publish specific rate limit quotas. Monitor for HTTP 429 and implement retry logic with exponential or stepped backoff. Add randomisation to backoff schedules to avoid thundering herd effects.", "docs": "https://razorpay.com/docs/build/llm-docs/api/understand.md" }, "useCases": [ { "title": "Generate payment links without dashboard access", "description": "Support and sales teams can create and send payment links instantly via natural language \u2014 no dashboard or developer involvement needed.", "tools": [ "create_payment_link", "create_payment_link_upi", "send_payment_link" ] }, { "title": "Transaction lookup and customer support", "description": "Fetch payment details, check status, and diagnose failures instantly for customer support queries.", "tools": [ "fetch_payment", "fetch_all_payments", "fetch_order_payments" ] }, { "title": "Refund processing", "description": "Issue full or partial refunds for captured payments. Requires local MCP server deployment.", "tools": [ "fetch_payment", "create_refund", "fetch_refund" ], "requirement": "local server only" }, { "title": "Settlement reconciliation", "description": "Finance teams can query settlement data and reconciliation reports without exporting CSVs from the dashboard.", "tools": [ "fetch_all_settlements", "fetch_settlement_recon_details", "fetch_settlement_with_id" ] }, { "title": "Payment failure analysis", "description": "Fetch payments over a date range and analyse failure trends and patterns.", "tools": [ "fetch_all_payments", "fetch_payment" ] }, { "title": "QR code payment collection", "description": "Create QR codes for in-person UPI or card payments, track payments received, and close QR codes when done.", "tools": [ "create_qr_code", "fetch_payments_for_qr_code", "close_qr_code" ], "note": "close_qr_code requires local server" }, { "title": "Checkout integration scaffolding", "description": "AI detects your project stack and generates ready-to-use Razorpay Checkout integration code.", "tools": [ "detect_stack", "integrate_razorpay_checkout" ] } ], "faqs": [ { "question": "What is MCP (Model Context Protocol)?", "answer": "An open standard that allows AI models to interact with external tools and services. It enables assistants like Claude to execute real operations on external platforms through standardized interfaces." }, { "question": "Can I use this in production?", "answer": "Yes. The Razorpay MCP Server is an official integration designed for production use. Use rzp_live_* keys for production and rzp_test_* keys for development." }, { "question": "How do I switch between test and live modes?", "answer": "Use the corresponding API keys. Keys starting with rzp_test_ use sandbox. Keys starting with rzp_live_ use production. The server determines the environment from your credentials automatically." }, { "question": "What is the difference between Remote and Local deployment?", "answer": "Remote is hosted by Razorpay \u2014 zero infrastructure, automatic updates, recommended for most users. Local is self-hosted via Docker, required for three write tools: create_refund, close_qr_code, and create_instant_settlement." }, { "question": "Why do OAuth URLs return an error when opened in a browser?", "answer": "The OAuth endpoints (mcp.razorpay.com/authorize, /token, /register) are MCP protocol endpoints, not browser-navigable URLs. They are called by MCP clients during the OAuth handshake, not directly by users. See https://razorpay.com/docs/build/llm-docs/mcp-server/oauth.md for integration instructions." }, { "question": "Can agents create payouts via MCP?", "answer": "No. The MCP server only supports read-only payout operations (fetch_all_payouts, fetch_payout_by_id). Creating payouts requires direct REST API calls to https://api.razorpay.com/v1/payouts." }, { "question": "Does the MCP server support subscriptions?", "answer": "No. Subscription management is not available via MCP tools. Use the Razorpay REST API directly at https://api.razorpay.com/v1/subscriptions." }, { "question": "Which AI clients are supported?", "answer": "Claude Desktop, Cursor, Visual Studio Code (with MCP extension), and any MCP-compatible client. See the deployment section for client-specific configuration." } ] }