Servidor MCP

Como conectar agentes de IA aos dados da sua conta pelo protocolo MCP, com chave de API ou OAuth.

O mesmo serviço que responde à API pública também expõe um servidor MCP, do Model Context Protocol. Ele entrega os dados da sua conta como ferramentas que um agente de IA, o Claude por exemplo, consegue chamar sozinho, sem ninguém escrever integração.

Na prática funciona assim: em vez de você programar uma chamada a GET /v1/contatodechat, o agente recebe uma ferramenta listar_contatos e decide quando usá-la.

O servidor MCP não é um recurso separado com dados próprios. Ele é outra porta de entrada para os mesmos registros, com a mesma separação por conta.

O servidor MCP faz parte do Plano Avançado, do Plano Premium e do Plano Revenda, e a conta em avaliação também usa. Contas no Plano Básico integram pela API REST, descrita nas outras páginas desta aba. Sem o recurso no plano, o endereço /mcp responde 403 e a tela de configuração fica somente leitura.

Endereço

https://api-publica.sunchat.com.br/mcp

O endereço da sua conta aparece na plataforma, em Opções › Servidor MCP, já pronto para colar na configuração do cliente.

Para o passo a passo no ChatGPT e no Claude, com as telas de cada um, veja Conectar o ChatGPT e o Claude à sua conta.

O servidor vem ativo, com todas as ferramentas habilitadas, e pode ser desligado por conta. Quando ele está desativado em Opções › Servidor MCP, o endereço /mcp não responde, mesmo com credenciais válidas. A mesma tela escolhe quais ferramentas ficam visíveis para o agente.

O que o agente consegue fazer

O servidor expõe 120 ferramentas, e elas cobrem os mesmos recursos da API REST. A tela de configuração lista 119 delas em 22 grupos, com um interruptor por ferramenta.

Grupo	Ferramentas	Exemplos
Contatos	15	`listar_contatos`, `criar_contato`, `vincular_etiquetas_contato`
Pipelines	9	`listar_funis`, `criar_funil`, `obter_estatisticas_funil`
Etapas do Funil	9	`listar_etapas_funil`, `reordenar_etapas_funil`, `mover_negocios_entre_etapas`
Negócios	11	`listar_negocios`, `criar_negocio`, `mover_negocio_para_etapa`
Produtos do Negócio	4	`listar_produtos_negocio`, `vincular_produto_negocio`
Atividades	10	`criar_atividade`, `concluir_atividade`, `reabrir_atividade`
Produtos	4	`listar_produtos`, `obter_produto`, `criar_produto`
Etiquetas	5	`listar_etiquetas`, `criar_etiqueta`, `excluir_etiqueta`
Motivos de Perda	5	`listar_motivos_de_venda`, `criar_motivo_de_venda`
Listas de Contato	5	`listar_listas_de_contato`, `criar_lista_de_contato`
Campos Personalizados	5	`listar_campos_personalizados`, `criar_campo_personalizado`
Canais	2	`listar_canais`, `obter_canal`
Conversas	3	`buscar_atendimentos_chat`, `obter_atendimento_chat`, `buscar_mensagens_conversa`
Tickets	3	`listar_tickets`, `obter_ticket`, `obter_ticket_por_codigo`
Departamentos	5	`listar_departamentos`, `criar_departamento`
Tipos de Atividade	5	`listar_tipos_de_atividade`, `criar_tipo_de_atividade`
Reuniões	6	`listar_reunioes`, `criar_reuniao`, `cancelar_reuniao`
Anotações do Negócio	5	`listar_anotacoes_negocio`, `criar_anotacao_negocio`
Usuários	1	`listar_usuarios`
Origens do Negócio	5	`listar_origens_do_negocio`, `criar_origem_do_negocio`
Consulta de CNPJ	1	`consultar_cnpj`
Consulta de CEP	1	`consultar_cep`

A ferramenta que sobra é solicitar_pagamento, que gera um pedido de pagamento. Ela não tem interruptor próprio hoje, então acompanha o interruptor geral do servidor.

Cada ferramenta na tela vem com um selo de risco. Baixo é leitura e atualização de registro existente, em 84 ferramentas. Médio é criação e vínculo, em 19. Alto é exclusão, em 16.

Fluxo com o gatilho MCP Server Tool também vira ferramenta no servidor. Elas aparecem em um grupo à parte e obedecem ao interruptor Ferramentas de fluxos (MCP Server Tool).

Boa parte das ferramentas escreve. Um agente com acesso ao servidor MCP consegue criar contatos, mover negócios e cancelar reuniões, então trate esse acesso com o mesmo cuidado que você trataria a chave de API.

Usar as ferramentas pela Luma

A Luma, a assistente dentro do SunchatPlus, também consegue usar essas mesmas ferramentas. Com isso, pedidos como "crie o departamento Financeiro" ou "liste os departamentos ativos" são atendidos na própria conversa, e o resultado aparece em um cartão com link para a tela correspondente.

Vem desligado. Para ligar, vá em Opções → Servidor MCP e ative:

Servidor MCP — o servidor precisa estar ativo.
Usar na Luma — libera a assistente a chamar as ferramentas.

Só administradores da conta conseguem usar as ferramentas pela Luma. Para os demais usuários ela continua respondendo apenas com base na documentação, sem acesso aos dados da conta.

As ferramentas que você desabilitou nesta tela ficam fora da Luma também — a lista é a mesma para agentes externos e para a assistente. Cada chamada feita pela Luma fica registrada no histórico de consultas da conta, com o nome da ferramenta e o horário.

Autenticação

O /mcp aceita duas formas de credencial. Escolha pelo cliente que vai conectar.

Chave de API

Os mesmos cabeçalhos da API REST, descritos em Autenticação:

{
  "mcpServers": {
    "sunchatpluscrm": {
      "url": "https://api-publica.sunchat.com.br/mcp",
      "headers": {
        "X-Ambiente": "12345",
        "X-Authorization": "X-Chave-Api sua-chave-aqui"
      }
    }
  }
}

É o caminho mais simples, e serve para cliente próprio, script ou agente que roda no seu servidor. A contrapartida é que a chave fica guardada em arquivo de configuração, e ela dá acesso total à conta.

OAuth 2.1

Para clientes que sabem fazer OAuth, basta apontar para o endereço do /mcp, sem cabeçalho nenhum. O cliente descobre o resto sozinho, porque o 401 inicial já traz o caminho dos metadados, e o registro e a negociação seguem dali.

{
  "mcpServers": {
    "sunchatpluscrm": {
      "url": "https://api-publica.sunchat.com.br/mcp"
    }
  }
}

O navegador abre, você entra com o seu usuário do SunchatPlus, escolhe a conta e autoriza. Nenhuma chave é copiada, e o acesso fica no nome do seu usuário.

Detalhes do OAuth

Para quem está escrevendo um cliente MCP, o servidor de autorização fica no mesmo host da API e segue as especificações que os clientes MCP esperam:

Item	Valor
Metadados do servidor de autorização	`/.well-known/oauth-authorization-server` (RFC 8414)
Metadados do recurso protegido	`/.well-known/oauth-protected-resource/mcp` (RFC 9728)
Autorização	`/connect/authorize`
Token	`/connect/token`
Registro dinâmico de cliente	`/connect/register` (RFC 7591)
Chaves públicas	`/.well-known/jwks`
Fluxos	`authorization_code` e `refresh_token`
PKCE	Obrigatório (`S256`)
Escopos	`mcp`, `offline_access`, `openid`

O token é um JWT que carrega a conta escolhida, e vale para uma conta só. Para operar em outra, é preciso autorizar de novo e escolher a outra conta.

O 401 do /mcp traz WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp". Um cliente MCP compatível usa esse cabeçalho para achar o servidor de autorização por conta própria. Você não precisa configurar endereço de autorização em lugar nenhum.

MCP ou API REST?

Use MCP quando	Use a API REST quando
Um agente de IA precisa consultar e agir sobre a conta	Você está escrevendo a integração e sabe exatamente quais chamadas fazer
O conjunto de ações não é conhecido de antemão	O fluxo é fixo: recebeu pedido, cria contato, envia mensagem
O consumidor é o Claude, um assistente ou um copiloto	O consumidor é o seu ERP, site ou back-end

As duas usam os mesmos dados e a mesma separação por conta, então nada impede manter as duas ligadas ao mesmo tempo.