Copy page

Developers

Merchant MCP

The Fluxis merchant MCP lets an assistant create payment links, hosted checkouts, and direct crypto payments with your API key. It speaks Streamable HTTP and does not keep a session.

Endpoints

Environment	URL	API key prefix
Local	http://localhost:8080/mcp	fxs.dev.
Sandbox (staging)	https://mcp.stgfluxis.us/mcp	fxs.stg.
Production	https://mcp.fluxis.us/mcp	fxs.prd.

GET /.well-known/mcp/server-card.json describes the server when MCP is enabled. GET and DELETE on /mcp return 405.

Sandbox is the staging deployment on mainnet. A sandbox charge is a real payment. Use a small amount. There is no payment simulator.

Authentication

Send the same API key you use for the REST API:

• x-fluxis-api-key and x-fluxis-api-secret, or
• Authorization: Bearer <api-key>:<api-secret>

The key prefix must match the host. A production key on the sandbox host is rejected.

Role	MCP access
read	Read tools only (payments:read)
write	Read tools and create or delete tools (payments:read and payments:write)

A failed credential returns 401 with {"error":"invalid_token","error_description":"..."} and WWW-Authenticate: Bearer realm="fluxis". OAuth is not supported.

Every tool checks that the point of sale belongs to the credential. An account key sees only that account. An organization key sees the accounts in its reach.

Tools

Call fluxis_get_context first.

Tool	Access	Purpose
fluxis_get_context	read	Environment, credential owner, each point of sale and whether it supports links and checkout, default online point of sale
fluxis_list_points_of_sale	read	Points of sale this key can use
fluxis_list_payment_links	read	Payment links. Default status is active
fluxis_get_payment_link	read	One link by id or code, plus stats and five recent payments
fluxis_get_payment	read	One payment by id, or the newest payment for a reference
fluxis_list_payments	read	Payments. Default window is the last 30 UTC days, maximum 92
fluxis_list_transactions	read	Ledger transactions after a payment is confirmed
fluxis_get_payment_options	read	Crypto assets the point of sale accepts
fluxis_create_payment_link	write	Reusable link to share with buyers
fluxis_delete_payment_link	write	Soft-delete, two steps
fluxis_create_checkout	write	One-off hosted checkout page
fluxis_create_crypto_payment	write	Direct crypto payment request

Payment link fields

name is shown to the buyer as the merchant name. buyer_reference is your internal order or invoice id. The buyer does not see it as the product title. On the REST API the same field is external_id.

If you omit both expiration and expires_in_minutes, the link does not expire. Send at most one of them. expires_in_minutes is from 5 to 43200. expiration is an RFC3339 timestamp in the future.

Delete confirmation

The first fluxis_delete_payment_link call does not delete the link. It returns a confirmation_token that lasts 300 seconds. Ask the user to confirm, then call the tool again with that token. Deleting a link that is already deleted succeeds and reports already_deleted.

Idempotency and limits

Pass idempotency_key (8 to 64 letters, digits, _, or -) on creates. The same key and the same input return the original result for 24 hours. The same key with a different input returns a conflict.

Per credential, each minute: 120 reads, 20 writes, 10 deletes. A limited tool call returns RATE_LIMITED and retry_after_seconds.

Resources and prompts

• fluxis://docs/quickstart
• fluxis://docs/payment-statuses
• fluxis://catalog/payment-options
• fluxis://payments/{payment_id}
• Prompts: fluxis_charge_customer, fluxis_integrate, fluxis_sales_summary

Payment links are also available over REST. See Payment Links.