MCP server

Let your AI coding agent drive the JoPay integration: the CLI doubles as a stdio Model Context Protocol server authorized by your partner API key.

Overview

jopay mcpstarts an MCP server on stdio that exposes the v1 partner API as tools — create test payment requests, list accounts, register webhooks — so an agent can build and verify your integration end to end. Tool access follows the API key: the agent only ever sees tools its key's scopes allow, and the server enforces scopes again on every call.

Claude Code

claude mcp add jopay --env JOPAY_API_KEY=jo_test_xxx -- npx -y @jopay/cli mcp

Or after jopay login, the stored profile is used and no env var is needed:

claude mcp add jopay -- npx -y @jopay/cli mcp

Cursor and other MCP clients

Any client that launches stdio servers works with the same command. JSON configuration (Cursor mcpServers, Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "jopay": {
      "command": "npx",
      "args": ["-y", "@jopay/cli", "mcp"],
      "env": {
        "JOPAY_API_KEY": "jo_test_xxx",
        "JOPAY_BASE_URL": "https://admin.jopay.app"
      }
    }
  }
}

Tools

partner_info                       — identify the key: partner, mode, scopes
request_create                     — create a payment request   (requests:write)
request_list / request_get         — read payment requests      (requests:read)
request_cancel                     — void an open request       (requests:write)
account_list / account_get         — read accounts              (accounts:read)
account_create                     — provision a shell account  (accounts:write)
webhook_endpoint_list / _get       — read subscriptions         (webhooks:read)
webhook_endpoint_create            — register an endpoint       (webhooks:write)
webhook_deliveries_list            — inspect deliveries         (webhooks:read)
webhook_test                       — send a test event          (webhooks:write)

Deliberately not exposed over MCP: rotate-secret (secret material does not belong in an agent transcript) and endpoint update/delete stay in the CLI and portal; delivery replays stay in the portal. A human runs those.

Give agents scoped keys

Create a dedicated restricted key for agent use instead of reusing a full-access key. A sensible default for development is requests:read + requests:write on a jo_test_ key: the agent can create and verify test requests but cannot touch accounts or webhooks. Widen scopes only when the integration work needs them, and revoke the key when the work is done.

What this can never do

The MCP server is instruction-only, like everything on the partner API: it creates and reads payment-request data. It cannot move funds, sign transactions, or hold wallet keys — those capabilities are structurally absent from the API key model. On-chain results are observed and reported as proof_status: verified, never asserted.