Rail

Rail MCP

Rail は、人間に代わってエージェントが何かを購入する際に呼び出す、予算管理、承認、領収書のためのレイヤーです。デフォルトではドライランで動作し、カードを発行するのではなく、決済に Stripe Link を使用します。

マーケットプレイス、ストアフロント、アウトリーチツールではありません。Rail は予算、承認ゲート、領収書台帳を管理します。

クイックスタート

Node.js 20 以降が必要です。公開パッケージを npx -y rail-mcp で実行します。デフォルトモードはドライランで、ネットワークへの接続や請求は発生しません。

Claude Desktop および mcpServers ブロックを受け付けるその他のホスト：

{
  "mcpServers": {
    "rail": {
      "command": "npx",
      "args": ["-y", "rail-mcp"]
    }
  }
}

Cursor： ワンクリックでインストールできます（インストールリンク）。config の値は {"command":"npx","args":["-y","rail-mcp"]} の base64 です。

Rail を Cursor にインストール

cursor://anysphere.cursor-deeplink/mcp/install?name=rail&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInJhaWwtbWNwIl19

Grok Bot： npx -y rail-mcp でカスタム MCP を追加します。

この共有スニペットに Stripe や Link のシークレット（STRIPE_SECRET_KEY、LINK_ACCESS_TOKEN、または実際の支出を有効にするフラグ）を含めないでください。これらのゲートを共有設定の外で意図的に設定しない限り、実際の請求は発生しません。Stripe Link の接続箇所を参照してください。

台帳ファイル（budget.json、proposals.json、receipts.json）は、ユーザーのホームディレクトリにある ~/.rail、または RAIL_DATA_DIR が設定されている場合はそのディレクトリに書き込まれます。これらはローカル状態であり、npm パッケージには含まれません。デフォルトではプロセスの作業ディレクトリを基準にしないため、ホストがサーバーを / から起動しても、ホームディレクトリ配下に書き込まれます。

使用例

予算を設定し、購入を提案して、人間に承認してもらった後、領収書を読み取ります。ドライランでは、マシンの外に資金が移動することはありません。

1. set_budget → { "amount_usd": 50, "note": "week1" }
2. propose_purchase → { "merchant": "Acme", "amount_usd": 12, "rationale": "need widgets" }
3. get_budget には、残額 50.00 と open_proposals: 1 が引き続き表示されます。人間が決定するまで、提案は保留状態です。
4. decide_proposal → { "proposal_id": "prop_…", "decision": "approve" }
5. get_receipts は、settlement_ref を含む settled_dry_run の領収書を1件返します。残りの予算は 38.00 です。

却下しても支出は発生しません。refund_receipt はドライランの決済を取り消し、予算を復元します。

ツール

ツール	目的
set_budget	ローカルの予算上限を上書きします。資金は移動しません
get_budget	予算、支出額、残額、保留中の提案数を読み取ります
propose_purchase	保留中の購入意図のみを記録します。資金は移動しません。後で人間の承認が必要です
list_proposals	pending（デフォルト）／approved／rejected／all で提案を読み取ります
decide_proposal	人間による確認ステップです。approve は決済を実行します（ドライランの領収書と settlement_ref を作成し、残額を減らします）。reject は支出を発生させません。同じ提案を二重に決定することはできません
get_receipts	領収書を新しい順に読み取ります
refund_receipt	人間による確認ステップです。ドライランの決済を取り消し、予算を復元します

権限モデル

購入の提案にコストはほとんどかかりません。しかし、購入の決済にはコストがかかります。エージェントはお金を動かさずに、購入の意思を記録できます。購入を決済する、または領収書を取り消す呼び出しは、人間が確認する必要があります。

ホストは tools/list から title、description、annotations を読み取る必要があります。すべてのヒントは明示的に設定されています。仕様のデフォルト（readOnlyHint が false、destructiveHint が true、openWorldHint が true）のままでは、すべてのツールが破壊的なオープンワールドへの書き込みとして扱われてしまいます。Rail の台帳はローカルにあります。デフォルトモードはドライランです。ネットワーク接続も課金も発生しません。

ツール	readOnlyHint	destructiveHint	idempotentHint	openWorldHint	ホストの対応
set_budget	false	false	true	false	許可します。ローカルの上限のみを上書きします。同じ引数を繰り返しても、上限が積み重なったり支出されたりすることはありません
get_budget	true	false	true	false	許可します。読み取り専用です
propose_purchase	false	false	false	false	許可します。保留中の購入意思を1件追加しますが、支出は発生しません。呼び出すたびに新しい提案が作成されます
list_proposals	true	false	true	false	許可します。読み取り専用です
decide_proposal	false	true	true	false	人間に確認します。approve は決済を行い、残りの予算を減額します。繰り返しても再度決済されません
get_receipts	true	false	true	false	許可します。読み取り専用です
refund_receipt	false	true	true	false	人間に確認します。ドライランでの決済を取り消し、予算を復元します。繰り返しても再度返金されません

destructiveHint は確認を求める合図であり、true になるのは decide_proposal と refund_receipt のみです。すべてのツールで openWorldHint は false です。ドライランの処理が台帳の外に出ることはなく、ライブの Link は別の環境ゲートの内側に留まります。アノテーションはホスト向けのヒントです。それ自体でお金が動くことはありません。

モードのデフォルトは RAIL_MODE=dry_run です。金額は整数のセント単位で保存され、ツールは USD を小数点以下2桁で表示します。ID は prop_…、rcpt_…、settlement_ref 上のドライラン用 Link 参照は lsrq_dry_… です。

ローカルでのチェックアウト

このリポジトリでは、dogfood 用に tsx を開発依存関係として使用しています。npm run smoke は TypeScript ソースを直接実行するため、ビルドは不要です。npm start は最初にコンパイルしてから dist/index.js を実行します（rail-mcp の bin が指すファイルと同じです）。

npm install
npm start          # tsc → dist/, then stdio MCP server
npm run dev        # tsx watch src/index.ts
npm run smoke      # dry-run ledger smoke test; throwaway dirs only (never ./data, ~/.rail, or RAIL_DATA_DIR)

npm run smoke は RAIL_MODE=dry_run を強制し、ライブ課金ゲートを有効にせず、作成後に削除する一時ディレクトリ内にのみ台帳を書き込みます。環境で RAIL_DATA_DIR が設定されている場合も、./data、~/.rail、RAIL_DATA_DIR は変更されません。テストの1つでは、作業ディレクトリを / に、HOME を一時ディレクトリに設定してサーバーを起動し、その後ツールを呼び出します。この呼び出しは成功し、そのテストの台帳は /data や実際の ~/.rail ではなく、一時ホームディレクトリ内に作成されます。その起動時に RAIL_DATA_DIR を明示的に設定した場合は、デフォルトより優先されます。

Stripe Link seam

Rail は Link にワンタイム認証情報を要求します。予算とポリシーの判断、レシートの記録は引き続き Rail が行います。この接続部分ではカードを発行せず、UI も表示しません。

• RAIL_MODE=dry_run（デフォルト。未設定の場合も含みます）：createSpendRequest は偽の Link 支出リクエスト ID とステータス dry_run_pending_human を返します。Stripe または Link への HTTP 通信はありません。承認すると、その ID が settled_dry_run レシートの settlement_ref として保存され、残りの予算が減額されます。
• ゲートが設定されていない状態での RAIL_MODE=live： STRIPE_SECRET_KEY と RAIL_LIVE=1 の両方が設定されていない場合、live mode not enabled — set keys and get explicit human approval というエラーがスローされます。提案は保留中のままで、レシートは記録されません。
• この2つのゲートを設定したライブモード： POST https://api.link.com/spend_requests の本文はひな形のみです（src/stripeLink.ts を参照）。RAIL_ALLOW_LIVE_CHARGE=1 が設定されない限り、何も送信されません。
• RAIL_ALLOW_LIVE_CHARGE=1： Link の呼び出しが許可される唯一の分岐であり、さらに LINK_ACCESS_TOKEN も設定されている場合に限ります。STRIPE_SECRET_KEY は有無の確認にのみ使われ、送信されることはありません。Stripe Issuing によるカード発行はありません。ドキュメント：Link CLI、link-cli、Issuing for agents。
• ライブ支出は、これらの環境変数を意図的に設定するまで無効のままです。送信された Link リクエストは link_pending_human として保存され、ドライランの予算は減額されません。CI と npm run smoke はドライランのままで、課金は行いません。

環境変数	役割
RAIL_MODE	dry_run（デフォルト）または live
RAIL_DATA_DIR	台帳ディレクトリ。デフォルトはユーザーのホームディレクトリにある ~/.rail です。明示的に値を指定するとデフォルトが上書きされます
STRIPE_SECRET_KEY	ライブモードで必須です。カード発行にも、Link のベアラートークンにも使用されません
RAIL_LIVE=1	シークレットキーと併せて必要な、ライブモードへの明示的な承認
RAIL_ALLOW_LIVE_CHARGE=1	Link への HTTP 通信を実行する前に必要な追加ゲート
LINK_ACCESS_TOKEN	Link OAuth トークン。ひな形の POST を実際に実行する前に必要です

明示的な対象外

• マーケットプレイス UI はありません
• アウトリーチ／メッセージ送信はありません
• カード発行はありません
• ドライラン、CI、スモークテストでの実際の課金はありません

ライセンス

MIT。Copyright 2026 Thomas Stockham.