Skip to main content
Glama
OrcaRail MCP

OrcaRail MCP

Official
by OrcaRail

@orcarail/mcp

Official Model Context Protocol (MCP) server for OrcaRail — accept crypto payments from your AI coding agent.

Runs locally over stdio and wraps the @orcarail/node SDK, so Claude Code, Cursor, Codex, and any other MCP client can create payment intents, manage subscriptions, maintain your product catalog, and look up exchange rates.

What you can ask your agent

  • "Create a $25 USDC payment intent on Polygon with return URL https://myapp.com/success and give me the pay link."

  • "List my active subscriptions and cancel the one for customer@example.com at period end."

  • "Create a product called Pro Plan with a $29/month recurring price."

  • "How much is 500 EUR in USDC right now?"

Related MCP server: Safefy MCP

Requirements

  • Node.js 18+

  • For private tools (payment intents, subscriptions, catalog): an OrcaRail API key (ak_…) and secret (sk_…) from the dashboard

  • Public tools (rates.*, pay.*) work with no credentials

Quick start

Public rates/pay tools need no credentials:

npx -y @orcarail/mcp --tools=all

For private tools, set environment variables (preferred — keeps secrets out of shell history):

export ORCARAIL_API_KEY=ak_live_xxx
export ORCARAIL_API_SECRET=sk_live_xxx
npx -y @orcarail/mcp --tools=all

The --api-key and --api-secret flags also work, but any other user on the same machine can read command-line flags in the process list (ps). Pass the secret through the environment.

The server speaks MCP over stdin/stdout; it is meant to be launched by an MCP client, not used interactively. npx -y @orcarail/mcp --help prints usage.

Configuration

Every option is a CLI flag or an environment variable. Flags win. Prefer env for secrets.

Flag

Environment variable

Required

Description

--api-key

ORCARAIL_API_KEY

For private tools

API key (ak_…)

--api-secret

ORCARAIL_API_SECRET

For private tools

API secret (sk_…). Use the environment variable: a flag is visible in the process list

--api-base

ORCARAIL_API_BASE

No

API base URL. Default https://api.orcarail.com/api/v1

--organization-id

ORCARAIL_ORGANIZATION_ID

No

Default organization for products.* / prices.* tools

--tools

—

No

all (default) or comma-separated tool names

Restrict what the agent can do:

npx -y @orcarail/mcp \
  --tools=payment_intents.create,payment_intents.retrieve,subscriptions.list

Local API (development):

npx -y @orcarail/mcp --tools=all --api-base=http://127.0.0.1:3000/api/v1

Client setup

Claude Code

Pass the credentials as environment variables:

claude mcp add orcarail \
  -e ORCARAIL_API_KEY=ak_live_xxx \
  -e ORCARAIL_API_SECRET=sk_live_xxx \
  -- npx -y @orcarail/mcp --tools=all

Verify with claude mcp list.

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "orcarail": {
      "command": "npx",
      "args": ["-y", "@orcarail/mcp", "--tools=all"],
      "env": {
        "ORCARAIL_API_KEY": "ak_live_xxx",
        "ORCARAIL_API_SECRET": "sk_live_xxx"
      }
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.orcarail]
command = "npx"
args = ["-y", "@orcarail/mcp", "--tools=all"]

[mcp_servers.orcarail.env]
ORCARAIL_API_KEY = "ak_live_xxx"
ORCARAIL_API_SECRET = "sk_live_xxx"

Other MCP clients

Any stdio-capable MCP client works with the same shape: command npx, args ["-y", "@orcarail/mcp", "--tools=all"], credentials in env. For Claude Desktop, use the Cursor JSON block in claude_desktop_config.json.

Live vs sandbox

The server detects the mode from your API key and tells the agent about it through its MCP instructions and the account.get_mode tool.

Key

Mode

What it means

ak_test_…

Sandbox

A sandbox organization: testnets only, no real funds. payment_intents.simulate is available.

ak_live_…

Live

Real funds on mainnet networks. The agent is asked to confirm with you before any write.

none

Public

Only the public tools (rates.*, pay.*, account.get_mode).

Use a sandbox key while you build with an agent. You can create one from the Go to sandbox button in the OrcaRail dashboard (see Sandbox). Switch to a live key only when you are ready.

Tool reference

Tool names follow resource.action. Responses are raw OrcaRail API objects as JSON.

Payment intents

Tool

Arguments

Description

payment_intents.create

return_url (required); either price_id or amount + currency + tokenId + networkId; optional cancel_url, description, metadata, expires_at, payment_method_types, withdrawal_addresses

Create a payment intent (returns client_secret and payment link)

payment_intents.retrieve

id

Fetch current status

payment_intents.update

id + any updatable field

Update before confirmation

payment_intents.confirm

id, client_secret, return_url

Confirm and get the hosted pay redirect URL

payment_intents.complete

id

Required after the customer returns to your success URL: completes the intent once the payment is confirmed (until then it is not final or withdrawable); call again while it is still processing

payment_intents.cancel

id

Cancel the intent

payment_intents.simulate

id

Sandbox keys only. Complete the payment without a wallet, firing the usual webhooks

tokenId / networkId are UUIDs — see Networks and Tokens.

Subscriptions

Tool

Arguments

Description

subscriptions.create

description (required); either price_id or interval + amount + currency + token_id + network_id; optional collection_method, total_cycles, trial_period_days, trial_end, payer_email, payer_user_id, billing_cycle_anchor, cancel_at, cancel_at_period_end, days_until_due, interval_count, metadata, withdrawal_addresses, return_url, cancel_url

Create a recurring subscription

subscriptions.retrieve

id

Fetch a subscription

subscriptions.update

id + any updatable field, including pause_collection

Update

subscriptions.cancel

id, optional cancellation_details (comment, feedback)

Cancel

subscriptions.resume

id

Resume a paused subscription

subscriptions.list

Optional status, collection_method, created / current_period_start / current_period_end range filters, limit, starting_after, ending_before

List with cursor pagination

subscriptions.list_payment_links

id, optional limit, starting_after, ending_before

Cycle invoices for a subscription

Catalog — products and prices

Catalog tools operate on an organization: pass organization_id per call or set a default via --organization-id / ORCARAIL_ORGANIZATION_ID.

Tool

Arguments

Description

products.list

optional organization_id

List products

products.create

name (required); optional description, active, metadata, default_price, marketing_features, …

Create a product

products.update

product_id + updatable fields

Update a product

products.delete

product_id

Delete a product

prices.list

optional active, recurring, limit

List prices

prices.create

unit_amount_decimal, currency, token_id, network_id (required); product or inline product_data; optional recurring (interval, interval_count, trial_period_days), nickname, lookup_key, active, metadata

Create a one-time or recurring price

prices.update

price_id + updatable fields

Update a price

prices.deactivate

price_id

Deactivate a price

Rates and pay (public — no credentials required)

Tool

Arguments

Description

rates.get_fiat_quote

amount, currency

Fiat → USD/USDC quote

rates.list_currencies

optional active

Supported fiat currencies

pay.get_by_slug

slug

Payment details by hosted pay slug

pay.cancel_by_slug

slug

Cancel by pay slug

account.get_mode

—

Live, sandbox or public mode of this server (see Live vs sandbox)

Error handling

API failures surface to the agent as tool errors with the HTTP status, error type, and message intact, e.g. API error (401): [authentication_error]: …. Nothing is retried automatically.

Calling a private tool without credentials returns a clear tool error telling you to set ORCARAIL_API_KEY and ORCARAIL_API_SECRET (or the matching flags).

Programmatic usage

The package also exports its building blocks if you want to embed the server:

import { createServer, startStdioServer, listToolNames } from '@orcarail/mcp';

const { server, tools } = createServer({
  // Optional — omit for public rates/pay only
  apiKey: process.env.ORCARAIL_API_KEY,
  apiSecret: process.env.ORCARAIL_API_SECRET,
  tools: 'all', // or new Set(['payment_intents.create'])
});

console.log(listToolNames()); // all 25 tool names
await startStdioServer(server);

Security

  • API keys grant full access to the linked organization — treat MCP config files like .env files.

  • Prefer environment variables over inline --api-key=… args.

  • Never commit live keys; keep project-level .cursor/mcp.json with secrets out of git.

  • Scope with --tools to only the operations your agent needs.

  • Use test keys during development; rotate leaked keys in the dashboard.

Troubleshooting

Symptom

Fix

Missing credentials for this tool

Set ORCARAIL_API_KEY/ORCARAIL_API_SECRET (or --api-key/--api-secret) for private tools

Authentication error on every call

Verify the key/secret pair; don't mix test and live credentials

organization_id is required

Pass organization_id in the call or launch with --organization-id

Tool missing from the client

Check the --tools filter — names must match exactly

Client can't start the server

Ensure Node.js 18+ on the client's PATH; try npx -y @orcarail/mcp --help

Development

npm install
npm run build       # tsup → dist/
npm test            # vitest
npm run typecheck   # tsc --noEmit
npm run lint        # eslint

Test against a local MCP inspector:

ORCARAIL_API_KEY=ak_test_xxx ORCARAIL_API_SECRET=sk_test_xxx npx @modelcontextprotocol/inspector node dist/cli.cjs --tools=all

License

MIT

Available Tools

26 tools
account.get_modeA
Read-only

Returns whether this server is connected to a LIVE organization (real funds, ak_live_ key), a SANDBOX organization (testnets only, no real funds, ak_test_ key) or no key (public tools only). Check this before creating, confirming, completing or cancelling anything.

Inputs: no named parameters.

pay.cancel_by_slugA
Destructive

Cancel the payment intent behind a hosted pay page, identified by the slug in its payment link URL. Works without API credentials: anyone holding the slug can call it. To cancel by Payment Intent ID with credentials, use payment_intents.cancel.

Inputs: slug (required).

pay.get_by_slugB
Read-only

Get pay / payment intent details by hosted pay slug

Inputs: slug (required).

payment_intents.cancelA
Destructive

Cancel a Payment Intent by ID. Returns the cancelled intent. Check its status with payment_intents.retrieve first when the customer may already have paid. To cancel from a hosted pay slug without credentials, use pay.cancel_by_slug.

Inputs: id (required).

payment_intents.completeA
Destructive

Required after the customer returns to your success URL: completes the Payment Intent once its payment is confirmed (until then the payment is not final or withdrawable); call again while it is still processing

Inputs: id (required).

payment_intents.confirmB
Destructive

Confirm a Payment Intent and get the hosted pay redirect URL

Inputs: id (required), return_url (required), client_secret (required).

payment_intents.createA

Create a Payment Intent. Provide either price_id (a catalog price) or all of amount + currency + tokenId + networkId. tokenId and networkId are UUIDs from the OrcaRail Networks and Tokens reference; no tool in this server lists them, so prefer price_id when the user has a catalog price. Returns the intent, including client_secret (needed by payment_intents.confirm) and the hosted payment link.

Inputs: return_url (required), amount, tokenId, currency, +8 more.

payment_intents.retrieveA
Read-only

Retrieve a Payment Intent by ID

Inputs: id (required).

payment_intents.updateC
Destructive

Update a Payment Intent before confirmation

Inputs: id (required), amount, tokenId, currency, +9 more.

prices.createC

Create a catalog price (one-time or recurring)

Inputs: currency (required), token_id (required), network_id (required), unit_amount_decimal (required), +9 more.

prices.deactivateA
Destructive

Deactivate a catalog price (it is marked inactive, not deleted). Reverse with prices.update active: true.

Inputs: price_id (required), organization_id.

prices.listC
Read-only

List catalog prices for an organization

Inputs: limit, active, recurring, organization_id.

prices.updateC
Destructive

Update a catalog price

Inputs: price_id (required), active, product, currency, +9 more.

products.createC

Create a catalog product

Inputs: name (required), url, active, metadata, +8 more.

products.deleteA
Destructive

Permanently delete a catalog product from an organization. Fails while any of its prices is in use by subscriptions or payment links. To stop selling a product without deleting it, use products.update with active: false instead.

Inputs: product_id (required), organization_id.

products.listC
Read-only

List catalog products for an organization

Inputs: organization_id.

products.updateC
Destructive

Update a catalog product

Inputs: product_id (required), url, name, active, +9 more.

rates.get_fiat_quoteB
Read-only

Get a fiat-to-USDC quote for an amount in a source currency

Inputs: amount (required), currency (required).

rates.list_currenciesB
Read-only

List supported fiat currencies

Inputs: active.

subscriptions.cancelA
Destructive

Cancel a subscription. Cancels immediately, unless cancel_at_period_end was already set on it, in which case it ends at the current period end. To schedule a period-end cancellation, call subscriptions.update with cancel_at_period_end: true (or cancel_at for a specific date) instead of this tool. Optional cancellation_details records the reason (comment; feedback one of too_expensive, missing_features, switched_service, unused, other). Returns the subscription object.

Inputs: id (required), cancellation_details.

subscriptions.createA

Create a recurring subscription. Provide either price_id (a recurring catalog price) or all of amount + currency + token_id + network_id + interval. token_id and network_id are UUIDs from the OrcaRail Networks and Tokens reference; no tool in this server lists them. collection_method send_payment_link creates a payment link each cycle (optionally emailed); auto_charge charges automatically. Returns the subscription object.

Inputs: description (required), amount, currency, interval, +18 more.

subscriptions.listC
Read-only

List subscriptions with optional filters and cursor pagination

Inputs: limit, status, created, ending_before, +4 more.

subscriptions.resumeC
Destructive

Resume a paused subscription

Inputs: id (required).

subscriptions.retrieveC
Read-only

Retrieve a subscription by ID

Inputs: id (required).

subscriptions.updateC
Destructive

Update a subscription

Inputs: id (required), amount, currency, metadata, +13 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 26 tools

    Disambiguation4/5

    Most tools target a distinct resource+action pair, and the descriptions explicitly cross-reference near-duplicates (payment_intents.cancel vs pay.cancel_by_slug, subscriptions.cancel vs subscriptions.update with cancel_at_period_end). The pay.* namespace still overlaps conceptually with payment_intents.* (both operate on payment intents, just by slug vs ID), which could cause occasional misselection.

    Naming Consistency5/5

    Every tool follows a strict resource.action dot-namespaced pattern in snake_case (payment_intents.create, subscriptions.list_payment_links, products.delete). Namespaces map cleanly to domain objects, making the surface highly predictable.

    Tool Count3/5

    26 tools is on the heavy side for a payments API, though the surface spans several real sub-domains (products, prices, subscriptions, payment intents, rates, account). Each tool is individually justified, but the count sits just above the comfortable range.

    Completeness3/5

    CRUD/lifecycle coverage is strong for products, prices, subscriptions, and payment intents, including confirm/complete/cancel flows. However, there is no tool to list networks or tokens even though payment_intents.create and subscriptions.create require tokenId/networkId UUIDs, and there are no retrieve-by-ID tools for products or prices — real dead ends for agents.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that enables AI agents to accept Bitcoin Lightning payments. It allows agents to create orders, generate invoices, check payment status, and manage the full SatsRail merchant API through natural language.
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Official MCP server for Safefy, enabling AI agents to manage PIX payments, withdrawals, customers, and transactions via the Safefy payment API.
      29
      8 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Official MCP server for ZuckPay – create PIX, SPEI, and PayPal charges, and query transactions from your AI assistant.
      20
      23 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Official MCP server for NanoCart, enabling AI agents to manage products, orders, coupons, categories, subscribers, settings, and pull sales reports from your store.
      31
      47 npm
      MIT