askell-mcp

MCP server for the Askell payment and subscription API.

Connect it to Cursor, Claude Desktop, or any MCP client to discover Askell endpoints, inspect customers/contracts/billing, and call the API. Reads and writes are separate tools so clients can show their own approval UI on mutations.

Requirements

• An Askell account and secret API key (from the Askell dashboard)

• One of:

  • Bun ≥ 1.4.0 (for bunx), or

  • a prebuilt binary from Releases (no Bun needed)

Related MCP server: datagate-mcp

Quick start

1. Get API keys

In the Askell dashboard, copy your private (secret) API key. Optionally also the public key (only needed for temporary payment-method / checkout status endpoints).

2. Add to your MCP client

Prefer two server entries if you have both production and sandbox keys. Tool names are the same on both; the client distinguishes them by the server key (askell-prod vs askell-sandbox). Each instance's instructions include the environment it is talking to.

Put keys in gitignored dotenv files, not in JSON. Copy .env.example:

• .env — production (ASKELL_ENV=production and that dashboard's keys)

• .env.sandbox — sandbox (ASKELL_ENV=sandbox and that dashboard's keys)

Bun does not auto-load .env.sandbox. --no-env-file stops the sandbox process from also reading a production .env that happens to sit in the cwd.

Cursor

Project file: .cursor/mcp.json. mcp.json.example is this shape. ${workspaceFolder} is the directory that contains that mcp.json (the repo root when the file is .cursor/mcp.json). In ~/.cursor/mcp.json, use an absolute envFile path.

With Bun:

{
  "mcpServers": {
    "askell-prod": {
      "command": "bunx",
      "args": ["--no-env-file", "x", "askell-mcp"],
      "envFile": "${workspaceFolder}/.env"
    },
    "askell-sandbox": {
      "command": "bunx",
      "args": ["--no-env-file", "x", "askell-mcp"],
      "envFile": "${workspaceFolder}/.env.sandbox"
    }
  }
}

With a binary (download askell-mcp-<os>-<arch> from Releases, then chmod +x). Same envFile; the binary reads the environment Cursor injects:

{
  "mcpServers": {
    "askell-prod": {
      "command": "/absolute/path/to/askell-mcp-linux-x64",
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

Reload the window after saving.

Claude Desktop

Config file:

• Linux: ~/.config/Claude/claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

No envFile field. The desktop process cwd is not your repo, so a relative .env path does not resolve. With Bun, pass an absolute --env-file:

{
  "mcpServers": {
    "askell-prod": {
      "command": "bunx",
      "args": ["--no-env-file", "--env-file=/absolute/path/.env", "x", "askell-mcp"]
    },
    "askell-sandbox": {
      "command": "bunx",
      "args": ["--no-env-file", "--env-file=/absolute/path/.env.sandbox", "x", "askell-mcp"]
    }
  }
}

A binary has no --env-file. Put the keys in env (plaintext in that JSON file):

{
  "mcpServers": {
    "askell-prod": {
      "command": "/absolute/path/to/askell-mcp-linux-x64",
      "env": {
        "ASKELL_ENV": "production",
        "ASKELL_PRIVATE_API_KEY": "your_production_secret_api_key",
        "ASKELL_PUBLIC_API_KEY": "your_production_public_api_key_optional"
      }
    }
  }
}

Quit Claude Desktop completely and reopen it. Saving the file is not enough.

Claude Code

Project .mcp.json expands ${VAR} from the environment of the process that launched claude. It does not load a dotenv file. The Bun --env-file args from the Desktop section work here as well; a relative path is fine when you start claude from the repo. ${ASKELL_PRIVATE_API_KEY} inside env only works when that variable is already exported in that environment. A .env file alone is not read.

Configuration

ASKELL_ENV picks a stable host (same v1/v2 surface):

• production — https://askell.is/api

• sandbox — https://sandbox.askell.is/api (isolated tenant; keys from that dashboard)

Point a second MCP server entry at sandbox (ASKELL_ENV=sandbox) rather than switching env on one process. Keys do not work across hosts. Áskell Test Gateway is a payment acquirer (fake cards) on either host — not the same as the sandbox API. Official prose at docs.askell.is still documents Test Gateway and may omit the sandbox host.

ASKELL_MUTATION_GATE:

• auto (default) — confirmation form only if this request's _meta envelope declared form elicitation (MCP 2026-07-28). 2025-era clients (Cursor, most hosts) do not send that envelope, so the mutation runs and their own “allow this tool” UI is the gate.

• elicit — always return an elicitation form. The SDK refuses the call if the client cannot fulfil it (2026 envelope / 2025 initialize via the legacy shim).

• off — never ask (eval / trusted automation).

If both ASKELL_MUTATION_GATE and ASKELL_REQUIRE_MUTATION_APPROVAL are set, ASKELL_MUTATION_GATE wins.

What you can do

Typical agent workflow:

1. Discover — askell_list_operations / askell_describe_operation (from bundled OpenAPI v1 + v2)

2. Support tasks — customer/contract/billing helpers below

3. Anything else — askell_call for GET/HEAD, askell_mutate for POST/PUT/PATCH/DELETE

Tools

Resources

API notes (short)

• v1 — legacy paths like /customers/, /subscriptions/ (no /v2 prefix). Contracts-only accounts refuse new legacy subscriptions (400, code: legacy_subscriptions_disabled). A subscription whose billing moved to a contract refuses cancel/activate/set_expiry/PATCH (code: subscription_managed_by_contract, follow v2_endpoint).

• v2 — current model: catalogs, quotes, checkouts, contracts, billing runs, coupons/promotion codes, fulfillment orders under /v2/

• v2 contract changes — reference (max 128, no commas) on create/patch/list filter. Item update apply_at=now|period_end; cancel a scheduled change with POST .../scheduled-changes/{id}/cancel/. Move the billing anchor with POST .../change-anchor/, not PATCH. PATCH accepts only metadata, reference, payment_processor_override — ignore the description's delivery_address / accounting fields; they are not on V2SubscriptionContractPatch.

• v2 refunds — billing-run charges are not Payments. POST /v2/billing-runs/{id}/refund/ (full amount, no body). 202 means still succeeded; do not resend immediately. POST /payments/{uuid}/refund/ is one-off only. payment.* may carry billing_run_id.

• v2 discounts — catalog CRUD /v2/coupons/ + /v2/promotion-codes/ (coupon = definition, promotion code = what the customer types). Contract: GET/POST /v2/subscription-contracts/{id}/discount|apply-code|remove-discount (one active). Quotes take promotion_code and, for an existing buyer, customer (id) so combo discounts + promo restrictions apply. First-period totals already include coupon + combo; quote.recurring_* include combo but not the coupon (discount.recurring_final_amount while the coupon is active). Recurring finalize needs a verified payment method even when due-now is 0. Not the v1 discount 0–100 field.

• v2 fulfillment — GET /v2/fulfillment-orders/ for backfill; POST .../{id}/fulfill/ (optional tracking body) and POST .../{id}/cancel/ mark shipped/cancelled. Webhooks: fulfillment_order.created, shipment_booked (extra shipment_id), fulfilled, cancelled. Same body as GET.

• Paths use trailing slashes

• Prefer v2 for new integrations; v1 remains for existing ones

• Docs: docs.askell.is · OpenAPI: v1 · v2

License

MIT

Contributing

See CONTRIBUTING.md for local development, tests, and releases.