Configuração do MCP

O Model Context Protocol (MCP) da Caramelo AI é um padrão aberto que permite conectar assistentes de Inteligência Artificial (como Claude Desktop, ChatGPT e Gemini) diretamente aos dados do seu projeto de forma segura e em tempo real.

Com essa integração, a IA de sua escolha ganha a capacidade de consultar e analisar métricas, leads, conversas e o desempenho de suas campanhas de forma autônoma.

🚀 Como acessar o painel MCP

1. Acesse o Painel Administrativo da Caramelo AI.
2. Navegue até o seu projeto.
3. No menu lateral, acesse Integrações.
4. No card Model Context Protocol (MCP), clique em Gerenciar.

Nesta página, você encontrará a sua URL de Conexão exclusiva do projeto, a listagem de conexões OAuth ativas e a seção Chaves de API de MCP.

[!IMPORTANT] Chaves de API exclusivas para o MCP: Para clientes que utilizam autenticação estática (como Claude Desktop ou Cursor), você deve gerar uma chave do MCP (mak_...) nesta tela. Chaves gerais de API do projeto (sak_... ou cak_...) serão rejeitadas pelo servidor MCP por motivos de segurança.

⚙️ Instruções de Configuração por Cliente

A URL de conexão do seu projeto possui o seguinte formato: https://mcp.carameloai.com/mcp/projects/<PROJECT_ID>

Parâmetros de URL Disponíveis

Para estender a compatibilidade com diferentes clientes e CLIs, você pode anexar parâmetros de consulta à URL de conexão:

• ?json=true (ou ?jsonResponse=true): Força o servidor a responder a requisições POST no formato application/json em vez de text/event-stream. Útil para clientes que não suportam a leitura de pacotes SSE nas respostas de requisições POST.
• Detecção e Suporte Automático: O servidor detecta e negocia dinamicamente conexões do padrão oficial SSE ou conexões legadas do rascunho Streamable HTTP (enviados por CLIs como agy ou clientes em Go), provendo suporte retrocompatível sob a mesma URL.

🔵 Cursor / Antigravity IDE (Conexão SSE Direta)

Se você está usando um editor ou IDE com suporte nativo a conexões MCP via SSE/HTTP (como o Cursor ou o Antigravity IDE):

1. Adicione um novo servidor MCP nas configurações da sua IDE.
2. Selecione o tipo de transporte como SSE (ou utilize a propriedade "serverUrl" no arquivo de configuração do agente).
3. Insira a sua URL de Conexão exclusiva obtida no painel: https://mcp.carameloai.com/mcp/projects/SEU_PROJECT_ID
4. Configure os cabeçalhos de autorização passando a chave mak_ gerada no painel. Exemplo no arquivo mcp_config.json:

{
  "mcpServers": {
    "caramelo-vendedor": {
      "serverUrl": "https://mcp.carameloai.com/mcp/projects/SEU_PROJECT_ID",
      "headers": {
        "Authorization": "Bearer mak_SUA_CHAVE_MCP_AQUI"
      }
    }
  }
}

🟣 Claude Desktop (Ponte de Conexão stdio via Supergateway)

Como o Claude Desktop nativamente apenas suporta servidores locais via stdio (entrada e saída padrão), você precisa utilizar uma ponte para converter a conexão SSE do nosso servidor em stdio local. Para isso, utilizamos a ferramenta supergateway informando a chave mak_ correspondente.

1. Abra ou crie o arquivo de configuração do Claude Desktop:
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
2. Insira a seguinte estrutura sob a chave mcpServers (substituindo a URL e a chave mak_ pelas suas credenciais copiadas do Dashboard):

{
	"mcpServers": {
		"caramelo-vendedor": {
			"command": "npx",
			"args": [
				"-y",
				"supergateway",
				"--sse",
				"https://mcp.carameloai.com/mcp/projects/SEU_PROJECT_ID",
				"--oauth2Bearer",
				"mak_SUA_CHAVE_MCP_AQUI"
			]
		}
	}
}

3. Reinicie o Claude Desktop. Um ícone de tomada (plug) aparecerá no chat indicando que as ferramentas foram carregadas.

🟢 ChatGPT (Custom GPTs / Connectors)

O ChatGPT suporta a integração remota com o fluxo de autorização automática (OAuth 2.1) e registro dinâmico.

1. No ChatGPT, acesse Explore GPTs -> Create GPT.
2. Na aba Configure, role até Actions e clique em Create new action.
3. Na seção de Autenticação, selecione OAuth e preencha as configurações utilizando a URL base de conexão obtida no painel. O ChatGPT fará o auto-registro (DCR) no nosso servidor.
4. Quando o usuário interagir com o Custom GPT pela primeira vez, ele será redirecionado para a tela de login e consentimento da Caramelo AI.
5. Após aprovar, a conexão será estabelecida e listada nas Conexões Ativas do seu painel.

🔵 Gemini CLI / Clientes compatíveis com SSE

Para ferramentas CLI ou clientes customizados que utilizam transporte via Server-Sent Events (SSE):

• Configure o cliente apontando para a URL de conexão HTTP do seu projeto.
• O cliente MCP receberá um desafio 401 Unauthorized com o cabeçalho WWW-Authenticate contendo as informações da tela de consentimento.
• Siga as instruções do cliente para concluir a autenticação no navegador.

📊 Ferramentas Disponíveis para a IA

Uma vez conectado, o assistente de IA poderá acionar as seguintes ferramentas (tools) quando você solicitar no chat:

📁 Projetos e Contas

• list_projects: Lista todos os projetos disponíveis na conta para localizar identificadores rapidamente.
• get_account_subscription: Recupera dados sobre o plano de assinatura atual.

👥 Clientes e Leads

• search_customers: Permite realizar pesquisas textuais de contatos na base de clientes (nome, e-mail, telefone, etc.).
• get_lead_funnel: Exibe a distribuição dos leads nas etapas do funil de vendas (CRM).
• get_funnel_transitions: Retorna taxas de conversão e duração média dos leads em cada estágio do pipeline de vendas.

📈 Métricas e Desempenho

• get_chatbot_metrics: Retorna métricas agregadas de performance do chatbot (taxas de conversão, transbordo para humanos, custos e sentimentos).
• get_live_metrics: Obtém métricas em tempo real das interações e mensagens nas últimas horas (conversas ativas, fila de espera, transbordos).
• get_daily_usage: Apresenta o consumo diário de recursos e tokens no projeto para acompanhamento de limites.
• get_usage_insights: Fornece insights consolidados de volumetria de uso na conta (tokens consumidos, chamadas de API, tarefas, etc.).

💬 Conversas e Atendimento

• list_chatbots: Lista todos os chatbots configurados no projeto.
• read_conversation: Permite à IA visualizar o histórico completo de mensagens de uma conversa específica para analisar o contexto do atendimento.
• list_conversations: Lista as conversas (threads) do projeto com suporte a filtros de status, sentimento, etc.
• get_failed_conversations: Identifica e lista conversas com baixo engajamento, sentimento negativo ou insatisfação dos usuários.

🔧 Diagnósticos e Logs (v1.2)

• get_chatbot: Obtém a configuração detalhada de prompts, personas e ferramentas de um chatbot.
• get_tool_execution_logs: Recupera os logs de chamadas de ferramentas e APIs do chatbot para diagnóstico de falhas de integração.
• get_nlp_insights: Retorna insights de clusters de intenções e perguntas não respondidas pelos chatbots.

🤖 Ciclo de Vida do Chatbot (Mutação - v1.3)

• create_chatbot: Cria um novo chatbot no projeto com uma versão de rascunho inicial.
• get_chatbot_draft: Obtém a configuração do rascunho atual de um chatbot.
• edit_chatbot_draft: Permite editar propriedades de configuração do rascunho de um chatbot.
• generate_chatbot_test_url: Cria uma URL temporária para testar e pré-visualizar o rascunho do chatbot.
• publish_chatbot_draft: Promove o rascunho do chatbot para produção, gerando uma nova versão ativa.

🔒 Segurança e Controle

[!IMPORTANT] Isolamento de Dados: Cada conexão é estritamente vinculada ao projeto selecionado. O assistente não consegue visualizar dados de outros projetos sem uma nova autorização explícita.

[!TIP] Revogação Instantânea: Se você perder o acesso ao dispositivo ou quiser encerrar a conexão de um assistente de IA, vá para a seção Conexões Ativas na página do MCP no painel e clique em Revogar ao lado da conexão correspondente. O token será invalidado na mesma hora.

[!WARNING] Limites de Requisição (Rate Limiting): Para garantir a estabilidade da plataforma, cada projeto possui um limite de 30 requisições por minuto ao servidor MCP.

🙋 Perguntas Frequentes (FAQ)