MCP Server v2.0 — Technical Specification

📡 1. JSON-RPC 2.0 / SSE Protocol Transports

Smartchat MCP Server exposes a standardized endpoint at https://chat.liberdade.digital/mcp supporting JSON-RPC 2.0 requests via HTTP POST and 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. Authentication & Granular Scopes (McpScope)

The MCP Server offers two secure authentication methods with per-tenant isolation:

• 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.

Table of 14 Granular Permission Scopes

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. Flow Management Tools

The server exposes 24 native flow tools — reading, full CRUD validated by FlowPublisher, and triggering:

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. Multi-Tenant Security & PostgreSQL RLS

All MCP calls execute strictly within the authenticated Tenant context. The engine applies PostgreSQL Row Level Security (RLS) at the database layer and checks automatic protections for contacts with LGPD erasure flags.

💻 5. Claude Desktop Setup

Copy the JSON snippet below and add it to your file 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"
      }
    }
  }
}