The Ryft MCP server is a Model Context Protocol interface for Ryft's payments API, enabling full lifecycle management of financial resources across multiple deployment options (stdio, HTTP, AWS Lambda).
Customer Management – Create, retrieve, update, delete, and list customers; list stored payment methods.
Payment Sessions – Create, retrieve, update, capture, void, and refund (full or partial) payment sessions; continue payments after 3DS authentication; list and retrieve associated transactions.
Subscriptions – Create, retrieve, update, cancel, and list subscriptions; retrieve associated payment sessions.
Accounts – Create, retrieve, update, and verify business/individual/hosted accounts; generate authorization links and temporary account links for hosted sub-accounts.
Payment Methods – Retrieve, update billing address, and delete payment methods.
Webhooks – Create, retrieve, update, delete, and list webhook endpoints.
Persons – Create, retrieve, update, delete, and list persons associated with business accounts.
Payout Methods & Payouts – Manage payout methods (bank accounts); create, list, and retrieve payouts.
Transfers – Create, list, and retrieve transfers between accounts.
Files – Upload (Evidence, VerificationDocument, Report), retrieve, and list files.
Platform Fees – List and retrieve platform fees and their refunds.
Events – List and retrieve Ryft events with optional account scoping.
Disputes – List, retrieve, accept, or challenge disputes; add and delete evidence.
Balances – List balances by currency and list balance transactions.
Health Monitoring – Check server configuration state without exposing secrets.
Authentication is handled via environment variables, with support for optional default account scoping.
Enables serverless deployment of the Ryft MCP server to AWS Lambda for stateless MCP over HTTPS, providing a dedicated Lambda handler entrypoint, build scripts for generating deployment artifacts, and configuration support for running as a serverless function with environment variable-based authentication.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Ryft MCP list my 10 most recent payouts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ryft-mcp is a Model Context Protocol server for the Ryft API.
It gives MCP clients a clean interface for working with Ryft resources such as customers, payment sessions, subscriptions, webhooks, accounts, payouts, disputes, files, and more.
The Ryft MCP server is deployed and ready to use. Add it to your MCP client with your Ryft secret key.
Important: Your Ryft secret key may contain special characters such as
/and+. Make sure to copy the full key exactly — truncating or escaping these characters will cause authentication failures (403 errors). After adding the server, restart your MCP client to pick up the new configuration.
Claude Desktop does not support custom authentication headers for remote MCP servers via config file. Use the stdio transport instead:
Clone this repository and install dependencies:
git clone https://github.com/bkawk/ryft-mcp.git
cd ryft-mcp
npm install
npm run buildOpen Claude Desktop
Go to Settings (gear icon in the top-right)
Click Developer in the sidebar
Click Edit Config to open claude_desktop_config.json
Add the following (replace the path and key with your own):
{
"mcpServers": {
"ryft": {
"command": "node",
"args": ["/absolute/path/to/ryft-mcp/dist/index.js"],
"env": {
"RYFT_SECRET_KEY": "YOUR_RYFT_SECRET_KEY"
}
}
}
}Save the file and restart Claude Desktop
Claude Code supports remote MCP servers with custom headers. Run this command in your terminal (all on one line):
claude mcp add ryft --transport http https://ryft-mcp.bkawk.com/mcp --header "Authorization: Bearer YOUR_RYFT_SECRET_KEY"Warning: Do not split this command across multiple lines. Line breaks inside the
--headervalue will be embedded in the token and cause silent authentication failures.
After running this command, start a new claude session (or type /mcp in an existing session) for the server to become available. You can verify it was saved correctly by running:
claude mcp listCheck that the Authorization header value shows Bearer sk_sandbox_... with no line breaks or extra whitespace.
To remove the server later:
claude mcp remove ryftChatGPT connectors currently only support OAuth or no-auth for remote MCP servers — custom Authorization headers are not supported. To use Ryft MCP with ChatGPT today:
Go to Settings → Apps & Connectors → Advanced settings and enable Developer mode
Go to Settings → Connectors → Create
Enter a name (e.g. "Ryft") and the server URL: https://ryft-mcp.bkawk.com/mcp
ChatGPT will attempt to connect without authentication
Note: Because ChatGPT cannot send a Bearer token, requests will be rejected with a 401 error. Full ChatGPT support requires adding OAuth to the MCP server — this is planned for a future release.
Open or create the file ~/.codex/config.toml
Add the Ryft MCP server:
[mcp_servers.ryft]
url = "https://ryft-mcp.bkawk.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_RYFT_SECRET_KEY" }Or to keep the key out of the config file, use an environment variable:
[mcp_servers.ryft]
url = "https://ryft-mcp.bkawk.com/mcp"
env_http_headers = { "Authorization" = "RYFT_AUTH_HEADER" }Then set export RYFT_AUTH_HEADER="Bearer YOUR_RYFT_SECRET_KEY" in your shell profile.
Save the file. Codex will pick up the server on the next run.
Open Cursor and go to Settings > MCP
Click Add new global MCP server
This opens ~/.cursor/mcp.json. Add the following:
{
"mcpServers": {
"ryft": {
"url": "https://ryft-mcp.bkawk.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_RYFT_SECRET_KEY"
}
}
}
}Save the file. The server should appear as connected in the MCP settings panel.
Any MCP client that supports remote Streamable HTTP servers can connect. Use these details:
URL: https://ryft-mcp.bkawk.com/mcp
Authentication: Bearer token
Token: Your Ryft secret key (e.g. sk_sandbox_...)
Once configured, ask your AI assistant something like "List my Ryft customers" or run the ryft.health tool. If the connection is working, you should see a response with your Ryft data or the list of available tool families.
Symptom | Cause | Fix |
401 Unauthorized | Missing or malformed | Ensure the header is |
403 Access Denied | Truncated secret key (often a missing | Re-copy the full key from the Ryft dashboard — it may contain special characters |
403 Access Denied | Newline embedded in the key | Re-run |
AI says "no Ryft tools" | MCP server not connected or stale tool list | Start a new |
"not valid MCP server" in Claude Desktop | Claude Desktop does not support remote MCP with custom headers via config file | Use the stdio setup for Claude Desktop (see above) or use Claude Code CLI instead |
Config saved but tools missing | Config was saved to a different project scope | Run |
Related MCP server: MCP Stripe Server
Available tool families:
customers — create, get, list, update, delete, list payment methods
paymentSessions — create, get, list, update, close, capture, refund
subscriptions — create, get, list, update, cancel
files — upload, get, list
accounts — create, get, list, update
accountLinks — create, get, list, delete
paymentMethods — create, get, list, update, delete
webhooks — create, get, list, update, delete
persons — create, get, list, update, delete
payoutMethods — create, get, list, update, delete
payouts — create, get, list, update
transfers — create, get, list
platformFees — create, get, list
events — get, list
disputes — get, list, update
balances — get, list
applePay — initiate, complete, decrypt
inPerson — in-person payment operations
If you prefer to run your own instance, there are three deployment options.
npm install
npm run build
RYFT_SECRET_KEY=your_secret_key npm startMCP client configuration for stdio:
{
"mcpServers": {
"ryft": {
"command": "node",
"args": ["/absolute/path/to/ryft-mcp/dist/index.js"],
"env": {
"RYFT_SECRET_KEY": "your_secret_key"
}
}
}
}RYFT_SECRET_KEY=your_secret_key PORT=8787 npm run dev:httpHealth check: curl http://127.0.0.1:8787/health
The infra/ directory contains a CDK stack that deploys:
Lambda function (Node.js 20, arm64)
API Gateway HTTP API with CORS
ACM certificate (DNS-validated)
Custom domain with Route 53 alias record
Prerequisites:
AWS CLI configured with appropriate permissions
An existing Route 53 hosted zone for your domain
Node.js 20+
Setup:
# Create your .env from the template
cp .env.example .env
# Edit .env with your values:
# AWS_PROFILE=your-profile
# CDK_DEFAULT_ACCOUNT=123456789012
# CDK_DEFAULT_REGION=us-east-1
# DOMAIN_NAME=mcp.yourdomain.com
# HOSTED_ZONE_NAME=yourdomain.com
# Build the Lambda bundle
npm install
npm run build:lambda:zip
# Deploy
cd infra
npm install
export $(grep -v '^#' ../.env | xargs)
npx cdk deployThe deployed server authenticates per-request — each caller passes their own Ryft secret key in the Authorization: Bearer header. No secrets are stored in the Lambda environment.
Variable | Required | Default | Description |
| stdio only | — | Ryft API secret key (stdio mode reads from env) |
| No |
| Ryft API base URL |
| No | — | Default |
stdio and remote Streamable HTTP transports
AWS Lambda handler for stateless MCP over HTTPS
per-request authentication via Authorization: Bearer header (hosted mode)
structured Ryft API error responses
account-scoped requests with optional default account
multipart file uploads
DELETE-with-body support for endpoints that require it
npm install # install dependencies
npm run check # typecheck
npm run lint # lint
npm test # run tests
npm run build # build all entry pointsIn hosted mode, the server does not store any API credentials. Each request must include a valid Ryft secret key in the Authorization header. Requests without a valid Bearer token receive a 401 response.
In stdio mode (local), the server reads RYFT_SECRET_KEY from the environment and exits immediately if it is missing.
MIT
Generate a temporary Ryft account link for a hosted sub-account.
Inputs: accountId (required), redirectUrl (required).
Create a Ryft account.
Inputs: entityType (required), onboardingFlow, email, business, +4 more.
Create a Ryft account authorization link for a registered account email.
Inputs: email (required), redirectUrl (required).
Get a Ryft account by id.
Inputs: id (required).
Update a Ryft account by id.
Inputs: id (required), entityType, business, individual, +3 more.
Request account verification for a Ryft account.
Inputs: id (required).
List Ryft balances for a currency.
Inputs: currency (required), accountId.
List Ryft balance transactions.
Inputs: limit, startsAfter, payoutId, accountId.
Create a Ryft customer.
Inputs: email (required), firstName, lastName, metadata.
Delete a Ryft customer.
Inputs: id (required).
Get a Ryft customer by id.
Inputs: id (required).
List Ryft customers.
Inputs: email, startTimestamp, endTimestamp, ascending, +2 more.
List stored payment methods for a Ryft customer.
Inputs: id (required).
Update a Ryft customer.
Inputs: id (required), firstName, lastName, metadata.
Accept a Ryft dispute.
Inputs: id (required).
Add evidence to a Ryft dispute.
Inputs: id (required), text, files.
Challenge a Ryft dispute.
Inputs: id (required).
Delete evidence from a Ryft dispute.
Inputs: id (required), text, files.
Get a Ryft dispute by id.
Inputs: id (required).
List Ryft disputes.
Inputs: startTimestamp, endTimestamp, ascending, limit, +1 more.
Get a Ryft event by id.
Inputs: id (required), accountId.
List Ryft events.
Inputs: ascending, limit, accountId.
Upload a file to Ryft.
Inputs: filePath (required), category (required), accountId.
Get a file by id.
Inputs: id (required), accountId.
List files.
Inputs: category, ascending, limit, startsAfter.
Delete a Ryft payment method.
Inputs: id (required).
Get a Ryft payment method by id.
Inputs: id (required).
Update a Ryft payment method billing address.
Inputs: id (required), billingAddress (required).
Capture a manually captured Ryft payment session.
Inputs: id (required), amount.
Continue a Ryft payment after a required action such as 3DS.
Inputs: clientSecret (required), threeDs.
Create a Ryft payment session.
Inputs: amount (required), currency (required), customerEmail, customerId, +4 more.
Get a Ryft payment session by id.
Inputs: id (required).
Get a payment session transaction by id.
Inputs: id (required), transactionId (required).
List Ryft payment sessions.
Inputs: startTimestamp, endTimestamp, ascending, limit, +2 more.
List transactions for a payment session.
Inputs: id (required).
Refund a Ryft payment session.
Inputs: id (required), amount, reason, refundPlatformFee.
Update a Ryft payment session.
Inputs: id (required), amount, captureFlow, customerEmail, +1 more.
Void a Ryft payment session.
Inputs: id (required).
Create a Ryft payout method for an account.
Inputs: accountId (required), type (required), currency (required), country (required), +2 more.
Delete a Ryft payout method.
Inputs: accountId (required), payoutMethodId (required).
Get a Ryft payout method by id.
Inputs: accountId (required), payoutMethodId (required).
List payout methods for a Ryft account.
Inputs: accountId (required), ascending, limit, startsAfter.
Update a Ryft payout method.
Inputs: accountId (required), payoutMethodId (required), bankAccount (required), displayName.
Create a Ryft payout for an account.
Inputs: accountId (required), amount (required), currency (required), payoutMethodId (required), +1 more.
Get a Ryft payout by id.
Inputs: accountId (required), payoutId (required).
List Ryft payouts for an account.
Inputs: accountId (required), startTimestamp, endTimestamp, ascending, +2 more.
Create a Ryft person for a business account.
Inputs: accountId (required), firstName (required), lastName (required), email (required), +10 more.
Delete a Ryft person.
Inputs: accountId (required), personId (required).
Get a Ryft person by id.
Inputs: accountId (required), personId (required).
List Ryft persons for an account.
Inputs: accountId (required), ascending, limit, startsAfter.
Update a Ryft person.
Inputs: accountId (required), personId (required), firstName, middleNames, +11 more.
Get a Ryft platform fee by id.
Inputs: id (required).
List refunds for a Ryft platform fee.
Inputs: id (required).
List Ryft platform fees.
Inputs: ascending, limit.
Show the Ryft MCP server configuration state without revealing secrets.
Inputs: no named parameters.
Cancel a Ryft subscription using the correct lifecycle endpoint.
Inputs: id (required).
Create a Ryft subscription.
Inputs: customerId (required), amount (required), currency (required), interval (required), +4 more.
Get a Ryft subscription by id.
Inputs: id (required).
List payment sessions for a Ryft subscription.
Inputs: id (required), startTimestamp, endTimestamp, ascending, +2 more.
List Ryft subscriptions.
Inputs: startTimestamp, endTimestamp, ascending, limit, +1 more.
Update a Ryft subscription.
Inputs: id (required), description, metadata.
Create a Ryft transfer.
Inputs: amount (required), currency (required), source, destination, +2 more.
Get a Ryft transfer by id.
Inputs: id (required).
List Ryft transfers.
Inputs: ascending, limit, startsAfter.
Create a Ryft webhook endpoint.
Inputs: url (required), active (required), eventTypes (required).
Delete a Ryft webhook endpoint.
Inputs: id (required).
Get a Ryft webhook by id.
Inputs: id (required).
List Ryft webhook endpoints.
Inputs: no named parameters.
Update a Ryft webhook endpoint.
Inputs: url (required), active (required), eventTypes (required), id (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 69 tools
Every tool has a clearly distinct purpose with no ambiguity. Tools are organized by resource type (accounts, customers, disputes, etc.) with specific CRUD operations, making it easy to distinguish between them. The naming convention clearly indicates both the resource and action, preventing misselection.
The naming follows a perfectly consistent pattern throughout: resource.action (e.g., accounts.create, customers.get, disputes.list). All tools use lowercase with dot notation separating resource and verb, creating a predictable and readable structure. There are no deviations in naming style.
With 69 tools, the count is excessive for most agent workflows and feels heavy for the payment processing domain. While the domain is comprehensive, this many tools creates cognitive load and may overwhelm agents. A more focused subset would be more appropriate for typical use cases.
The tool surface provides complete CRUD/lifecycle coverage across all major payment processing domains: accounts, customers, payments, disputes, subscriptions, transfers, and webhooks. Every resource type has create, get, update, and list operations where applicable, with no obvious gaps in functionality.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server for Modern Treasury — payment orders, transactions, counterparties and ledgers.
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
