MCP Integration

O protocolo MCP permite que LLMs como Claude e ChatGPT usem ferramentas externas. Com z-mcp, você conecta seu WhatsApp direto na conversa.

O que é MCP?

MCP (Model Context Protocol) é o padrão criado pela Anthropic para permitir que modelos de linguagem interajam com ferramentas externas. Pense como uma forma de dar “superpoderes” ao Claude: ele pode enviar mensagens, buscar informações, cruzar contexto de conversas e muito mais.

O z-mcp implementa esse protocolo como servidor MCP remoto, transporte Streamable HTTP, em https://<sua-instancia>.zmcp.me/api/mcp. O endpoint antigo /api/mcp/sse foi descontinuado e responde 410. Você controla suas conversas pelo Claude, ChatGPT, Claude Code, Cursor ou qualquer outro cliente MCP... tudo na nuvem, sem instalar nada.

100% Cloud

Não precisa instalar nada no seu computador. O cliente MCP fala direto com sua instância z-mcp na nuvem.

3 formas de autenticar

A instância aceita a chave zmcp_... de três jeitos. Use header sempre que o cliente permitir:

MétodoExemploQuando usar
X-API-KeyX-API-Key: zmcp_sua-api-keyRecomendado. Funciona em Claude Code, Cursor, Windsurf e qualquer cliente que aceite headers customizados.
Authorization: BearerAuthorization: Bearer zmcp_sua-api-keyAlternativa equivalente, para clientes que só falam Bearer.
?key= na URL?key=zmcp_sua-api-keySó para cliente sem campo de header (ex.: ChatGPT). A chave aparece em log de acesso; trate a URL como senha.

Ferramentas disponíveis

Depois de configurar, estas ferramentas ficam disponíveis na conversa:

FerramentaDescriçãoParâmetrosEscopos
send_whatsapp_messageEnvia mensagem de texto para um contato ou grupo.to, messagefull, send_only
get_recent_messagesMensagens recentes de todos os chats ou de um só, com paginação por data.start_date, end_date, chat_id (opcional), limitfull, read_only
get_chat_historyHistórico de uma conversa específica, reunindo aliases do mesmo contato.chat_id, período (opcional)full, read_only
get_messageTexto completo de uma mensagem, útil quando o conteúdo vem truncado.chat_id, message_idfull, read_only
search_contactsBusca contatos e chats por nome ou telefone.queryfull, read_only
get_whatsapp_statusInforma se o WhatsApp da instância está conectado.(nenhum)full, read_only, send_only
get_response_metricsMédia, mediana e p90 de tempo de resposta num período, com comparação mensal.start_date, end_datefull, read_only
get_attention_chatsLista conversas esperando resposta, ordenadas por atraso.start_date, end_datefull, read_only
get_contact_contextResolve contato e aliases para cruzar com reuniões no Grilo conectado.chat_idfull, read_only

Cada chave de API tem um escopo: full chama tudo, read_only chama tudo menos send_whatsapp_message, e send_only só envia mensagem e checa status.

Configurando no Claude (claude.ai e Claude Desktop)

1. Gere uma API key

Na sua instância, abra a aba Conectar e crie uma chave. Ela aparece uma única vez, no formato zmcp_....

2. Adicione o conector personalizado

No Claude, vá em Configurações > Conectores > Adicionar conector personalizado. Nome: z-MCP. URL do servidor, sem a chave:

URL do conectortext
https://sua-instancia.zmcp.me/api/mcp

Em Authentication, escolha “No sign-in”. Em Request headers, clique em Add header e informe X-API-Key com sua chave. Salve.

3. Ative numa conversa

Abra uma conversa nova, clique no menu de ferramentas e ligue o conector z-MCP. As ferramentas de WhatsApp ficam disponíveis na hora.

Não use o claude_desktop_config.json

Esse arquivo só aceita servidores locais (command e args) e rejeita entradas com URL. Conector remoto entra pela tela de Conectores, tanto no claude.ai quanto no app Claude Desktop. O plano Free permite 1 conector personalizado.

ChatGPT

Em Plugins > Adicionar > Criar aplicativo MCP, dê o nome z-mcp. O ChatGPT não tem campo de header, então cole a URL com a chave em URL do servidor e escolha “Sem autenticação”. Depois, numa conversa, escolha o z-mcp no botão +:

URL do conector (ChatGPT)text
https://sua-instancia.zmcp.me/api/mcp?key=zmcp_sua-api-key

Depende do plano

A opção Criar aplicativo MCP só aparece em determinados planos do ChatGPT.

Prefere Actions clássicas em vez de MCP? A instância também expõe uma especificação OpenAPI compatível em /api/mcp/openapi-actions, para montar um GPT customizado com autenticação por X-API-Key.

Outros clientes MCP

O z-mcp funciona com qualquer cliente que suporte servidor MCP remoto por URL (Streamable HTTP). Claude Code:

terminalbash
claude mcp add --transport http zmcp "https://sua-instancia.zmcp.me/api/mcp" --header "X-API-Key: zmcp_sua-api-key"

Cursor, Windsurf e outros que usam um mcp.json:

mcp.jsonjson
{
  "mcpServers": {
    "zmcp": {
      "url": "https://sua-instancia.zmcp.me/api/mcp",
      "headers": {
        "X-API-Key": "zmcp_sua-api-key"
      }
    }
  }
}

Pra conferir que o servidor responde, um curl listando as ferramentas:

terminalbash
curl -s -X POST "https://sua-instancia.zmcp.me/api/mcp" \
  -H "X-API-Key: zmcp_sua-api-key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Dica

Combine ferramentas para automações poderosas. Por exemplo: “Busque todas as mensagens sobre fatura do último mês e resuma em um relatório.”

Vantagens do z-mcp Cloud

  • Sem instalação - Tudo funciona como conector remoto
  • Sempre atualizado - Novas features automaticamente
  • Multi-dispositivo - Use em qualquer computador
  • Seguro - Conexão criptografada, API key única por instância