Askell MCP

Servidor MCP para a API de pagamentos e assinaturas da Askell. Descubra endpoints, inspecione clientes, contratos e cobranças, e chame a API pelo Cursor ou Claude.

GitHub

Experimente este MCPPatrocinado

Documentação

askell-mcp

Servidor MCP para a API de pagamentos e assinaturas do Askell.

Conecte-o ao Cursor, Claude Desktop ou qualquer cliente MCP para descobrir endpoints do Askell, inspecionar clientes/contratos/cobranças e chamar a API. Leituras e escritas são ferramentas separadas, para que os clientes possam exibir sua própria interface de aprovação em mutações.

Requisitos

Uma conta no Askell e chave de API secreta (no painel do Askell)
Um dos seguintes:
- Bun ≥ 1.4.0 (para bunx), ou
- um binário pré-compilado de Releases (sem necessidade de Bun)

Início rápido

1. Obtenha as chaves de API

No painel do Askell, copie sua chave de API privada (secreta). Opcionalmente, copie também a chave pública (necessária apenas para endpoints temporários de método de pagamento / status de checkout).

2. Adicione ao seu cliente MCP

Prefira duas entradas de servidor se você tiver chaves de produção e sandbox. Os nomes das ferramentas são os mesmos em ambos; o cliente os distingue pela chave do servidor (askell-prod vs askell-sandbox). As instruções de cada instância incluem o ambiente com o qual ela está falando.

Coloque as chaves em arquivos dotenv ignorados pelo git, não em JSON. Copie .env.example:

.env — produção (ASKELL_ENV=production e as chaves desse painel)
.env.sandbox — sandbox (ASKELL_ENV=sandbox e as chaves desse painel)

O Bun não carrega .env.sandbox automaticamente. --no-env-file impede que o processo de sandbox leia também um .env de produção que esteja no diretório de trabalho atual.

Cursor

Arquivo do projeto: .cursor/mcp.json. mcp.json.example tem este formato. ${workspaceFolder} é o diretório que contém esse mcp.json (a raiz do repositório quando o arquivo é .cursor/mcp.json). Em ~/.cursor/mcp.json, use um caminho envFile absoluto.

Com 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"
    }
  }
}

Com um binário (baixe askell-mcp-<os>-<arch> de Releases e depois chmod +x). Mesmo envFile; o binário lê o ambiente que o Cursor injeta:

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

Recarregue a janela após salvar.

Claude Desktop

Arquivo de configuração:

Linux: ~/.config/Claude/claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Sem campo envFile. O diretório de trabalho do processo do desktop não é o seu repositório, então um caminho .env relativo não resolve. Com Bun, passe um --env-file absoluto:

{
  "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"]
    }
  }
}

Um binário não tem --env-file. Coloque as chaves em env (texto simples nesse arquivo JSON):

{
  "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"
      }
    }
  }
}

Saia completamente do Claude Desktop e reabra-o. Salvar o arquivo não é suficiente.

Claude Code

O .mcp.json do projeto expande ${VAR} a partir do ambiente do processo que iniciou o claude. Ele não carrega um arquivo dotenv. Os argumentos --env-file do Bun da seção Desktop funcionam aqui também; um caminho relativo é suficiente quando você inicia o claude a partir do repositório. ${ASKELL_PRIVATE_API_KEY} dentro de env só funciona quando essa variável já está exportada nesse ambiente. Um arquivo .env sozinho não é lido.

Configuração

Variável	Obrigatório	Padrão	Descrição
`ASKELL_PRIVATE_API_KEY`	sim*	—	Chave de API secreta (ou `ASKELL_SECRET_API_KEY`)
`ASKELL_PUBLIC_API_KEY`	não	—	Chave pública para alguns endpoints de checkout/pagamento
`ASKELL_ENV`	não	`production`	`production` \| `sandbox` — seleciona o host oficial da API
`ASKELL_API_BASE_URL`	não	—	Base de API personalizada/local apenas. Não defina junto com `ASKELL_ENV`, a menos que corresponda
`ASKELL_RESPONSE_MAX_BYTES`	não	`64000`	Tamanho máximo de resposta retornado ao modelo
`ASKELL_MUTATION_GATE`	não	`auto`	`auto` / `elicit` / `off` — veja abaixo
`ASKELL_REQUIRE_MUTATION_APPROVAL`	não	—	Alias obsoleto: `true`→`elicit`, `false`→`off`

ASKELL_ENV escolhe um host estável (mesma superfície v1/v2):

produção — https://askell.is/api
sandbox — https://sandbox.askell.is/api (tenant isolado; chaves desse painel)

Aponte uma segunda entrada de servidor MCP para o sandbox (ASKELL_ENV=sandbox) em vez de alternar o ambiente em um único processo. As chaves não funcionam entre hosts. O Áskell Test Gateway é um adquirente de pagamentos (cartões falsos) em qualquer host — não é o mesmo que a API de sandbox. A documentação oficial em docs.askell.is ainda documenta o Test Gateway e pode omitir o host de sandbox.

ASKELL_MUTATION_GATE:

auto (padrão) — formulário de confirmação apenas se o envelope _meta desta requisição declarar elicitação de formulário (MCP 2026-07-28). Clientes da era 2025 (Cursor, a maioria dos hosts) não enviam esse envelope, então a mutação é executada e a própria interface "permitir esta ferramenta" deles é o controle.
elicit — sempre retornar um formulário de elicitação. O SDK recusa a chamada se o cliente não puder atendê-la (envelope 2026 / initialize 2025 via shim legado).
off — nunca perguntar (avaliação / automação confiável).

Se tanto ASKELL_MUTATION_GATE quanto ASKELL_REQUIRE_MUTATION_APPROVAL estiverem definidos, ASKELL_MUTATION_GATE vence.

O que você pode fazer

Fluxo de trabalho típico de agente:

Descobrir — askell_list_operations / askell_describe_operation (a partir do OpenAPI v1 + v2 incluído)
Tarefas de suporte — auxiliares de cliente/contrato/cobrança abaixo
Qualquer outra coisa — askell_call para GET/HEAD, askell_mutate para POST/PUT/PATCH/DELETE

Ferramentas

Ferramenta	Descrição
`askell_list_operations`	Buscar operações OpenAPI incluídas
`askell_describe_operation`	Parâmetros e esquema do corpo para uma operação
`askell_call`	GET/HEAD em qualquer endpoint v1/v2
`askell_mutate`	POST/PUT/PATCH/DELETE em qualquer endpoint v1/v2
`askell_paginate_all`	Seguir endpoints de listas paginadas
`askell_customer_overview`	Cliente v1 + assinaturas
`askell_contract_overview`	Contrato de assinatura v2 + execuções de cobrança
`askell_billing_run_triage`	Execução de cobrança v2 (+ contrato opcional)
`askell_list_webhooks`	Listar webhooks configurados (`hmac_secret` oculto)

Recursos

URI	Conteúdo
`askell://spec/v1`	OpenAPI v1
`askell://spec/v2`	OpenAPI v2
`askell://docs/webhook-events`	Referência de eventos de webhook

Notas da API (resumidas)

v1 — caminhos legados como /customers/, /subscriptions/ (sem prefixo /v2)
v2 — modelo atual: catálogos, cotações, checkouts, contratos, execuções de cobrança, cupons/códigos promocionais, pedidos de fulfillment em /v2/
Descontos v2 — CRUD de catálogo /v2/coupons/ + /v2/promotion-codes/ (cupom = definição, código promocional = o que o cliente digita). Contrato: GET/POST /v2/subscription-contracts/{id}/discount|apply-code|remove-discount (um ativo). Cotações aceitam promotion_code e, para um comprador existente, customer (id) para que descontos combinados + restrições promocionais se apliquem. Os totais do primeiro período já incluem cupom + combinado; quote.recurring_* incluem combinado, mas não o cupom (discount.recurring_final_amount enquanto o cupom estiver ativo). finalize recorrente exige um método de pagamento verificado mesmo quando o valor devido agora é 0. Não é o campo discount 0–100 da v1.
Fulfillment v2 — GET /v2/fulfillment-orders/ para backfill; POST .../{id}/fulfill/ (corpo de rastreamento opcional) e POST .../{id}/cancel/ marcam como enviado/cancelado. Mesmo corpo dos webhooks fulfillment_order.*.
Os caminhos usam barras finais
Prefira v2 para novas integrações; a v1 permanece para as existentes
Documentação: docs.askell.is · OpenAPI: v1 · v2

Licença

MIT

Contribuição

Veja CONTRIBUTING.md para desenvolvimento local, testes e releases.