MCP server

OrcaRail ships an official Model Context Protocol (MCP) server as @orcarail/mcp. It runs locally over stdio and wraps the @orcarail/node SDK, so AI coding agents such as Claude Code, Cursor, and Codex can create payment intents, manage subscriptions, maintain your product catalog, and look up exchange rates on your behalf — the same delivery model as Stripe's @stripe/mcp.

Source code: github.com/OrcaRail/mcp

What you can do with it

Once connected, you can ask your agent things like:

"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 [email protected] at period end."
"Create a product called Pro Plan with a $29/month recurring price."
"How much is 500 EUR in USDC right now?"
"What's the status of payment intent 550e8400-…?"

The agent calls the corresponding MCP tools; every call is authenticated with your API key and secret against the OrcaRail REST API.

Requirements

Node.js 18 or later
An OrcaRail API key and secret (ak_… / sk_…) from the dashboard

Quick start

npx -y @orcarail/mcp --tools=all --api-key=ak_live_xxx --api-secret=sk_live_xxx

The server speaks MCP over stdin/stdout — it is meant to be launched by an MCP client (see the client sections below), not used interactively.

Configuration

Every option is available as a CLI flag or an environment variable. Flags take precedence.

Flag	Environment variable	Required	Description
`--api-key`	`ORCARAIL_API_KEY`	Yes	API key (`ak_…`)
`--api-secret`	`ORCARAIL_API_SECRET`	Yes	API secret (`sk_…`)
`--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 catalog tools (`products.`, `prices.`)
`--tools`	—	No	`all` (default) or a comma-separated list of tool names

Restricting tools

By default all tools are exposed. Use --tools to limit what the agent can do — for example, read-and-create only, no cancellations or deletions:

npx -y @orcarail/mcp \
  --tools=payment_intents.create,payment_intents.retrieve,subscriptions.list,rates.get_fiat_quote \
  --api-key=ak_live_xxx --api-secret=sk_live_xxx

Unknown names are silently ignored; the server registers only the tools that match.

Self-hosted or local API

Point --api-base at your own deployment:

npx -y @orcarail/mcp --tools=all \
  --api-base=http://127.0.0.1:3000/api/v1 \
  --api-key=ak_test_xxx --api-secret=sk_test_xxx

Client setup

Claude Code

claude mcp add orcarail -- npx -y @orcarail/mcp --tools=all --api-key=ak_live_xxx --api-secret=sk_live_xxx

Or keep secrets out of the command line with 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, then ask Claude Code to, for example, "list my OrcaRail subscriptions".

Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects):

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

Cursor picks the server up automatically; check Settings → MCP to confirm it is running.

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 client that supports stdio MCP servers works with the same shape: command npx, args ["-y", "@orcarail/mcp", "--tools=all"], and the two ORCARAIL_* credential variables in the environment. For Claude Desktop, add the same JSON block as Cursor's to claude_desktop_config.json.

Tool reference

Tool names follow resource.action. All responses are the raw OrcaRail API objects serialized 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 the intent including `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`	Mark processing after the customer returns to your success URL
`payment_intents.cancel`	`id`	Cancel the intent

tokenId and networkId are UUIDs — see Networks and Tokens for live values.

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 a subscription
`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 (payment links) for a subscription

Catalog — products

Catalog tools operate on an organization. Pass organization_id per call, or set a default once with --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`, and more	Create a product
`products.update`	`product_id` + any updatable field	Update a product
`products.delete`	`product_id`	Delete a product

Catalog — prices

Tool	Arguments	Description
`prices.list`	optional `organization_id`, `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` + any updatable field	Update a price
`prices.deactivate`	`price_id`	Deactivate a price

Rates

Tool	Arguments	Description
`rates.get_fiat_quote`	`amount`, `currency`	Convert a fiat amount to USD/USDC
`rates.list_currencies`	optional `active`	List supported fiat currencies

Pay (hosted pay pages)

Tool	Arguments	Description
`pay.get_by_slug`	`slug`	Get payment details by hosted pay slug
`pay.cancel_by_slug`	`slug`	Cancel a payment intent by its pay slug

Example workflows

Create a payment and get the pay link

Prompt your agent:

Create a 50 USD payment intent on OrcaRail using USDC on Polygon, return URL https://myshop.com/thanks, then confirm it and give me the customer-facing pay URL.

The agent will call payment_intents.create, then payment_intents.confirm with the returned client_secret, and report the hosted pay URL.

Set up a subscription product

Create an OrcaRail product "Pro Plan" with a $29/month USDC recurring price, then create a subscription for [email protected] using that price.

The agent chains products.create → prices.create (with recurring.interval: "month") → subscriptions.create (with the new price_id and payer_email).

Investigate a payment

Look up payment intent 550e8400-e29b-41d4-a716-446655440000 and tell me its status, amount, and the last transaction.

Error handling

API failures are returned to the agent as tool errors with the HTTP status, error type, and message from the API intact (for example, API error (401): [authentication_error]: …). Agents typically read these and correct their next call; nothing is retried automatically.

Security

Keys grant full access to the organization linked to the API key. Treat MCP config files with the same care as .env files.
Prefer environment variables over inline --api-key=… args so secrets don't end up in shell history or committed config.
Never commit live keys. If you use a project-level .cursor/mcp.json, keep the key out of git (use env references or a local-only file).
Scope with --tools. Expose only the operations your agent needs — for example, exclude products.delete and subscriptions.cancel for read-mostly workflows.
Use test keys during development, and rotate any key that may have leaked from the dashboard.

Troubleshooting

Symptom	Fix
`Missing credentials` on startup	Pass `--api-key`/`--api-secret` or set `ORCARAIL_API_KEY`/`ORCARAIL_API_SECRET`
`Authentication error` on every call	Verify the key/secret pair in the dashboard; check you're not mixing test and live credentials
`organization_id is required`	Pass `organization_id` in the tool call or launch with `--organization-id`
Tool missing from the client	Check your `--tools` filter — names must match exactly (e.g. `payment_intents.create`)
Client can't start the server	Ensure Node.js 18+ is on the PATH the client uses; try `npx -y @orcarail/mcp --help` in a terminal

What you can do with it​

Requirements​

Quick start​

Configuration​

Restricting tools​

Self-hosted or local API​

Client setup​

Claude Code​

Cursor​

Codex​

Other MCP clients​

Tool reference​

Payment intents​

Subscriptions​

Catalog — products​

Catalog — prices​

Rates​

Pay (hosted pay pages)​

Example workflows​

Create a payment and get the pay link​

Set up a subscription product​

Investigate a payment​

Error handling​

Security​

Troubleshooting​

Related​