Askell MCP

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). The public key is optional — only temporary payment-method and checkout status endpoints use it
• One of:
  • Bun ≥ 1.4.4 (for bunx), or
  • a prebuilt binary from Releases (no Bun needed)

Quick start

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

Variable	Required	Default	Description
ASKELL_PRIVATE_API_KEY	yes*	—	Secret API key (or ASKELL_SECRET_API_KEY)
ASKELL_PUBLIC_API_KEY	no	—	Public key for a few checkout/payment endpoints
ASKELL_ENV	no	production	production | sandbox — selects the official API host
ASKELL_API_BASE_URL	no	—	Custom/local API base only. Do not set together with ASKELL_ENV unless it matches
ASKELL_RESPONSE_MAX_BYTES	no	131072	Max response size returned to the model
ASKELL_MUTATION_GATE	no	auto	auto / elicit / off — see below
ASKELL_REQUIRE_MUTATION_APPROVAL	no	—	Deprecated alias: true→elicit, false→off

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

Tools

Tool	Description
askell_list_operations	Search bundled OpenAPI operations (paths, tags, error codes)
askell_describe_operation	Params, body schema, and response/error codes for one operation
askell_call	GET/HEAD any v1/v2 endpoint
askell_mutate	POST/PUT/PATCH/DELETE any v1/v2 endpoint
askell_paginate_all	Follow paginated list endpoints
askell_customer_overview	v1 customer + subscriptions (+ optional v2 contracts)
askell_contract_overview	v2 subscription contract + billing runs
askell_billing_run_triage	v2 billing run (+ optional contract)
askell_list_webhooks	List configured webhooks (hmac_secret redacted)

hmac_secret is the only field redacted in tool output. Customer-portal sign-in URLs and widget tokens (POST /v2/customer-portal-entries/, POST /v2/customer-portal-sessions/) are returned in full so the browser can use them. Do not put the widget token in a URL.

Resources

URI	Content
askell://spec/v1	OpenAPI v1
askell://spec/v2	OpenAPI v2
askell://docs/webhook-events	Webhook event reference

Skills (SEP-2640)

Clients supporting MCP Skills (skills/list, skills/get) can load bundled guidance on demand:

Skill	Purpose
askell-docs	Live Askell docs workflow and integration traps (claims, coupons, checkouts, webhooks)
askell-mcp	Tool selection, discovery, read/mutate split, and prod vs sandbox safety

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

License

MIT

Contributing

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