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