Servidor MCP

O servidor MCP da Ephra publica as 142 operações da API do vendedor como ferramentas que um agente de IA chama sozinho. Em vez de escrever o cliente HTTP, autenticar, paginar e tratar 401, você aponta o agente para o servidor e conversa em português.

MCP (Model Context Protocol) é o protocolo que clientes como Claude Code, Claude Desktop e Cursor usam para descobrir e chamar ferramentas externas. O servidor da Ephra fala stdio e HTTP.

O que você ganha

143 ferramentas

Uma por operação da API, mais ephra_toolsets_list para o agente descobrir o que existe.

Token renovado sozinho

O token da Ephra dura 60 segundos. O servidor renova antes de expirar e repete a chamada em 401.

Anotações de segurança

Cada ferramenta declara readOnlyHint e destructiveHint — o agente sabe o que é leitura e o que devolve dinheiro.

Recorte por domínio

Sete toolsets. Ligue só os que a tarefa usa e poupe a janela de contexto do agente.

Como as ferramentas se chamam

O nome sai do caminho da rota mais o verbo do operationId: ephra_<recurso>_<ação>.

Operação da API	Ferramenta MCP
`GET /v1/products`	`ephra_products_list`
`POST /v1/products/v2`	`ephra_products_v2_create`
`POST /v1/products/{productId}/offers`	`ephra_products_offers_create`
`GET /v1/balance`	`ephra_balance_get`
`POST /v1/transfers`	`ephra_transfers_create`
`POST /v1/refund-requests/{refundRequestId}/approve`	`ephra_refund_requests_approve`

Os argumentos de cada ferramenta são os parâmetros de caminho, de query e os campos do corpo, num único objeto — com a mesma validação e os mesmos enums da API.

Os sete toolsets

Toolset	Ferramentas	Cobre
`catalog`	38	Produtos, ofertas, planos, cupons, order bumps, upsell, categorias
`growth`	30	Afiliados, coprodução, marketplace, indicações, recompensas, relatórios
`platform`	35	Chaves de API, time, webhooks, entregas, supressões, cadastro da empresa, subconta e integrações
`finance`	14	Saldo, extrato, bloqueios, saques, antecipações, taxas, conta bancária
`checkout`	12	Checkouts, links de pagamento, carrinhos abandonados, pixels
`refunds`	7	Pedidos de reembolso, quiz de retenção, contestações
`commerce`	6	Clientes, exportação de vendas, estorno de uma venda paga

Um agente com 143 ferramentas gasta contexto antes da primeira pergunta. Se a tarefa é financeira, suba com EPHRA_MCP_TOOLSETS=finance e o agente enxerga 14 ferramentas mais a de descoberta. Ligue tudo só quando não souber de antemão o que vai precisar.

Configure o seu cliente

Existem dois servidores: https://docs.ephra.io/mcp pesquisa a documentação. O servidor de ações usa https://api.ephra.io/mcp, após a publicação da versão da API com essa rota. É nele que você conecta as credenciais para consultar e alterar dados.

Conexão remota com chave de API

Gere o par apiKey e apiSecret em Dashboard › Chaves de API. Veja Primeiros passos. Configure seu cliente MCP para enviar o header Authorization: Basic <base64(apiKey:apiSecret)> em cada requisição:

Cliente MCP com headers HTTP

{
  "mcpServers": {
    "ephra": {
      "type": "http",
      "url": "https://api.ephra.io/mcp",
      "headers": {
        "Authorization": "Basic <BASE64_DA_CHAVE_DOIS_PONTOS_SEGREDO>"
      }
    }
  }
}

Para calcular o valor localmente, carregue suas credenciais nas variáveis e execute:

printf '%s:%s' "$EPHRA_API_KEY" "$EPHRA_API_SECRET" | base64 -w0

O servidor autentica cada chamada como a empresa dona desse par e obtém o token da API automaticamente. Você não precisa copiar nem renovar o JWT de 60 segundos. Todos os toolsets estão ligados por padrão, incluindo criação, edição e exclusão.

Base64 não criptografa a chave. Use HTTPS e guarde o header como um segredo, fora do Git. As credenciais permitem ações da empresa, inclusive reembolsos e saques; revise as operações antes de executá-las. Este fluxo usa chave de API, não OAuth. Clientes que aceitam somente OAuth precisam de outro método de conexão; use um cliente com headers HTTP ou stdio.

Conexão local por stdio

No stdio, as credenciais ficam no ambiente do processo:

Claude Desktop / Cursor

{
  "mcpServers": {
    "ephra": {
      "command": "node",
      "args": ["/opt/ephra-services/dist/apis/mcp/src/main.js"],
      "env": {
        "EPHRA_API_KEY": "sua-chave",
        "EPHRA_API_SECRET": "seu-segredo",
        "EPHRA_MCP_TOOLSETS": "all"
      }
    }
  }
}

Para desenvolvimento, suba o transporte HTTP local e configure o mesmo header no cliente:

node dist/apis/mcp/src/main.js \
  --transport http --host 127.0.0.1 --port 3333 --path /mcp

Variáveis e flags

Variável	Flag	Padrão
`EPHRA_API_KEY`	—	obrigatória no stdio
`EPHRA_API_SECRET`	—	obrigatória no stdio
`EPHRA_API_BASE_URL`	`--base-url`	`https://api.ephra.io`
`EPHRA_MCP_TOOLSETS`	`--toolsets`	`all`
`EPHRA_MCP_TRANSPORT`	`--transport`	`stdio`
`EPHRA_MCP_HTTP_PORT`	`--port`	`3333`
`EPHRA_MCP_HTTP_PATH`	`--path`	`/mcp`
`EPHRA_MCP_TIMEOUT_MS`	`--timeout`	`30000`
`EPHRA_MCP_LOG_LEVEL`	`--log-level`	`info`

No stdio, sem credenciais o servidor ainda sobe: tools/list funciona e as operações recusam a execução. No HTTP, initialize, tools/list e tools/call exigem autenticação por header. Credenciais ausentes ou inválidas recebem HTTP 401; falha no serviço de autenticação recebe HTTP 503. O HTTP nunca usa as credenciais de ambiente do servidor como fallback.

Uma tarefa resolvida

Peça em português:

Crie o produto “Curso de Tráfego Pago 2026” por R$ 499, categoria de cursos, com garantia de 7 dias, e me diga o link de venda.

O agente resolve em três chamadas, sem você escrever nenhuma.

Descobre a categoria

ephra_product_categories_list — para escolher um categoryId existente antes de criar o produto. Na criação V2, a categoria é opcional.

{
  "success": true,
  "data": [
    { "id": 1, "name": "Cursos e Treinamentos", "productCount": 436 }
  ],
  "pagination": { "page": 1, "pageSize": 10, "total": 1, "totalPages": 1 }
}

Cria o produto

ephra_products_v2_create com price: 49900 — o agente converte reais em centavos porque o schema diz que o campo é inteiro em centavos.

{
  "success": true,
  "data": {
    "id": "cmty05wl0000apyg1bx1566ej",
    "name": "Curso de Tráfego Pago 2026",
    "status": "approved",
    "categoryId": 1,
    "price": 49900,
    "productType": "digital",
    "billingType": "one_time",
    "refundPeriodDays": 7
  }
}

Busca o link

ephra_products_links_list com o id recém-criado, e devolve a URL do checkout ao usuário.

O que faz isso funcionar não é mágica: é a mesma descrição que você lê na Referência da API chegando ao agente como descrição de ferramenta, com o enum completo e o exemplo de payload.

Quando algo não aparece

O agente diz que a ferramenta não existe

O toolset dela está desligado. Peça ao agente para chamar ephra_toolsets_list: ele responde quais dos sete domínios estão habilitados nesta sessão. Acrescente o que faltar em EPHRA_MCP_TOOLSETS e reinicie o cliente MCP — a lista de ferramentas só é lida na conexão.

tools/call responde que faltam credenciais

No HTTP, confira o header Authorization: Basic e o par chave/segredo. As variáveis do servidor não substituem as credenciais do cliente. No stdio, EPHRA_API_KEY ou EPHRA_API_SECRET não chegaram ao processo. Clientes MCP não herdam o seu shell: as variáveis precisam estar no bloco env da configuração, não no .bashrc.

Erros 401 intermitentes

O token da Ephra dura 60 segundos e o servidor renova com folga de 10 segundos. Se mesmo assim aparecer 401, o relógio da máquina está fora de sincronia — ligue o NTP.

O agente inventa um id

Peça que ele liste antes de agir. As ferramentas _list existem para isso, e as descrições das ferramentas de escrita apontam qual listagem consultar primeiro.

Integração

API do vendedor

Cobranças

Assinaturas

Ajuda

Servidor MCP

O que você ganha

143 ferramentas

Token renovado sozinho

Anotações de segurança

Recorte por domínio

Como as ferramentas se chamam

Os sete toolsets

Configure o seu cliente

Conexão remota com chave de API

Conexão local por stdio

Variáveis e flags

Uma tarefa resolvida

Quando algo não aparece

​O que você ganha

143 ferramentas

Token renovado sozinho

Anotações de segurança

Recorte por domínio

​Como as ferramentas se chamam

​Os sete toolsets

​Configure o seu cliente

​Conexão remota com chave de API

​Conexão local por stdio

​Variáveis e flags

​Uma tarefa resolvida

​Quando algo não aparece

O que você ganha

Como as ferramentas se chamam

Os sete toolsets

Configure o seu cliente

Conexão remota com chave de API

Conexão local por stdio

Variáveis e flags

Uma tarefa resolvida

Quando algo não aparece