> ## Documentation Index > Fetch the complete documentation index at: https://docs.ephra.io/llms.txt > Use this file to discover all available pages before exploring further. # Servidor MCP > Conecte um agente de IA à API da Ephra: o que o servidor MCP expõe, como configurar o cliente, como recortar os toolsets e uma tarefa resolvida do começo ao fim. 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 Uma por operação da API, mais `ephra_toolsets_list` para o agente descobrir o que existe. O token da Ephra dura 60 segundos. O servidor renova antes de expirar e repete a chamada em `401`. Cada ferramenta declara `readOnlyHint` e `destructiveHint` — o agente sabe o que é leitura e o que devolve dinheiro. 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__`. | 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](/guias/primeiros-passos). Configure seu cliente MCP para enviar o header `Authorization: Basic ` em cada requisição: ```json Cliente MCP com headers HTTP theme={null} { "mcpServers": { "ephra": { "type": "http", "url": "https://api.ephra.io/mcp", "headers": { "Authorization": "Basic " } } } } ``` Para calcular o valor localmente, carregue suas credenciais nas variáveis e execute: ```bash theme={null} 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: ```json Claude Desktop / Cursor theme={null} { "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: ```bash theme={null} 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. `ephra_product_categories_list` — para escolher um `categoryId` existente antes de criar o produto. Na criação V2, a categoria é opcional. ```json theme={null} { "success": true, "data": [ { "id": 1, "name": "Cursos e Treinamentos", "productCount": 436 } ], "pagination": { "page": 1, "pageSize": 10, "total": 1, "totalPages": 1 } } ``` `ephra_products_v2_create` com `price: 49900` — o agente converte reais em centavos porque o schema diz que o campo é inteiro em centavos. ```json theme={null} { "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 } } ``` `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](/api-reference/introducao) chegando ao agente como descrição de ferramenta, com o enum completo e o exemplo de payload. ## Quando algo não aparece 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. 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`. 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. 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.