# Ryft MCP

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

```bash
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):

```json
{
  "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):

```bash
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:

```bash
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:

```bash
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:

```toml
[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:

```toml
[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:

```json
{
  "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)

```bash
npm install
npm run build
RYFT_SECRET_KEY=your_secret_key npm start
```

MCP client configuration for stdio:

```json
{
  "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

```bash
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:**

```bash
# 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

```bash
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