Ryft

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.

Quick Start (Hosted)

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

Claude Desktop does not support custom authentication headers for remote MCP servers via config file. Use the stdio transport instead:

1. Clone this repository and install dependencies:

git clone https://github.com/bkawk/ryft-mcp.git
cd ryft-mcp
npm install
npm run build

2. Open Claude Desktop
3. Go to Settings (gear icon in the top-right)
4. Click Developer in the sidebar
5. Click Edit Config to open claude_desktop_config.json
6. 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"
      }
    }
  }
}

7. Save the file and restart Claude Desktop

Claude Code (CLI)

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 --header value 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 list

Check that the Authorization header value shows Bearer sk_sandbox_... with no line breaks or extra whitespace.

To remove the server later:

claude mcp remove ryft

ChatGPT

ChatGPT 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:

1. Go to Settings → Apps & Connectors → Advanced settings and enable Developer mode
2. Go to Settings → Connectors → Create
3. Enter a name (e.g. "Ryft") and the server URL: https://ryft-mcp.bkawk.com/mcp
4. 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.

Codex (OpenAI CLI)

1. Open or create the file ~/.codex/config.toml
2. 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.

3. Save the file. Codex will pick up the server on the next run.

Cursor

1. Open Cursor and go to Settings > MCP
2. Click Add new global MCP server
3. This opens ~/.cursor/mcp.json. Add the following:

{
  "mcpServers": {
    "ryft": {
      "url": "https://ryft-mcp.bkawk.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_RYFT_SECRET_KEY"
      }
    }
  }
}

4. Save the file. The server should appear as connected in the MCP settings panel.

Other MCP Clients

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_...)

Verify the Connection

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.

Troubleshooting

Symptom	Cause	Fix
401 Unauthorized	Missing or malformed Authorization header	Ensure the header is Bearer <key> with a space after Bearer
403 Access Denied	Truncated secret key (often a missing / or +)	Re-copy the full key from the Ryft dashboard — it may contain special characters
403 Access Denied	Newline embedded in the key	Re-run claude mcp add with the entire command on a single line — do not use \ line continuation
AI says "no Ryft tools"	MCP server not connected or stale tool list	Start a new claude session, or type /mcp to refresh the connection
"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 claude mcp list to confirm the server is registered. If it was added from a different directory, it may be project-scoped to that path

Tool Coverage

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

Self-Hosting

If you prefer to run your own instance, there are three deployment options.

Option 1: Local stdio (for development)

npm install
npm run build
RYFT_SECRET_KEY=your_secret_key npm start

MCP client configuration for stdio:

{
  "mcpServers": {
    "ryft": {
      "command": "node",
      "args": ["/absolute/path/to/ryft-mcp/dist/index.js"],
      "env": {
        "RYFT_SECRET_KEY": "your_secret_key"
      }
    }
  }
}

Option 2: Local HTTP server

RYFT_SECRET_KEY=your_secret_key PORT=8787 npm run dev:http

Health check: curl http://127.0.0.1:8787/health

Option 3: AWS Lambda via CDK

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 deploy

The 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.

Environment Variables

Variable	Required	Default	Description
RYFT_SECRET_KEY	stdio only	—	Ryft API secret key (stdio mode reads from env)
RYFT_BASE_URL	No	https://sandbox-api.ryftpay.com/v1	Ryft API base URL
RYFT_ACCOUNT_ID	No	—	Default Account header for scoped operations

Features

• 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

Development

npm install        # install dependencies
npm run check      # typecheck
npm run lint       # lint
npm test           # run tests
npm run build      # build all entry points

Security

In 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.

License

MIT