Skip to content
Integrations
Open .md
On this page

MCP Server

Connect Claude Code, Cursor, or any MCP client to a local Paymos server and let an agent build your integration with sandbox invoices and simulated payments.

@paymos/mcp connects your coding agent to the Paymos sandbox. The local Model Context Protocol server gives the agent six tools and five documentation resources to create invoices, simulate payments, inspect results, and check webhook signatures while writing your integration.

Requirements

Connect your client

Run this in your terminal:

npx -y @paymos/mcp setup

Choose the client you use, then enter your test key pair. Secret input is hidden. A webhook secret is optional; add it if you want the agent to verify webhook signatures. Setup can read the same values from PAYMOS_API_KEY_ID, PAYMOS_API_SECRET, and optional PAYMOS_WEBHOOK_SECRET instead.

To choose the client in the command, use --client:

npx -y @paymos/mcp setup --client codex
Client Value for --client Default configuration
Codex codex $CODEX_HOME/config.toml or ~/.codex/config.toml
Claude Code claude-code ~/.claude.json
Claude Desktop claude-desktop macOS or Windows Claude configuration
Kimi CLI kimi $KIMI_CODE_HOME/mcp.json or ~/.kimi-code/mcp.json
Cursor cursor ~/.cursor/mcp.json
Windsurf windsurf ~/.codeium/windsurf/mcp_config.json
OpenCode opencode OPENCODE_CONFIG or its user configuration
VS Code vscode .vscode/mcp.json in the current directory
Another client generic Supply --config PATH

Use --config PATH when your client reads a different file. Claude Desktop also needs an explicit path on operating systems other than macOS and Windows. For Cline, Roo Code, or your own MCP client, find its MCP configuration path and pass it with --client generic --config PATH.

The keys go in a separate JSON file at $XDG_CONFIG_HOME/paymos/mcp/credentials.json, or ~/.config/paymos/mcp/credentials.json when XDG_CONFIG_HOME is unset. Choose another location with --credentials-file PATH. The client configuration receives only PAYMOS_CREDENTIALS_FILE, pointing to that file. Keep the credentials file outside your project and version control.

You can inspect a proposed setup before saving it:

npx -y @paymos/mcp setup --client codex --dry-run
npx -y @paymos/mcp setup --help

Dry-run writes no files and does not print secrets. Running setup again with the same data leaves the existing entry in place. If the Paymos entry or credentials file differs, setup stops for you to review it rather than overwriting it. Other MCP servers, comments, model choices, and client settings stay as they are. An older Paymos entry with inline key environment variables is a conflict too; setup does not migrate it automatically.

Restart or reconnect your client after setup, then check that Paymos appears among its MCP servers. Ask the agent to create a sandbox invoice and simulate its payment. The server uses stdio without opening a network listener and calls the Merchant API through the official SDK.

Your client runs the server; your model decides how to use its tools. Kimi CLI is a client with its own configuration. GLM, Kimi, and custom models can use this server through an MCP client when the selected model and client support tool calling. A model name alone does not establish compatibility. For example, Z.ai documents GLM in Claude Code; configure Paymos in that client after setting up the model.

Configure manually

If you prefer to edit the configuration, create a credentials file outside your project:

{
  "apiKeyId": "pk_test_…",
  "apiSecret": "sk_test_…",
  "webhookSecret": "whsec_…"
}

Omit webhookSecret if you do not need signature verification. On Unix, run chmod 600 /absolute/path/credentials.json after saving the file, using its actual absolute path. On Windows, keep it in your account directory and check its existing access permissions. Replace /absolute/path/credentials.json below with the actual path.

Claude Code, Claude Desktop, Cursor, Windsurf, and generic clients

Add this entry to the client's MCP configuration:

{
  "mcpServers": {
    "paymos": {
      "command": "npx",
      "args": ["-y", "@paymos/mcp"],
      "env": { "PAYMOS_CREDENTIALS_FILE": "/absolute/path/credentials.json" }
    }
  }
}

Kimi CLI uses the same format in its mcp.json. For Claude Code, a project-level .mcp.json is also a manual option. Claude Desktop uses ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Preserve existing entries when adding Paymos.

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

Add to your OpenCode configuration:

{
  "mcp": {
    "paymos": {
      "type": "local",
      "command": ["npx", "-y", "@paymos/mcp"],
      "environment": { "PAYMOS_CREDENTIALS_FILE": "/absolute/path/credentials.json" },
      "enabled": true
    }
  }
}

VS Code

Use .vscode/mcp.json:

{
  "servers": {
    "paymos": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@paymos/mcp"],
      "env": { "PAYMOS_CREDENTIALS_FILE": "/absolute/path/credentials.json" }
    }
  }
}

Zed

Setup does not have a Zed adapter. On Unix, add the launcher manually under context_servers.paymos in ~/.config/zed/settings.json; project settings use .zed/settings.json. On Windows, open settings in Zed to find the actual settings.json file. Use command, args, and env from the generic example.

Windows launcher

For manual configuration on Windows, replace the launcher with:

"command": "cmd",
"args": ["/d", "/c", "npx", "-y", "@paymos/mcp"]

OpenCode instead uses "command": ["cmd", "/d", "/c", "npx", "-y", "@paymos/mcp"]. In Codex TOML, use command = "cmd" and the same argument array. Setup chooses this launcher automatically on Windows.

The server also accepts PAYMOS_API_KEY_ID, PAYMOS_API_SECRET, and PAYMOS_WEBHOOK_SECRET directly. Existing --api-key-id and --api-secret flags remain available: environment values take priority over flags, and flags take priority over the credentials file. Avoid putting secrets in command history or project configuration.

Tools and resources

Tool Purpose
create_invoice Create a sandbox invoice; idempotent per external_order_id; returns payment_url
get_invoice Read the current invoice state
list_invoices Read one cursor page of invoices with filters
cancel_invoice Cancel an unpaid invoice and store the reason
simulate_invoice_payment Simulate paid, paid_late, overpaid, underpay, or cancel in the sandbox
verify_webhook_signature Verify X-Webhook-Signature locally without an API call

The five resources are paymos://docs/quick-start, paymos://docs/hosted-checkout, paymos://docs/webhooks, paymos://docs/testing-sandbox, and paymos://docs/server-sdks.

paid_late simulates the late-payment case; it does not introduce a new invoice status. See sandbox testing for the scenario's behavior.

Sandbox boundary

Only test key pairs are accepted. Live (pk_live_/sk_live_) and payout (rk_…) keys are refused at setup, startup, and on tool calls. Once you have checked the integration, run your own application with its live keys; the MCP server remains outside production payment paths.

This page covers the local server. Hosted MCP is deferred; it is not an available connection method.

Next steps

Previous Server SDKs Next Security