Servidor MCP

O Nexus expõe um servidor MCP (Model Context Protocol) remoto, por HTTP, para agentes de IA consultarem o estado das linhas e pedirem uma reconexão segura. A primeira versão é fechada de propósito: diagnóstico e recuperação, sem envio de mensagem, sem cobrança, sem exclusão e sem rotação de credenciais.

Endpoint

POST https://nexus.socialfy.me/mcp

Transporte: Streamable HTTP, o padrão dos clientes MCP atuais. Sem credencial válida o endpoint responde 401 antes de listar qualquer ferramenta.

Credenciais aceitas

Credencial	Alcance no MCP
Sessão do painel (`Authorization: Bearer <JWT>`)	As linhas da conta da pessoa
Chave da linha (`Authorization: Bearer nx_live_...`)	Só o chip da chave

A chave de API da conta ainda não é aceita no MCP. Quando entrar, será anunciada no changelog.

O agente nunca informa a conta nem a subconta: o servidor deriva tudo da credencial e recusa qualquer tentativa de operar uma linha fora dela.

Ferramentas

Ferramenta	O que faz	Proteção
`list_instances`	Lista as linhas autorizadas e a saúde de cada uma	Somente leitura; nunca devolve credenciais nem endereços internos
`get_instance_status`	Diagnóstico de uma linha e a próxima ação recomendada	Somente leitura
`get_instance_qr`	Lê o QR atual, quando já existe	Não gera, não limpa e não força sessão
`get_ghl_connection`	Lê a subconta e o provedor de conversa vinculados	Somente leitura; nunca devolve tokens
`reconnect_instance`	Inicia uma reconexão não destrutiva	Exige `confirm: true`; a intenção é auditada antes de tocar a linha

Fora do catálogo, de propósito: enviar mensagem, apagar ou desconectar linha, limpar sessão, reconexão forçada, cobrança, qualquer mutação no CRM e rotação de chaves.

Configuração num cliente MCP

mcp_servers:
  nexus:
    url: "https://nexus.socialfy.me/mcp"
    headers:
      Authorization: "Bearer nx_live_SUA_CHAVE"

Use a chave da linha quando o agente cuida de um número só. Para um agente que acompanha a conta inteira, use a sessão de uma pessoa com o papel adequado, e troque para a chave da conta quando ela for aceita.

Garantias de segurança

Falha fechada sem credencial válida.
A chave da linha não lista nem opera outra linha.
O QR é tratado como credencial sensível e não aparece em logs.
A reconexão sempre preserva a sessão existente; a versão destrutiva não está exposta.
Toda chamada de ferramenta fica na trilha de auditoria da conta.

Boas práticas

Dê ao agente a credencial de menor alcance que resolve. Na dúvida, chave da linha.
Trate reconnect_instance como ação humana: peça confirmação explícita na conversa antes de chamar com confirm: true.
Não deixe o agente repetir reconexão em loop. Uma tentativa, leitura do estado, e escalada para uma pessoa se não voltou.