API & MCP

MCP, para agentes de IA

O Model Context Protocol deixa um agente de IA usar o ionluz como ferramenta. O servidor fica em https://app.ionluz.com.br/api/mcp, fala Streamable HTTP com JSON-RPC 2.0 (protocolo 2025-06-18) e autentica só pela chave no cabeçalho Authorization: Bearer. Não há login por OAuth: o cliente MCP precisa deixar você informar esse cabeçalho. A chave de teste também conecta, com tudo em modo simulação.

Configuração

Em clientes que aceitam servidor remoto com cabeçalho num arquivo JSON:

{
  "mcpServers": {
    "ionluz": {
      "url": "https://app.ionluz.com.br/api/mcp",
      "headers": { "Authorization": "Bearer ilz_sua_chave" }
    }
  }
}

No Claude Code, pela linha de comando:

claude mcp add --transport http ionluz https://app.ionluz.com.br/api/mcp \
  --header "Authorization: Bearer ilz_sua_chave"

Ferramentas

O agente lê as descrições completas em tools/list.

• quote_solar recebe os mesmos campos de POST /v1/quote. Por padrão simula; passe persist: true para gravar a proposta e receber os links. Ao gravar, consent: true é obrigatório (consentimento LGPD do titular; sem ele a ferramenta devolve consentimento-obrigatorio). Nas contas com o motor novo, o argumento opcao escolhe qual opção vira a proposta (economica, recomendada ou bateria; padrão: a recomendada), como no REST.
• Cliente que não sabe o consumo em kWh: mande valorContaBrl, quanto ele paga de luz por mês. O consumo sai estimado pela tarifa, o structuredContent traz consumoEstimado: true e consumoKwhMes, e o texto diz de onde veio o número para o agente repassar (veja Pelo valor da conta de luz).
• idempotencyKey (argumento opcional de quote_solar, só com persist) dá a mesma garantia da Idempotency-Key do REST: repetir a mesma chave com os mesmos argumentos devolve a mesma proposta (idempotent: true no structuredContent), sem duplicar o lead; duas chamadas simultâneas nunca criam duas. As chaves são independentes das do REST. Sem idempotencyKey, não há deduplicação: retries podem duplicar.
• Chame coverage_status quando quote_solar voltar com faixa-nao-atendida, fora-da-area ou sem-preco-configurado: ela diz o que falta (plano e chave) e o que vale saber da cobertura e do modo de preço.

O que o agente recebe

Cada ferramenta devolve um texto pronto (content) e os dados (structuredContent). Em quote_solar, os dados são os campos da resposta de POST /v1/quote (orcamento, assumptions, preview e, ao gravar, proposalId, pdfUrl e propostaUrl). O texto de uma simulação com { "consumoKwhMes": 780, "uf": "SP", "cidade": "Campinas", "fases": "bi" } sai assim:

Sistema de 5,72 kWp por R$ 14.297, cobre 97% do consumo compensável (o consumo menos a taxa mínima da distribuidora), paga-se em 1,9 ano, economia de R$ 617 no 1º mês e R$ 396.502 em 25 anos. Simulação (não gravada). Estimativa sujeita a visita técnica.

Nas contas com o motor novo, o structuredContent ganha preco.publicado, opcoes, opcao, sistema, equipamento, validade e avisos, e o texto segue a publicação da conta. Com a faixa automática de uma conta que ainda cota pela referência ({ "consumoKwhMes": 600, "uf": "SP", "fases": "bi" }):

Sistema de 5,72 kWp entre R$ 13.500 e R$ 15.100 (o valor final é confirmado na visita técnica), cobre 121% do consumo compensável (o consumo menos a taxa mínima da distribuidora), paga-se em 2,2 anos, economia de R$ 527 no 1º mês e R$ 363.646 em 25 anos. Também há a opção econômica (4,29 kWp, entre R$ 10.900 e R$ 12.100) e a opção com bateria (5,72 kWp com bateria de 10 kWh, entre R$ 46.800 e R$ 51.800); os detalhes estão em opcoes no structuredContent. Simulação (não gravada). Estimativa sujeita a visita técnica.

Com "eu aprovo antes", nenhum número de preço, e a instrução para o agente não informar um:

Sistema de 5,72 kWp (inclui o deslocamento técnico de 103 km), cobre 97% do consumo compensável (o consumo menos a taxa mínima da distribuidora), o payback sai junto com o valor, economia de R$ 617 no 1º mês e R$ 396.502 em 25 anos. A Empresa Exemplo Energia Solar confirma o valor antes de apresentá-lo ao cliente; não informe número de preço. Também há a opção com bateria (5,72 kWp com bateria de 15 kWh); os detalhes estão em opcoes no structuredContent. Simulação (não gravada). Estimativa sujeita a visita técnica.

Programe o agente para dizer o preço como o texto e o preco.publicado dizem.

Chave de teste

Com a chave de teste, quote_solar ignora persist e avisa no texto, get_proposal responde (chave-de-teste) e as outras funcionam. O initialize avisa que a conexão é de teste. A cota é de 50 por dia na conta, somando as requisições REST e as chamadas de ferramenta do MCP; conectar e listar as ferramentas não gasta. A cota volta à meia-noite de Brasília.

Erros

GET no endereço responde 405: o servidor não abre stream (SSE), toda mensagem é um POST com uma resposta JSON.