Paymos MCP Server
OfficialPaymos MCP Server lets AI clients test Paymos payment workflows in a local sandbox and connect supported clients to a merchant account via OAuth.
Create, fetch, list, cancel, and simulate sandbox invoices, including paid, overpaid, underpaid, cancel, and paid-late outcomes.
Create, fetch, list, block, and unblock sandbox payment channels.
Simulate deposits and read/list confirmed payment-channel deposits with cursor-based polling.
Verify
X-Webhook-Signatureheaders locally against raw webhook bodies.Recommend invoices, payment channels, or both from a merchant’s payment-flow scenario.
Read five built-in Paymos documentation resources.
Connect supported IDEs/CLIs to a Paymos merchant account via OAuth 2.1 PKCE and configure the local OAuth bridge.
For connected merchants, use tools that create/rotate payment and payout credentials via a short-lived installer-ticket flow.
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., "@Paymos MCP Server Create a sandbox invoice for order #123 and simulate it as paid"
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.
@paymos/mcp
Paymos offers a local Sandbox server for integration testing and a hosted MCP connection for your merchant account.
Connect a merchant account
Connect any supported AI IDE or CLI to your Paymos merchant account with one command and no API keys:
npx -y @paymos/mcp authauth automatically detects installed clients (antigravity, claude-code, codex, kimi, zcode/glm, cursor, windsurf, opencode, claude-desktop, and project .vscode), opens Paymos in your browser for OAuth 2.1 PKCE S256 sign-in (merchant:mcp and offline_access), saves your OAuth session under OS-protected permissions outside IDE configs (%APPDATA%\Paymos\mcp\merchant-oauth.json on Windows, $XDG_CONFIG_HOME/paymos/mcp/merchant-oauth.json on Unix), and configures the local stdio OAuth bridge (@paymos/mcp connect). If a local Sandbox entry already occupies paymos, Merchant MCP is configured side-by-side as paymos-merchant.
Dashboard → Developers → Agents shows connection status, activity, recent operations and the Disconnect action.
Paymos command
npx -y @paymos/mcp auth
npx -y @paymos/mcp auth --client antigravity
npx -y @paymos/mcp auth --client glm
npx -y @paymos/mcp auth --client codex
npx -y @paymos/mcp auth --client claude-codeOptions for auth:
--client NAME:codex,claude-code,claude-desktop,antigravity,kimi,zcode(or aliasglm),cursor,windsurf,opencode,vscode, orgeneric--config PATH: explicit client configuration path (required forgeneric)--origin URL: custom Paymos origin (https://...or loopbackhttp://127.0.0.1/http://localhost, defaulthttps://app.paymos.io)--token-file PATH: custom OAuth token store path--no-login: write client configurations without opening browser login--dry-run: preview target files without signing in or writing
Local OAuth bridge (connect)
Configured clients launch npx -y @paymos/mcp connect (or cmd /d /c npx -y @paymos/mcp connect on Windows). connect responds to MCP startup requests (initialize, ping, tools/list, resources/list, prompts/list) locally without blocking IDE startup, triggers browser OAuth lazily on tools/call when needed, and transparently refreshes expired access tokens.
Direct URL connectors (cloud / native OAuth clients)
Clients that connect directly over Streamable HTTP OAuth 2.1 + DCR can use:
URL
https://app.paymos.io/connect/merchant-mcpOAuth scopes
merchant:mcpandoffline_access
Key and file delivery
The merchant tools can create and rotate Payment and Payout credentials under the merchant’s access policy. The tools return a short-lived installer ticket. The installer uses a verifier generated on the destination machine to exchange the ticket and save the credentials into the chosen environment file.
paymos install-secret --prepare --file .env --merchant-id "$PAYMOS_MERCHANT_ID" --environment production --operation-id "$PAYMOS_OPERATION_ID"
paymos install-secret --file .env --request-id "$PAYMOS_REQUEST_ID" --token "$PAYMOS_INSTALLER_TICKET"Pass the first command’s request_id and challenge as the tool’s delivery input with the same merchant, environment and operation ID. Run the second command on the same machine with the returned ticket. For private exports and staged logo or avatar uploads, the download-file and upload-file helpers use the same prepare-and-redeem flow with --file. Upload preparation also supplies the file size, content type and hash.
Withdrawals follow the merchant’s current policy and native approval rules. Manage withdrawal whitelist addresses from the dashboard.
Related MCP server: cryptunnel-mcp
Local Sandbox
The local stdio server provides 14 tools and five documentation resources for creating and simulating test invoices, checking invoice states and verifying webhook signatures. It signs API requests with the official SDK using a test Payment key pair.
Requirements
Requires Node.js 22.12 or later.
A Paymos merchant account with a test key pair from Dashboard → Developer → API Keys (
pk_test_…andsk_test_…)An MCP client that can launch a local stdio server
Setup the local server
Run:
npx -y @paymos/mcp setupChoose your client and enter your test key pair. Secret input is hidden. You can also supply a webhook secret for signature verification or press Enter to skip it. If the values are already in your environment, setup reads PAYMOS_API_KEY_ID, PAYMOS_API_SECRET, and optional PAYMOS_WEBHOOK_SECRET.
You can select the client in the command:
npx -y @paymos/mcp setup --client codexClient |
| Default configuration |
Codex |
|
|
Claude Code |
|
|
Claude Desktop |
| Claude's macOS or Windows configuration |
Antigravity |
|
|
Kimi CLI |
|
|
ZCode / GLM |
|
|
Cursor |
|
|
Windsurf |
|
|
OpenCode |
|
|
VS Code |
|
|
Another client |
| Explicit |
For OpenCode, setup uses an existing opencode.jsonc before opencode.json. To use a different configuration for any client, pass --config PATH. Claude Desktop on other operating systems needs an explicit path. Cline, Roo Code, and custom clients can use --client generic --config PATH with the MCP configuration path shown by that client.
Setup saves credentials separately, by default in $XDG_CONFIG_HOME/paymos/mcp/credentials.json or ~/.config/paymos/mcp/credentials.json when XDG_CONFIG_HOME is unset. Use --credentials-file PATH to choose another location outside your project. The client entry contains only PAYMOS_CREDENTIALS_FILE with that path; it does not contain your keys. Keep the credentials file out of version control.
To preview the proposed changes, run:
npx -y @paymos/mcp setup --client codex --dry-runDry-run writes no files and prints no secrets. Repeating setup with the same data does not add a duplicate entry. If existing Paymos settings or credentials differ, setup refuses to overwrite them so you can review the conflict. Other servers, comments, models, and client settings are preserved. An older Paymos entry with inline key environment variables also causes a conflict; setup does not migrate it automatically.
Restart or reconnect your MCP client after setup, then look for Paymos in its server list. Try asking the agent to create a sandbox invoice and simulate payment. Use npx -y @paymos/mcp setup --help for the full option list. Without an interactive terminal, provide --client and the required key environment variables; setup cannot ask for missing values there.
Kimi CLI is a client, distinct from the Kimi model. GLM, Kimi, and custom models can use Paymos through an MCP client if both the client and chosen model support tool calling. Setup does not change your model. For example, Z.ai explains how to run GLM in Claude Code; add Paymos using the Claude Code adapter after configuring the model.
Manual configuration
Create a credentials file outside the project:
{
"apiKeyId": "pk_test_…",
"apiSecret": "sk_test_…",
"webhookSecret": "whsec_…"
}webhookSecret is optional. On Unix, run chmod 600 /absolute/path/credentials.json after saving, using the actual absolute path. On Windows, keep the file in your account directory and check its existing access permissions. In the examples below, replace /absolute/path/credentials.json with the file's absolute path, and preserve your existing client settings.
Claude Code, Claude Desktop, Kimi CLI, Cursor, Windsurf, and generic clients
{
"mcpServers": {
"paymos": {
"command": "npx",
"args": ["-y", "@paymos/mcp"],
"env": {
"PAYMOS_CREDENTIALS_FILE": "/absolute/path/credentials.json"
}
}
}
}Use the locations in the setup table. Claude Code also accepts a project .mcp.json. Claude Desktop uses ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Cline and Roo Code show their configuration through MCP Servers → Configure.
Codex
Add to config.toml:
[mcp_servers.paymos]
command = "npx"
args = ["-y", "@paymos/mcp"]
[mcp_servers.paymos.env]
PAYMOS_CREDENTIALS_FILE = "/absolute/path/credentials.json"OpenCode
{
"mcp": {
"paymos": {
"type": "local",
"command": ["npx", "-y", "@paymos/mcp"],
"environment": {
"PAYMOS_CREDENTIALS_FILE": "/absolute/path/credentials.json"
},
"enabled": true
}
}
}VS Code
Add to .vscode/mcp.json or your user MCP configuration:
{
"servers": {
"paymos": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@paymos/mcp"],
"env": {
"PAYMOS_CREDENTIALS_FILE": "/absolute/path/credentials.json"
}
}
}
}Zed
Zed requires manual configuration; setup has no Zed adapter. On Unix, use ~/.config/zed/settings.json for global settings or .zed/settings.json for project settings. On Windows, open settings in Zed to find the actual settings.json file. Add:
{
"context_servers": {
"paymos": {
"command": "npx",
"args": ["-y", "@paymos/mcp"],
"env": {
"PAYMOS_CREDENTIALS_FILE": "/absolute/path/credentials.json"
}
}
}
}Windows
For each manual example, use this launcher on Windows:
"command": "cmd",
"args": ["/d", "/c", "npx", "-y", "@paymos/mcp"]OpenCode uses a single array: "command": ["cmd", "/d", "/c", "npx", "-y", "@paymos/mcp"]. For Codex TOML, set command = "cmd" and use the same argument array. Setup selects the Windows launcher automatically.
Existing credential options
The server still reads PAYMOS_API_KEY_ID, PAYMOS_API_SECRET, and optional PAYMOS_WEBHOOK_SECRET directly. The --api-key-id and --api-secret flags also remain available. Environment values take priority over flags, which take priority over fields in the credentials file. Avoid putting secrets in command history or tracked configuration.
Tools
Tool | Purpose |
| Recommend invoices, payment channels, or both from the merchant’s payment flow. Explain the fit and relevant lifecycle. When information is missing, return a targeted question instead of choosing. Respect an explicit merchant choice. |
| Create a sandbox invoice; idempotent per |
| Fetch the current invoice state |
| Fetch one cursor page of invoices, with filters |
| Cancel an unpaid invoice and store the reason |
| Simulate |
| Verify |
| Create a channel; idempotent per |
| Read a channel's current status and available deposit addresses |
| List one page of channels with filters and a cursor |
| Set a payment channel's status to blocked |
| Clear a payment channel's blocked status |
| Simulate a new |
| Read a deposit at any stage |
| Read one page of confirmed deposits, oldest first |
Each simulate_payment_channel_deposit call creates a new test deposit. The deposit feed returns only confirmed deposits. Save next_cursor from every response, including empty pages, and use it for the next poll. If the feed stops advancing, check blocked for the deposit and reason.
A deposit-feed cursor is valid for 24 hours; keep confirmed_from unchanged when continuing with that cursor.
paid_late is a simulation scenario, not an invoice status. See the sandbox documentation for its behavior.
Tool errors use { "code": "paymos/<api_error_code>", "message": "…" }. Sandbox and credential refusals use paymos/sandbox-only, paymos/missing-credentials, and paymos/invalid-credentials.
Resources
Five documentation pages are available inside the MCP session:
paymos://docs/quick-startpaymos://docs/hosted-checkoutpaymos://docs/webhookspaymos://docs/testing-sandboxpaymos://docs/server-sdks
Sandbox and credentials
The server opens no network listener and calls the Merchant API through @paymos/sdk. Setup output does not print secret values. Check your chosen client and model provider's logging settings separately. Setup stores keys in a separate local file; on Unix, new credential files use mode 0600 in a private directory. On Windows, access follows the account directory's permissions; the file is not encrypted by setup.
Live (pk_live_/sk_live_) and payout (rk_…) keys are rejected during setup, at server startup, and on tool calls. After checking your integration in the sandbox, run your own application with its live keys. This local MCP server stays outside production payment paths.
Development
npm install # @paymos/sdk resolves from ../typescript-sdk
npm run build:resources # regenerate documentation resources
npm test # package tests
npm run build # bundle to dist/License: MIT — see LICENSE.
Available Tools
15 toolsblock_payment_channelBlock payment channelC
Set a Sandbox payment channel's status to blocked.
Inputs: payment_channel_id (required).
cancel_invoiceCancel an invoiceA
Cancel an invoice that has not been paid yet; the reason is stored on the record. Invoices in a final status (paid, paid_over, underpaid, expired, cancelled) cannot be cancelled. Returns the invoice in wire form: invoice_id, status, payment_url, order, payment (expected, address, transfers), expires_at. status: awaiting_client | awaiting_payment | confirming | underpaid_waiting | paid | paid_over | underpaid | expired | cancelled.
Inputs: reason (required), invoice_id (required).
create_invoiceCreate a sandbox invoiceA
Create a Paymos invoice and get a hosted payment_url the customer opens. Idempotent per project: reuse the same external_order_id and you get the existing invoice back instead of a duplicate. Returns the invoice in wire form: invoice_id, status, payment_url, order, payment (expected, address, transfers), expires_at. status: awaiting_client | awaiting_payment | confirming | underpaid_waiting | paid | paid_over | underpaid | expired | cancelled.
Inputs: amount (required), currency (required), project_id (required), external_order_id (required), +3 more.
create_payment_channelCreate payment channelA
Create a Sandbox payment channel using project_id and external_id. Repeating the same pair returns the existing channel.
Inputs: project_id (required), external_id (required).
get_invoiceRead an invoiceA
Fetch the current state of one Paymos invoice by invoice_id. Returns the invoice in wire form: invoice_id, status, payment_url, order, payment (expected, address, transfers), expires_at. status: awaiting_client | awaiting_payment | confirming | underpaid_waiting | paid | paid_over | underpaid | expired | cancelled.
Inputs: invoice_id (required).
get_payment_channelGet payment channelB
Read a Sandbox payment channel by ID, including its current status and available deposit addresses.
Inputs: payment_channel_id (required).
get_payment_channel_depositGet payment channel depositB
Read a Sandbox payment channel deposit by ID at any stage, including confirming, reorged, and confirmed.
Inputs: payment_channel_deposit_id (required).
list_invoicesList invoicesA
Read one cursor-paginated page of invoices for a project. Filters: status (repeatable), external_order_id, created_from/created_to (Unix seconds). The result carries items[] and next_cursor — next_cursor is absent on the last page. Poll with the returned cursor; do not guess offsets.
Inputs: project_id (required), limit, cursor, status, +3 more.
list_payment_channel_depositsList confirmed channel depositsA
Poll confirmed Sandbox deposits, oldest first. Every response includes next_cursor, even on an empty page; save it for the next poll. If the feed stops advancing, the optional blocked field identifies the deposit and explains why.
Inputs: limit, cursor, project_id, confirmed_from, +1 more.
list_payment_channelsList payment channelsB
List Sandbox payment channels with optional project_id, external_id, and status filters. Use limit and cursor to request one page at a time.
Inputs: limit, cursor, status, project_id, +1 more.
recommend_payment_integrationRecommend a payment integrationARead-only
Recommend invoices, payment channels, or both from the merchant’s payment flow. Explain the fit and relevant lifecycle. When information is missing, return a targeted question instead of choosing. Respect an explicit merchant choice.
Inputs: scenario.
simulate_invoice_paymentSimulate a sandbox paymentA
Sandbox only: drive a test invoice through a payment outcome without touching a blockchain. The server derives the amounts — never compute money client-side. stage=paid marks it fully paid; overpaid pays more than expected; underpay pays less (invoice lands in underpaid waiting for a top-up); cancel voids it; paid_late pays the full amount after the deadline — the invoice keeps its terminal decision and gains the late-payment mark. Returns the invoice in wire form: invoice_id, status, payment_url, order, payment (expected, address, transfers), expires_at. status: awaiting_client | awaiting_payment | confirming | underpaid_waiting | paid | paid_over | underpaid | expired | cancelled.
Inputs: stage (required), invoice_id (required).
simulate_payment_channel_depositSimulate payment channel depositA
Create a new Sandbox deposit on every call using a channel ID, decimal-string amount, currency, and network. The optional stage accepts confirming, reorged, or confirmed and defaults to confirmed. No real blockchain is called, and no real funds move.
Inputs: amount (required), network (required), currency (required), payment_channel_id (required), +1 more.
unblock_payment_channelUnblock payment channelC
Clear a Sandbox payment channel's blocked status.
Inputs: payment_channel_id (required).
verify_webhook_signatureVerify a webhook signatureA
Verify the X-Webhook-Signature header of a Paymos webhook against its raw body, locally (no API call). Header format: t={unix},v1={hmac_hex("{unix}.{payload}")}; during secret rotation two v1= values are present and either may match. Use the raw request body byte-for-byte — re-serialized JSON breaks the signature.
Inputs: payload (required), signature_header (required), secret, tolerance_seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool targets a distinct resource and action: invoices, payment channels, channel deposits, webhook verification, and integration recommendation are cleanly separated. Sandbox simulation tools are explicitly scoped to their respective resources, and CRUD-style operations are unambiguous.
All tool names follow a consistent snake_case verb_noun pattern, such as create_payment_channel, get_invoice, list_invoices, and cancel_invoice. The resource ordering in simulate_invoice_payment versus simulate_payment_channel_deposit is slightly different but still predictable and readable.
Fifteen tools is well-scoped for a payment platform covering invoices, payment channels, sandbox simulation, and webhook verification. Each tool maps to a meaningful operation without obvious redundancy.
The surface covers core invoice and payment channel lifecycles, including create, read, list, cancel, block/unblock, deposits, and sandbox simulation. Minor gaps exist around refunds, disputes, or webhook endpoint management, but the main workflows are complete.
Maintenance
Related MCP Connectors
Build custom POS apps with your AI agent. Final's MCP server gives developers what they need to ship a custom point of sale: scaffold a checkout flow, adapt vetted screen blueprints for counter POS, self-checkout kiosks, restaurant ordering and payment terminals, ground every call in Final's version-locked POS APIs, validate, boot a live preview and deploy to real hardware with integrated card payments. The same server also manages the store behind it: products, stock, orders, customers and sales reports. Remote Streamable HTTP with OAuth 2.1.
Agent-to-business commerce sandbox: intents, offers, bookings. Demo data, ed25519-signed calls.
Agent-commerce MCP server for x402/USDC payments and affiliate splits on Base.
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
Related MCP Servers
AlicenseAqualityCmaintenanceEnables AI agents to answer Cryptbrew product questions and check live API health without merchant authentication. Exposes tools for pricing, FAQs, invoice flow, and health probes over stdio or streamable HTTP.8MIT
cryptunnel-mcpofficial
AlicenseAqualityCmaintenanceEnables coding agents to create and look up crypto payments over stdio, returning checkout links, payment statuses, paged payment lists, and receivable currencies, with real payments gated behind an explicit opt-in environment flag.4MIT- FlicenseNot gradedqualityAmaintenanceEnables AI coding agents to set up crypto checkout integration by registering workspaces, creating paylinks and public payment invoices, configuring webhook endpoints, verifying webhook signatures, and checking stablecoin payment status.-
- FlicenseNot gradedqualityAmaintenanceEnables AI coding agents to integrate stablecoin crypto checkout into applications by registering workspaces, configuring settlement wallets and webhooks, creating payment links and invoices, and verifying payment status and webhook signatures. It exposes these payment operations as tools over stdio so agents can complete end-to-end payment setup without manual dashboard work.-