n8n MCP: escolha uma rota e teste uma tarefa de CRM

n8n MCP pode significar um cliente de IA chamando o n8n ou um workflow do n8n chamando as ferramentas de outro aplicativo. Para uma consulta de cliente e uma tarefa interna no Customermates, a segunda direção serve: o exemplo testado abaixo usa o MCP Client independente do n8n, sem modelo de linguagem.

MCP é o protocolo de conexão; o n8n é o aplicativo de workflows. Comece pela direção da chamada e só depois escolha o nó ou o servidor. O guia de workflows do n8n para iniciantes cobre o editor visual; este guia cobre a escolha do MCP e uma rota datada, que foi executada.

O que é MCP no n8n?

MCP é a sigla de Model Context Protocol, um protocolo aberto que permite a um aplicativo de IA descobrir e chamar as ferramentas de um servidor. No n8n, ele aparece de quatro formas: o n8n como servidor para um cliente de IA (acesso no nível da instância ou o nó MCP Server Trigger), o n8n como cliente de outro servidor (o MCP Client Tool de um agente e o MCP Client independente) e projetos da comunidade ao redor disso. Para a base do protocolo, veja o que é um servidor MCP; para a diferença em relação a uma API comum, MCP vs API.

Qual rota do n8n MCP combina com o seu trabalho?

A tabela separa quem mantém a rota de quem tem as credenciais que autorizam o trabalho. Um nome de produto conhecido não basta para identificar uma conexão.

A documentação oficial do MCP no nível da instância distingue o acesso à instância do Server Trigger de um workflow. Ativar o MCP não expõe todos os workflows. A visibilidade segue o acesso do usuário e as configurações de exposição ao MCP. A referência de ferramentas inclui a criação e a edição de workflows e de tabelas de dados. Descrever o servidor oficial de hoje como "só executa" é incompleto.

A referência do MCP Server Trigger descreve um ponto de entrada de servidor. A referência do MCP Client Tool descreve as ferramentas externas de um agente. A referência do MCP Client independente cobre chamadas explícitas em um workflow normal.

O repositório n8n-mcp, independente, oferece ajuda para montar workflows. É um projeto à parte, não o nome de todos os recursos MCP nativos. Você não precisa instalá-lo para a receita do cliente independente abaixo.

Como habilitar o MCP no n8n e conectar um cliente de IA?

Esta é a rota em que o n8n é o servidor e um cliente de IA, como o Claude ou o Cursor, é quem chama. Ela não foi executada neste guia: o exemplo testado abaixo é a rota inversa. O que segue é um mapa da documentação oficial, na ordem em que costuma ser útil lê-la.

Um cliente de IA conectado vê apenas o que o usuário autorizado pode acessar e o que foi exposto ao MCP. Antes de ligar o recurso em uma instância com workflows de produção, teste em uma instância descartável e revise o que cada workflow exposto é capaz de alterar. O repositório da comunidade é outra rota, voltada a ajudar um cliente de programação a montar workflows; fixe a versão dele e trate-o como um projeto à parte.

O que exatamente foi executado, e em quais versões?

Executado em 28 de outubro de 2026, das 23:10:03 às 23:10:15 UTC: um workflow manual no n8n 2.45.5, com @n8n/n8n-nodes-langchain.mcpClient typeVersion 1.1. A imagem foi fixada neste digest:

docker.n8n.io/n8nio/n8n@sha256:9f6d0a5987ab5a297c4b0b38fbf1a22285dd1364551478e93f03d506908fa74c

A fonte do Customermates era 86212781f845d0ccdc1dfa3ddd78fa38fa2b8912. Todos os registros eram fictícios, em um banco local isolado. Um relay somente em loopback entregou, em memória, uma chave de API descartável a /api/v1/mcp. Não houve conta externa, chamada a modelo nem envio de mensagem.

Esta é uma receita para exatamente essa rota e essa sintaxe testadas, revisada em 5 de novembro de 2026. Não é uma nova execução do n8n nessa data. A configuração de autenticação do relay, os IDs fixos da fixture e a revisão do esquema são específicos do teste. OAuth, n8n Cloud, agendamentos, Server Trigger e a escolha de ferramentas pelo AI Agent não foram testados.

Como montar o workflow manual de cinco chamadas?

Crie um Manual Trigger seguido de cinco nós MCP Client independentes, ligados pelas saídas normais. Mantenha o workflow sem publicar enquanto valida uma tarefa interna em um espaço de trabalho descartável. O diagrama mostra a sequência executada, incluindo a requisição duplicada de propósito:

Manual Trigger
  → get_workspace_context
  → get_record_model
  → query_crm_records
  → mutate_crm_record
  → mutate_crm_record (identical payload and key)

No workflow preservado, cada nó cliente usou o seguinte formato de parâmetros. É o endereço histórico do relay local, não um endpoint público nem uma configuração de CRM sem autenticação:

{
  "serverTransport": "httpStreamable",
  "endpointUrl": "http://127.0.0.1:4053/mcp",
  "authentication": "none",
  "tool": {
    "__rl": true,
    "value": "get_workspace_context",
    "mode": "id"
  },
  "inputMode": "json",
  "jsonInput": {},
  "options": {
    "timeout": 60000,
    "convertToBinary": false
  }
}

Em cada nó seguinte, troque tool.value e jsonInput conforme os passos abaixo; mantenha Streamable HTTP, a entrada JSON e o timeout de 60 segundos. A sequência fixa não mapeia dinamicamente os resultados da descoberta para os nós seguintes.

1. Confirme o espaço de trabalho. Chame get_workspace_context com {}. Confira o usuário e o espaço de trabalho retornados antes de permitir uma escrita.
2. Leia o esquema. Chame get_record_model com {}. O ambiente de teste já tinha resolvido os tipos Task e Organization, os campos principais e a relação de saída antes de montar o workflow. A mutação registrada usou a revisão de configuração 2.
3. Encontre o cliente. Chame query_crm_records com o JSON registrado abaixo. No seu espaço de trabalho, resolva os IDs de novo e confira o resultado antes de escolher um cliente. A referência de registro conhecida da fixture foi fixada no nó seguinte; este não foi um teste de correspondência automática de entidades.

{
  "typeId": "51d5e8d2-9468-8718-852d-aad6d1964282",
  "fields": [
    "b8b511f4-5de8-81ce-887f-880d80b0062c"
  ],
  "search": "Example organization",
  "page": 1,
  "pageSize": 25
}

4. Crie a tarefa interna. Chame mutate_crm_record com este payload registrado, exatamente como está. Todo UUID é um identificador de fixture, inclusive o do usuário atribuído. A relação liga a tarefa à organização fictícia; ela não envia nada a essa organização.

{
  "expectedRevision": 2,
  "idempotencyKey": "seo-run340-n8n-mcp-manual-next-task-v1",
  "mutation": {
    "action": "create",
    "typeId": "0d70aff9-0fa9-8ce2-8e75-8bdddf0fdfd1",
    "assignedUserIds": [
      "eed148ca-b816-4db2-acac-186ca6f03043"
    ],
    "fields": [
      {
        "fieldId": "02960cb0-8976-81b2-82ce-6194a5bc90e3",
        "value": {
          "kind": "text",
          "value": "Fictional n8n manual proof: check the handover field list"
        }
      }
    ],
    "links": [
      {
        "relationId": "2f82adb2-ca57-8190-85ae-230cde69ff06",
        "direction": "outgoing",
        "record": {
          "typeId": "51d5e8d2-9468-8718-852d-aad6d1964282",
          "recordId": "16d88ab1-a440-4e42-b698-99a284940191"
        }
      }
    ]
  }
}

5. Repita a requisição idêntica. O último nó usou os mesmos argumentos de mutate_crm_record, um JSON equivalente byte a byte e a mesma chave de idempotência. Uma nova tentativa para o mesmo evento de negócio precisa manter o payload e a chave. Um evento ou payload diferente precisa de uma chave nova.

O teste original importou o workflow de ID seoRun340McpProof e o executou por ID dentro do runtime fixado:

n8n import:workflow --input /proof/workflow.json
n8n execute --id seoRun340McpProof --rawOutput

Esses comandos pressupõem que o workflow preservado e o relay já existem. Uma tentativa anterior com execute --file retornou código de saída zero sem executar o workflow. O teste a rejeitou porque nenhuma chamada de ferramenta tinha ocorrido. Um código de saída ou um arquivo JSON importável, sozinhos, não provam que a conexão funciona.

Que resultado você deve verificar antes de adaptar?

A execução corrigida registrou cinco chamadas de ferramenta realmente originadas no n8n: três leituras e duas mutações idênticas. A importação e a execução terminaram com sucesso. Depois, uma releitura separada pelo SDK verificou a tarefa 8f3bd9eb-0696-4505-9c09-e12620648cc1 na versão 1, com o responsável atribuído e a relação com o cliente intactos. O ambiente de teste também repetiu a mutação pelo SDK. A releitura ficou fora do workflow de cinco nós.

Um teste de produto separado, de 5 de novembro de 2026, na fonte 111f8a2e33f39975955e8f49d3f7c898fbbd3d05, exercitou leituras e escritas REST e MCP, repetição idempotente e uma recusa de permissão. O cliente MCP dele era o SDK 1.24.0, não o n8n. Ele sustenta essas observações atuais do produto; não atualiza o resultado datado de compatibilidade com o n8n.

Como diferem as credenciais e a configuração de produção?

Para uma conexão direta com o Customermates, use <BASE_URL>/api/v1/mcp e uma credencial Header Auth do n8n cujo nome de cabeçalho seja x-api-key. Guarde a chave nas credenciais, nunca no JSON exportado do workflow. O guia de chaves de API do Customermates explica o vínculo com o espaço de trabalho e as permissões herdadas do usuário. O Header Auth direto é uma configuração documentada; a execução preservada no n8n usou o relay.

Consulte o contrato MCP do Customermates para ver as ferramentas e os esquemas atuais. Troque os IDs da fixture e a revisão por valores do seu espaço de trabalho, adicione uma verificação de que a correspondência do cliente é inequívoca e releia a tarefa resultante. Inspecione os erros das ferramentas, e não só o status do workflow. Não transforme uma escrita que falhou em uma nova chave de idempotência sem entender o resultado.

Um cliente MCP externo age como o usuário conectado. As instruções de perguntar antes de enviar ou excluir são orientação para o cliente, não uma barreira de aprovação imposta pelo servidor. Implemente a sua própria etapa de revisão para ações que tenham consequências. A política de aprovação do Mate é separada; este workflow não aciona o Mate nem comprova um processo de aprovação.

Se a sua tarefa é uma sincronização fixa de CRM, o guia de integração do Customermates com o n8n pode ser mais simples: o community node @customermates/n8n-nodes-crm v2, separado, usa a API genérica de registros. Os workflows da v1 apontam para endpoints removidos. REST e webhooks também são opções; compare os contratos em MCP vs API.

O Customermates com hospedagem própria fornece o núcleo do CRM Starter, REST e acesso MCP externo. O Mate hospedado e a caixa de entrada na nuvem não estão incluídos. O Customermates não inclui um runtime nem uma assinatura do n8n, n8n hospedado gratuito ou sequências de envio. Se você só precisa conectar um CRM que já tem, o Customermates não é um intermediário obrigatório.

Um workflow como este cria o próximo passo. A resposta ao cliente é a outra metade: com LinkedIn e e-mail conectados no Customermates Cloud a partir do Pro, a conversa fica no registro do cliente, e o Mate ou o seu próprio agente de IA redige a resposta para você revisar e enviar. Para ver os dois juntos, comece seu teste: 14 dias de Pro sem cartão de crédito.

Perguntas frequentes

Documentação de terceiros verificada em 5 de novembro de 2026 nas referências oficiais do n8n e no repositório da comunidade linkados acima. O exemplo executado no n8n continua datado de 28 de outubro de 2026.