> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engineapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Servidor MCP

> Use o engineAPI com Claude, Cursor e qualquer agente AI via Model Context Protocol

O **Model Context Protocol (MCP)** é um padrão aberto da Anthropic que permite agentes AI interagirem com ferramentas externas de forma estruturada. O MCP Server do engineAPI expõe **9 tools fiscais** para qualquer cliente MCP compatível.

**Em 5 minutos** você terá o Claude emitindo notas fiscais em nome dos seus emissores.

## Início rápido: Claude Desktop

<Steps>
  <Step title="Obtenha sua API Key">
    Acesse [app.engineapi.com.br → Configurações → API Keys](https://app.engineapi.com.br/dashboard/api-keys) e copie sua chave (formato `ek_live_...`).
  </Step>

  <Step title="Configure o Claude Desktop">
    Edite o arquivo `~/.claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "engineapi": {
          "command": "npx",
          "args": ["@engineapi/mcp-server"],
          "env": {
            "ENGINEAPI_KEY": "ek_live_sua_chave_aqui"
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Reinicie o Claude Desktop e peça">
    > *"Liste meus emissores cadastrados no engineAPI"*
    >
    > *"Emita uma NFS-e de R\$ 3.500 para o CNPJ 12.345.678/0001-90, serviço de desenvolvimento de software"*
  </Step>
</Steps>

## Cursor / Continue.dev

Crie `.cursor/mcp.json` na raiz do seu projeto:

```json theme={null}
{
  "mcpServers": {
    "engineapi": {
      "command": "npx",
      "args": ["@engineapi/mcp-server"]
    }
  }
}
```

Adicione `ENGINEAPI_KEY=ek_live_...` nas variáveis de ambiente do Cursor.

## Modo HTTP (avançado)

Para integrações web (n8n, Make.com) ou servir múltiplos usuários por trás do
mesmo processo, suba o servidor no transporte **Streamable HTTP** (o
transporte oficial e atual da SDK do MCP):

```bash theme={null}
npx @engineapi/mcp-server --http --port 3015
```

Diferente do modo stdio, o modo HTTP é **multi-tenant**: o processo não lê
`ENGINEAPI_KEY` do ambiente; cada cliente autentica a PRÓPRIA sessão enviando
sua chave no header da requisição que conecta em `POST http://localhost:3015/mcp`:

```
x-api-key: ek_live_sua_chave_aqui
```

(ou `Authorization: Bearer ek_live_sua_chave_aqui`, equivalente).

<Note>
  Um host público hospedado pelo engineAPI (`mcp.engineapi.com.br`) está em
  preparação, ainda não está no ar. Até lá, o modo HTTP acima roda
  localmente/no seu próprio servidor; o modo stdio (seção anterior) é o caminho
  recomendado e testado hoje.
</Note>

## Variáveis de ambiente

| Variável             | Obrigatório      | Descrição                                                                                                         |
| -------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `ENGINEAPI_KEY`      | Sim (modo stdio) | Sua API Key (`ek_live_...`). No modo HTTP, cada cliente envia a própria chave via header, não é lida do ambiente. |
| `ENGINEAPI_BASE_URL` | Não              | Override da URL da API                                                                                            |
| `MCP_CORS_ORIGINS`   | Não              | Origens CORS (modo HTTP, default: `*`)                                                                            |

## Tools disponíveis

| Tool               | Descrição                                                                          |
| ------------------ | ---------------------------------------------------------------------------------- |
| `emitir_nfe`       | Emite NF-e (Modelo 55) com itens, NCM e destinatário                               |
| `emitir_nfce`      | Emite NFC-e (Modelo 65), cupom fiscal de venda no varejo/balcão a consumidor final |
| `emitir_nfse`      | Emite NFS-e de prestação de serviços                                               |
| `listar_notas`     | Lista documentos com filtros (tipo, status, período)                               |
| `consultar_status` | Status detalhado por ID ou chave de acesso (44 dígitos)                            |
| `cancelar_nota`    | Cancela nota autorizada com justificativa SEFAZ                                    |
| `listar_emissores` | Lista emissores com status do certificado digital                                  |
| `consultar_cnpj`   | Consulta dados na Receita Federal                                                  |
| `status_sefaz`     | Disponibilidade dos serviços SEFAZ por UF                                          |

## Exemplos de uso com Claude

```
// Emitir nota de serviço
"Emita uma NFSe de R$ 2.500 para a empresa 12.345.678/0001-90,
 serviço de consultoria em TI, emissor Alpha LTDA"

// Consultar notas do mês
"Liste as NFe autorizadas em maio de 2026"

// Verificar SEFAZ antes de emitir
"O SEFAZ de SP está funcionando?"

// Cancelar com justificativa
"Cancele a nota UUID-123, erro nos dados do destinatário"
```

## Segurança

* Sua `ENGINEAPI_KEY` nunca trafega para fora do engineAPI: ela é usada apenas para autenticar chamadas ao `api.engineapi.com.br`
* Todas as ações passam pelos Guards de autenticação e rate limit do seu plano
* Logs de auditoria são gerados normalmente para cada ação via MCP

<Note>
  O ambiente de **sandbox** (emissão em homologação SEFAZ) é ativado automaticamente quando o emissor selecionado tem `sandbox=true`. O MCP sempre informa quando está em modo sandbox.
</Note>