Connect an AI assistant with MCP

#Connect your assistant

The official Railbed MCP server lets your assistant work with one business in Test or Live mode. You sign in with your usual Railbed account and choose its access. You do not paste a secret key into your assistant.

https://mcp.railbed.io/mcp

1. Add this URL as a remote HTTP or Streamable HTTP MCP server in your assistant.
2. Sign in to Railbed when your client opens the WorkOS authorization page.
3. Ask your assistant to connect to your Railbed business. It calls railbed_connect and gives you a Railbed approval link.
4. Open that link. Choose a business, a connection name, Test or Live, and Read only or Full access. Select Connect assistant.
5. Return to your assistant. Ask it to check the connection before working with your records.

You must be an owner or developer of the business to connect. Your current business role still limits the available actions. Test and Full access are selected initially. Choose Live when you need real records, or Read only if the assistant should only look up information. Full access still requires your confirmation for each proposed change.

#ChatGPT and Codex

Add the URL through your client's MCP or custom-connector settings and choose OAuth authentication. Availability depends on your account and workspace settings. Follow the client's sign-in flow, then complete the Railbed business approval above.

For the Codex CLI:

codex mcp add railbed --url https://mcp.railbed.io/mcp
codex mcp login railbed

#Claude Code

claude mcp add --transport http railbed https://mcp.railbed.io/mcp

Open /mcp in Claude Code to authenticate. For Claude's web or desktop app, add the same URL as a custom connector where your plan and workspace allow it.

#Other MCP clients

Choose a remote HTTP connection with OAuth. A typical configuration looks like this; use your client's documented configuration format:

{
  "mcpServers": {
    "railbed": {
      "type": "http",
      "url": "https://mcp.railbed.io/mcp"
    }
  }
}

Railbed supports the current stateless MCP protocol and older clients using an initialization handshake. A local package or command is not required.

#What you can ask

Show the latest 10 Test payments and explain any held payments.

Prepare a Test payment link for USD 49.00 for a website consultation.
Give me the Railbed review link before creating it.

Show my webhook endpoints and the latest failed deliveries.

Read only connections cannot prepare changes. Full access allows proposals within your current business role. Wallets, fees, fund transfers, refunds, accepting held payments, secret retrieval and platform administration are outside this server's tools. Shopify and WooCommerce credential setup stays in their Railbed integration pages; the MCP server can show availability and help configure webhooks.

#Review changes in Railbed

Every write tool prepares a proposal. It returns an operation_id and a confirmation_url; it has not yet changed the checkout, payment link or integration.

1. Open the Railbed review link. It names the assistant, business and mode and shows the proposed values.
2. If needed, switch to that business and mode using the review page.
3. Check amounts, descriptions and destination URLs. Select Confirm change or Cancel proposal.
4. Ask your assistant to check the operation. It reports completion only after Railbed records the outcome.

Proposals expire after 15 minutes. Your assistant cannot approve one through an MCP tool. Webhook configuration deserves particular care: events can include payment and customer details, and pending retries use an endpoint's updated URL. A Test webhook still makes a real HTTP request; Live endpoints accept a ping rather than a synthetic payment event.

#Avoid duplicates

Write tools require an idempotency_key for the intended change. Your assistant should keep that key and reuse the same arguments after an interrupted response. The same key returns the same proposal; a different proposal needs a new key.

If an operation reports unknown, the change may already have happened. Inspect the linked dashboard before preparing another proposal. Railbed will not run that operation again automatically.

#Data and access

Each connection is fixed to one business and mode. A tool cannot switch it using a mode or business argument. To change its access, disconnect it and approve a new connection.

A business can have up to 100 active connections in each mode. Disconnect an unused connection in Developers before adding another at the limit. Clients that support token refresh can request ongoing access from WorkOS; a refreshed token still needs an active Railbed business approval.

Lists return small pages, with next_cursor when there is more. Use the same filters on the next page. Amounts are decimal text and record timestamps are Unix seconds. Read tools report stored status without starting payments, contacting card providers or advancing a payment's lifecycle. Use the returned expiry time alongside status when a payment is waiting for the normal expiry process.

Only connect assistants you trust with the requested business records. Order and customer detail tools can return contact and address information. List summaries keep those details smaller. API keys, webhook signing secrets, provider credentials and webhook receiver query values are never returned. Payment and checkout URLs are returned when they are needed to share or inspect a payment request.

Proposed input is cleared when it is applied, canceled or expires. Minimal operation receipts are retained for 90 days. Your assistant provider has its own handling of information returned to it.

#Disconnect a client

Open Developers, choose the connection's Test or Live mode and find MCP connections. Select Disconnect and confirm. Its next request is refused and unconfirmed proposals are canceled. Existing checkouts and payment links remain in your business.

Access also ends if the person who approved it loses permission to manage that business or their sign-in is disabled. Re-adding them does not restore the old approval. A change already being applied can finish; disconnecting does not undo it.

#Troubleshooting

• For AI agentsDocumentation tools, WebMCP and agent sign-in through the merchant API.→
• Test and LiveUnderstand simulated and real payment records.→
• Merchant APIBuild a server integration with the published API.→