Servidor MCP v2.0 — Especificação Técnica

📡 1. Transportes Protocolo JSON-RPC 2.0 / SSE

O Servidor MCP do Smartchat expõe um endpoint padronizado em https://chat.liberdade.digital/mcp suportando requisições JSON-RPC 2.0 via HTTP POST e Server-Sent Events (SSE).

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_flows",
    "arguments": { "status": "active" }
  }
}

🔑 2. Autenticação & Escopos Granulares (McpScope)

O Servidor MCP oferece dois métodos de autenticação segura com isolamento por Tenant:

• API Keys Diretas: Tokens prefixados com sc_mcp_live_... gerados no painel.
• OAuth2 Server Metadata (RFC 9728): Fluxo completo de autorização com código PKCE para integração de apps de terceiros.

Tabela de 14 Escopos de Permissão (Granulares)

mcp:full         -> Acesso total ilimitado a todas as ferramentas
leads:read       -> Leitura de dados de leads e contatos
leads:write      -> Alteração de campos e dados cadastrais
messages:read    -> Consulta do histórico de mensagens
messages:send    -> Envio de DMs e respostas a leads
tags:read        -> Listagem de etiquetas do tenant
tags:write       -> Atribuição e remoção de etiquetas
fields:read      -> Leitura de campos personalizados
fields:write     -> Edição de valores de campos personalizados
notes:read       -> Leitura de notas internas de CRM
notes:write      -> Adição de comentários e notas internas
flows:read       -> Listagem de fluxos, schema, analytics e execuções
flows:write      -> CRUD de fluxos, ordem de prioridade e growth tools
flows:trigger    -> Disparo de fluxos para leads (individual e em lote)

⚡ 3. Ferramentas de Gestão de Fluxos

O servidor expõe 24 ferramentas nativas de fluxo — leitura, CRUD completo validado pelo FlowPublisher e disparo:

list_flows({ status?, search? })       -> Fluxos cadastrados com contagem de execuções
get_flow({ flow_id })                  -> Estrutura visual em nós JSON do fluxo
get_flow_schema()                      -> Schema oficial de nós/arestas + exemplo JSON
get_flow_analytics({ flow_id })        -> Desempenho, conversão e pontos de abandono
list_flow_runs({ flow_id? })           -> Histórico de execuções
create_flow / update_flow              -> CRUD validado pelo FlowPublisher
duplicate_flow / delete_flow           -> Clonagem e remoção
toggle_flow_status({ flow_id, active}) -> Ativa ou pausa um fluxo em tempo real
reorder_flows({ order })               -> Prioridade estilo firewall entre regras
trigger_flow({ flow_id, lead_id })     -> Dispara o fluxo para um lead específico
batch_trigger_flow({ flow_id, tag })   -> Dispara em lote para os leads com a tag

Cada operação de escrita tem par em lote: batch_create_flows, batch_update_flows,
batch_duplicate_flows, batch_delete_flows.

🛡️ 4. Segurança Multi-Tenant & RLS PostgreSQL

Todas as chamadas MCP são executadas estritamente dentro do contexto do Tenant autenticado. O motor aplica Row Level Security (RLS) no PostgreSQL em nível de banco de dados e verifica proteções automáticas para contatos com flag de esquecimento LGPD.

💻 5. Configuração no Claude Desktop

Copie o trecho JSON abaixo e adicione ao seu arquivo claude_desktop_config.json:

{
  "mcpServers": {
    "smartchat": {
      "type": "url",
      "url": "https://chat.liberdade.digital/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer sc_mcp_live_SEU_TOKEN_AQUI"
      }
    }
  }
}