# IA e MCP

Há dois jeitos de usar IA com a emitza:

- **A IA emite as notas**, conectada pelo MCP (Model Context Protocol);
- **a IA escreve a sua integração**, lendo a documentação em formato próprio para ela.

## A IA emite as notas (MCP)

O servidor MCP fica em `/mcp`, no mesmo endereço da API, e usa a mesma chave:

| Endereço | Chave |
|---|---|
| `https://api-sandbox.emitza.com.br/mcp` | `fsk_test_...` (homologação, sem valor fiscal) |
| `https://api.emitza.com.br/mcp` | `fsk_live_...` (produção) |

Comece sempre pelo sandbox.

No Claude Code:

```bash
claude mcp add --transport http emitza https://api-sandbox.emitza.com.br/mcp \
  --header "Authorization: Bearer fsk_test_..."
```

Em clientes configurados por arquivo JSON (como o `mcp.json` de vários editores):

```json
{
  "mcpServers": {
    "emitza": {
      "type": "http",
      "url": "https://api-sandbox.emitza.com.br/mcp",
      "headers": { "Authorization": "Bearer fsk_test_..." }
    }
  }
}
```

Assistentes que só conectam por login OAuth, sem permitir um cabeçalho fixo, ainda não funcionam. O login OAuth chega junto com o portal do cliente.

### Ferramentas disponíveis

| Ferramenta | O que faz |
|---|---|
| `consultar_conta` | Diz se a chave é de teste ou de produção |
| `listar_empresas` | Empresas emitentes e os seus ids |
| `cadastrar_empresa` | Cadastra uma empresa (o certificado digital é enviado por você, nunca pela IA) |
| `calcular_impostos` | Calcula os impostos sem emitir |
| `emitir_nfe`, `emitir_nfse` | Emitem e esperam até 15 segundos pelo resultado |
| `consultar_nota` | Situação pelo id ou pelo externalId |
| `cancelar_nota` | Cancela; a IA é instruída a confirmar com você antes |
| `baixar_documento` | PDF (DANFE ou DANFSe) ou XML |

As ferramentas usam as mesmas regras da API: o mesmo `externalId` nunca gera duas notas, e a chave de teste só emite em homologação. Um erro de validação volta para a IA com o campo exato, para ela corrigir.

## A IA escreve a sua integração

Dê ao assistente um destes endereços:

| Endereço | Conteúdo |
|---|---|
| `https://docs.emitza.com.br/llms.txt` | Índice curto, com links para cada página em Markdown |
| `https://docs.emitza.com.br/llms-full.txt` | Toda a documentação num arquivo só: guias e referência de cada rota |
| `https://api.emitza.com.br/v1/openapi.json` | Contrato OpenAPI 3.1, para gerar o cliente da API |

Toda página deste site também existe em Markdown: troque o final do endereço por `index.md`.