Integrate OAuth 2.0 with Razorpay MCP Server

The Razorpay MCP Server uses OAuth 2.0 to authenticate MCP clients securely. OAuth provides enhanced security compared to using secret keys directly, as it enables granular permissions and user-based authorisation.

Benefits

Enhanced Security: No need to share API secret keys directly.
Granular Permissions: Control access at a more detailed level.
User-Based Authorisation: Individual user consent and access management.
Token Expiration: Temporary access tokens that can be refreshed or revoked.

OAuth Flow

The Razorpay MCP Server implements the OAuth 2.0 Authorisation Code flow. Here is how the integration works:

Discover Endpoints: Retrieve OAuth endpoints from the well-known configuration.
Request Authorisation: Direct users to the authorisation endpoint.
Receive Authorisation Code: Handle the callback with the temporary code.
Exchange for Access Token: Trade the authorisation code for an access token.
Access MCP Tools: Use the access token to call Razorpay MCP Server tools.

Integration Steps

Step 1: Discover OAuth Endpoints

Before starting the OAuth flow, retrieve the available endpoints and supported configurations using the well-known endpoint.

GET

.well-known/oauth-authorization-server

curl -X GET https://mcp.razorpay.com/.well-known/oauth-authorization-server

Response Parameters

issuer

string The OAuth 2.0 issuer identifier.

authorization_endpoint

string The URL for requesting user authorisation.

token_endpoint

string The URL for exchanging authorisation codes for tokens.

scopes_supported

array List of available OAuth scopes.

response_types_supported

array Supported OAuth response types.

grant_types_supported

array Supported OAuth grant types.

code_challenge_methods_supported

array PKCE (Proof Key for Code Exchange) challenge methods (S256 = SHA-256).

Step 2: Request User Authorisation

Redirect users to the authorisation endpoint to grant access to your application. Write to the

Razorpay Support Team

to generate Client id and secret.

POST

https://mcp.razorpay.com/authorize

https://mcp.razorpay.com/authorize?response_type=code&client_id={YOUR_CLIENT_ID}&redirect_uri={YOUR_REDIRECT_URI}&scope=read_only&state={RANDOM_STATE_VALUE}

Path Parameters

response_type

mandatory

string Must be code for authorisation code flow.

client_id

mandatory

string Your registered client identifier.

redirect_uri

mandatory

string URL where the user will be redirected after authorisation.

scope

mandatory

string Requested permissions. For example, read_only.

state

recommended

string Random string to prevent CSRF attacks.

User Experience

When users visit this URL, they:

Log in to their Razorpay account.
Review the permissions your application is requesting.
Approve or deny access.

Step 3: Handle Authorisation Callback

After the user approves access, Razorpay redirects them to your redirect_uri with an authorisation code.

Callback URL Format

https://cli.tool/callback?code={AUTHORIZATION_CODE}&state={STATE_VALUE}

Callback Parameters

code

string Temporary authorisation code (single-use).

state

string The same state value you sent in the authorisation request.

Security Check

Always verify that the state parameter matches the value you sent in the initial request to prevent CSRF attacks.

Step 4: Exchange Authorisation Code for Access Token

Use the authorisation code to obtain an access token from the token endpoint.

POST

https://mcp.razorpay.com/token

curl -X POST https://mcp.razorpay.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=xyz123" \
  -d "client_secret=secret456" \
  -d "code=authCodeXYZ" \
  -d "redirect_uri=https://cli.tool/callback"

Request Parameters

grant_type

mandatory

string Must be authorization_code.

client_id

mandatory

string Your registered client identifier.

client_secret

conditional

string Required for confidential clients.

code

mandatory

string The authorisation code from

Step 3

redirect_uri

mandatory

string Must match the URI used in the authorisation request.

Response Parameters

access_token

string OAuth bearer token for accessing MCP tools. Use this token in the Authorization header for all API requests.

token_type

string Always Bearer. This indicates the type of token returned.

expires_in

integer Token lifetime in seconds. For example, 3600 = 1 hour. Track this value to refresh tokens before expiration.

scope

string Granted permissions. Indicates which scopes were approved by the user.

Step 5: Use Access Token to Call MCP Tools

Include the access token in the Authorisation header when making requests to Razorpay MCP Server tools.

GET

https://mcp.razorpay.com/api/tool-endpoint

curl -X GET https://mcp.razorpay.com/api/tool-endpoint \
  -H "Authorization: Bearer mcp_access_token_abc123"

Token Management

Token Expiration

Access tokens expire after a set period. Monitor the expires_in value and implement token refresh logic in your application.

Token Storage

Store access tokens securely:

Never commit tokens to version control.
Use environment variables or secure vaults.
Encrypt tokens at rest.
Clear tokens from memory after use.

Token Revocation

If you need to revoke a token before expiration, contact

Razorpay Support team

or implement token management in your application settings.