OrcaRail MCP
OfficialOrcaRail MCP is an MCP stdio server that lets an AI coding agent manage OrcaRail crypto payments, subscriptions, catalog products/prices, exchange rates, and hosted pay links, with public tools available without credentials and private write/read tools requiring API credentials.
Detect whether the server is in live, sandbox, or public mode.
Create, retrieve, update, confirm, complete, cancel, and sandbox-simulate payment intents, including hosted payment links.
Create, retrieve, update, cancel, resume, list, and list payment links for subscriptions.
List, create, update, and delete catalog products.
List, create, update, and deactivate catalog prices, including recurring prices.
Get fiat-to-USDC quotes and list supported fiat currencies without credentials.
Look up or cancel hosted pay pages by slug without credentials.
Restrict available tools with the
--toolsoption and configure API key/secret, API base URL, and default organization ID.
Enables creating and managing crypto payment intents on the Polygon network via OrcaRail, supporting USDC payments and subscription billing.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OrcaRail MCP Create a $25 USDC payment intent on Polygon and give me the pay link."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@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.
Dashboard: app.orcarail.com
npm:
@orcarail/mcp
What you can ask your agent
"Create a $25 USDC payment intent on Polygon with return URL
https://myapp.com/successand give me the pay link.""List my active subscriptions and cancel the one for
customer@example.comat 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 dashboardPublic tools (
rates.*,pay.*) work with no credentials
Quick start
Public rates/pay tools need no credentials:
npx -y @orcarail/mcp --tools=allFor 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=allThe --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 |
|
| For private tools | API key ( |
|
| For private tools | API secret ( |
|
| No | API base URL. Default |
|
| No | Default organization for |
| — | No |
|
Restrict what the agent can do:
npx -y @orcarail/mcp \
--tools=payment_intents.create,payment_intents.retrieve,subscriptions.listLocal API (development):
npx -y @orcarail/mcp --tools=all --api-base=http://127.0.0.1:3000/api/v1Client 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=allVerify 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 |
| Sandbox | A sandbox organization: testnets only, no real funds. |
| Live | Real funds on mainnet networks. The agent is asked to confirm with you before any write. |
none | Public | Only the public tools ( |
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 |
|
| Create a payment intent (returns |
|
| Fetch current status |
|
| Update before confirmation |
|
| Confirm and get the hosted pay redirect URL |
|
| 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 |
|
| Cancel the intent |
|
| 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 |
|
| Create a recurring subscription |
|
| Fetch a subscription |
|
| Update |
|
| Cancel |
|
| Resume a paused subscription |
| Optional | List with cursor pagination |
|
| 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 |
| optional | List products |
|
| Create a product |
|
| Update a product |
|
| Delete a product |
| optional | List prices |
|
| Create a one-time or recurring price |
|
| Update a price |
|
| Deactivate a price |
Rates and pay (public — no credentials required)
Tool | Arguments | Description |
|
| Fiat → USD/USDC quote |
| optional | Supported fiat currencies |
|
| Payment details by hosted pay slug |
|
| Cancel by pay slug |
| — | 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
.envfiles.Prefer environment variables over inline
--api-key=…args.Never commit live keys; keep project-level
.cursor/mcp.jsonwith secrets out of git.Scope with
--toolsto only the operations your agent needs.Use test keys during development; rotate leaked keys in the dashboard.
Troubleshooting
Symptom | Fix |
| Set |
| Verify the key/secret pair; don't mix test and live credentials |
| Pass |
Tool missing from the client | Check the |
Client can't start the server | Ensure Node.js 18+ on the client's PATH; try |
Development
npm install
npm run build # tsup → dist/
npm test # vitest
npm run typecheck # tsc --noEmit
npm run lint # eslintTest 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=allRelated
License
MIT
Available Tools
26 toolsaccount.get_modeARead-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_slugADestructive
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_slugBRead-only
Get pay / payment intent details by hosted pay slug
Inputs: slug (required).
payment_intents.cancelADestructive
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.completeADestructive
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.confirmBDestructive
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.retrieveARead-only
Retrieve a Payment Intent by ID
Inputs: id (required).
payment_intents.updateCDestructive
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.deactivateADestructive
Deactivate a catalog price (it is marked inactive, not deleted). Reverse with prices.update active: true.
Inputs: price_id (required), organization_id.
prices.listCRead-only
List catalog prices for an organization
Inputs: limit, active, recurring, organization_id.
prices.updateCDestructive
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.deleteADestructive
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.listCRead-only
List catalog products for an organization
Inputs: organization_id.
products.updateCDestructive
Update a catalog product
Inputs: product_id (required), url, name, active, +9 more.
rates.get_fiat_quoteBRead-only
Get a fiat-to-USDC quote for an amount in a source currency
Inputs: amount (required), currency (required).
rates.list_currenciesBRead-only
List supported fiat currencies
Inputs: active.
subscriptions.cancelADestructive
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.listCRead-only
List subscriptions with optional filters and cursor pagination
Inputs: limit, status, created, ending_before, +4 more.
subscriptions.list_payment_linksCRead-only
List payment links (cycle invoices) for a subscription
Inputs: id (required), limit, ending_before, starting_after.
subscriptions.resumeCDestructive
Resume a paused subscription
Inputs: id (required).
subscriptions.retrieveCRead-only
Retrieve a subscription by ID
Inputs: id (required).
subscriptions.updateCDestructive
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
Scored across 26 tools
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.
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.
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.
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
Related MCP Connectors
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Official BlindPay MCP server: stablecoin payouts, payins, quotes and customers for global payments.
Official MCP server for subfeed.app — the cloud for agents. 15+ tools for AI agents to register, build, and deploy other agents. Zero human required. Start here: subfeed.app/skill.md
Official MCP server for Certifier to issue, manage, and track certificates and badges.
Related MCP Servers
AlicenseNot gradedqualityCmaintenanceAn 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
Safefy MCPofficial
AlicenseBqualityBmaintenanceOfficial MCP server for Safefy, enabling AI agents to manage PIX payments, withdrawals, customers, and transactions via the Safefy payment API.298 npmMIT
zuckpay-mcpofficial
AlicenseAqualityCmaintenanceOfficial MCP server for ZuckPay – create PIX, SPEI, and PayPal charges, and query transactions from your AI assistant.2023 npmMIT- AlicenseAqualityDmaintenanceOfficial MCP server for NanoCart, enabling AI agents to manage products, orders, coupons, categories, subscribers, settings, and pull sales reports from your store.3147 npmMIT