Ryft MCP

ryft-mcp is a Model Context Protocol server for the Ryft API.

It gives MCP clients a clean stdio server for working with Ryft resources such as customers, payment sessions, subscriptions, webhooks, accounts, payouts, disputes, files, and more.

Features

• stdio MCP server built with the official MCP SDK
• remote Streamable HTTP entrypoint for hosted deployments
• AWS Lambda handler for stateless MCP over HTTPS
• Ryft API authentication via environment variables
• structured Ryft API error responses
• account-scoped requests with optional default account support
• multipart file uploads
• DELETE-with-body support for endpoints that require it
• TypeScript, ESLint, unit tests, and build output ready for review or publishing

Tool Coverage

Current tool families include:

• customers
• paymentSessions
• subscriptions
• files
• accounts
• accountLinks
• paymentMethods
• webhooks
• persons
• payoutMethods
• payouts
• transfers
• platformFees
• events
• disputes
• balances

Requirements

• Node.js 20+
• a Ryft secret key

Installation

npm install

Build the server:

npm run build

Quick Start

Run the server locally over stdio:

RYFT_SECRET_KEY=your_secret_key npm run dev

Run the built server:

RYFT_SECRET_KEY=your_secret_key npm start

Run the hosted HTTP server locally:

RYFT_SECRET_KEY=your_secret_key PORT=8787 npm run dev:http

Optional environment variables:

• RYFT_BASE_URL
  • defaults to the Ryft sandbox API base URL
• RYFT_ACCOUNT_ID
  • default Account header for account-scoped operations

Health check:

RYFT_SECRET_KEY=your_secret_key node dist/index.js

HTTP health check:

curl http://127.0.0.1:8787/health

Example MCP Client Configuration

Example stdio configuration:

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

Example remote MCP configuration:

{
  "mcpServers": {
    "ryft": {
      "url": "https://ryft-mcp.bkawk.com/mcp"
    }
  }
}

Hosted Deployment

For hosted deployments, ryft-mcp now includes:

• dist/http.js
  • local Node HTTP server for remote MCP testing
• dist/lambda.js
  • AWS Lambda entrypoint
• dist/lambda.js export
  • handler name is handler

The remote transport is configured as:

• stateless Streamable HTTP
• JSON responses enabled
• no server-side MCP session persistence required

Build a Lambda zip artifact:

npm run build:lambda:zip

That produces:

.artifacts/ryft-mcp-lambda.zip

The zip includes:

• dist/*
• package.json

Recommended Lambda settings:

• Runtime: nodejs22.x
• Handler: dist/lambda.handler
• Architecture: arm64
• Environment variables:
  • RYFT_SECRET_KEY
  • optional RYFT_BASE_URL
  • optional RYFT_ACCOUNT_ID

High-level AWS CLI flow:

aws lambda create-function \
  --function-name ryft-mcp \
  --runtime nodejs22.x \
  --architectures arm64 \
  --handler dist/lambda.handler \
  --role arn:aws:iam::<account-id>:role/<lambda-exec-role> \
  --zip-file fileb://.artifacts/ryft-mcp-lambda.zip

Then place it behind either:

• API Gateway HTTP API with a POST /mcp route and optional GET /health
• Lambda Function URL if you want the smallest setup

For ChatGPT-compatible remote MCP, expose the HTTPS endpoint at /mcp.

Development

Install dependencies:

npm install

Run typecheck:

npm run check

Run lint:

npm run lint

Run tests:

npm test

Build:

npm run build

Security

ryft-mcp requires API credentials to be supplied by the caller through environment variables. The server will exit immediately if RYFT_SECRET_KEY is missing.

License

MIT