API & MCP

MCP, para agentes de IA

O Model Context Protocol deixa um agente de IA (Claude, ChatGPT via conectores, ou o seu próprio) usar a ionluz como ferramenta. Aponte o cliente MCP para https://app.ionluz.com.br/api/mcp com a sua chave e o agente ganha cinco ferramentas prontas, sem você escrever integração alguma. A chave de teste também conecta: o agente explora tudo em modo simulação antes de a conta virar assinante.

Configuração (clientes com MCP remoto/HTTP)

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

Ferramentas expostas

// tools/list devolve:
[
  { "name": "quote_solar",     "description": "Gera um orçamento de energia solar a partir do consumo..." },
  { "name": "check_coverage",  "description": "Lista quais faixas (kW de saída de inversor) × fase o integrador atende..." },
  { "name": "list_kits",       "description": "Lista os kits disponíveis para a conta, com kWp, módulos e se são precificáveis..." },
  { "name": "get_proposal",    "description": "Recupera uma proposta já gravada desta conta pelo id..." },
  { "name": "coverage_status", "description": "Diz o que falta configurar para a API responder cotações..." }
]

• quote_solar, cota a partir do consumo. 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 o erro consentimento-obrigatorio).
• idempotencyKey (argumento opcional de quote_solar, só com persist), 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.
• check_coverage, lista as faixas atendidas, para o agente cotar só o que existe.
• list_kits, lista os kits disponíveis para a conta, com potência em kWp, número de módulos, fases compatíveis e se o kit é precificável. Aceita os filtros fase, somentePrecificaveis e somenteMeus. Preço de custo fica de fora, é dado interno da conta.
• get_proposal, recupera uma proposta já gravada desta conta pelo id, com origem, data, kWp, valor, dados do cliente e links assinados. Chave viva apenas.
• coverage_status, diz em linguagem clara o que falta configurar para a API responder: plano, chave, régua de cobertura por fase e formação de preço. É a ferramenta a chamar quando quote_solar devolver faixa-nao-atendida ou sem-preco-configurado.

O transporte é Streamable HTTP (JSON-RPC 2.0). A negociação (initialize), a listagem (tools/list) e a execução (tools/call) seguem o protocolo padrão, qualquer cliente MCP compatível conecta. Falhas internas chegam como erro JSON-RPC estruturado (-32603, erro-interno) ou como resultado de ferramenta com isError, nunca um 500 sem envelope.