n8n e MCP: conectar seus workflows a um LLM local

#n8n e MCP: dois nós, dois sentidos de fluxo

O Model Context Protocol (MCP) é um protocolo aberto que descreve como uma aplicação de IA descobre e chama ferramentas fornecidas por um servidor. Se o conceito for novo para você, o guia “MCP: o que é?” apresenta os fundamentos; aqui, presume-se que você já conhece os termos cliente, servidor e ferramenta.

No n8n, o MCP aparece na forma de dois nós da família de IA (pacote n8n-nodes-langchain). Eles atendem a duas necessidades opostas, e é fácil confundir os dois ao ler os tutoriais.

MCP Server Trigger: o n8n vira servidor

O nó publica uma URL MCP. Cada ferramenta que você conecta a ele (um sub-workflow, uma requisição HTTP, uma ferramenta integrada) se torna uma ferramenta MCP que um cliente externo pode listar e chamar. Uso típico: dar ao seu assistente local acesso a “criar um ticket”, “pesquisar no CRM” ou “enviar um resumo”, sem entregar a ele suas credenciais.

MCP Client Tool: o n8n vira cliente

O nó é conectado como ferramenta sob um nó AI Agent. Ele se conecta a um servidor MCP existente, obtém a lista de ferramentas dele e as disponibiliza para o agente. Uso típico: um workflow agendado em que o agente lê arquivos, consulta um banco de dados ou pesquisa uma documentação por meio de um servidor MCP já em funcionamento.

O que o MCP não muda

A escolha do modelo continua independente. O agente do n8n pode rodar em Ollama; o cliente que chama o seu MCP Server Trigger também pode usar um modelo local. O MCP só transporta a descrição das ferramentas e as chamadas a elas, não o modelo.

Os dois nós podem coexistir na mesma instância: um workflow "servidor" que expõe algumas ações de negócio e um workflow "agente" que consome um ou mais servidores MCP. Nada impede até mesmo que um agente do n8n chame o MCP Server Trigger de outro workflow da mesma instância, o que equivale a dividir um agente grande em blocos reutilizáveis.

#Pré-requisitos

Uma instância recente do n8n

Auto-hospedada, de preferência com Docker. Os nós MCP surgiram em 2025 e evoluíram desde então (transportes, opções de autenticação): atualize o n8n e confie no que o seu editor exibe. A instalação em si é detalhada no guia do n8n com Docker.

Ollama acessível a partir do n8n

Por padrão, o Ollama escuta em http://localhost:11434. Se o n8n roda em um contêiner, localhost se refere ao contêiner, não à sua máquina: será necessário outro endereço (veja a etapa 1).

Um modelo que lida com chamadas de ferramentas

Um agente só é útil se o modelo souber gerar chamadas de ferramentas estruturadas. Escolha um modelo cuja página no Ollama indique a capacidade tools, por exemplo da família Qwen3. Em Q4_K_M, um 8B cabe em cerca de 5 GB de VRAM e um 14B em cerca de 9 GB, o que fica confortável em uma RTX 3060 de 12 GB ou uma RTX 4070 de 12 GB.

Para a etapa 2

Um servidor MCP acessível via HTTP. Os servidores executados apenas localmente via stdio (um comando npx ou uvx) não podem ser acessados diretamente pelo n8n: é preciso um servidor que escute em uma URL.

Para a etapa 4

Um cliente MCP capaz de se comunicar com um servidor remoto: LM Studio, Open WebUI, Claude Desktop por meio de um gateway ou o inspetor oficial do protocolo para testes.

#Etapa 1: um agente do n8n conectado a um modelo local

As duas direções do MCP passam por um agente, do lado do n8n ou do lado do cliente. Então, comece verificando se o n8n consegue se comunicar com o seu modelo local. A conexão básica é explicada em detalhes no guia n8n + Ollama; aqui está apenas o essencial.

# Télécharger un modèle compatible avec l'appel d'outils
ollama pull qwen3:8b

# Vérifier qu'Ollama répond et liste le modèle
curl http://localhost:11434/api/tags

Se o n8n roda no Docker e Ollama diretamente no host, adicione ao serviço n8n uma entrada que faça host.docker.internal apontar para a máquina host. No Docker Desktop (macOS, Windows), esse nome já existe; no Linux, é preciso declará-lo.

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    extra_hosts:
      - "host.docker.internal:host-gateway"

No Linux, o Ollama escuta por padrão apenas em 127.0.0.1: um contêiner não conseguirá acessá-lo via host-gateway enquanto você não definir OLLAMA_HOST=0.0.0.0 no serviço Ollama. Se os dois rodarem no mesmo arquivo Compose, use de preferência o nome do serviço, por exemplo http://ollama:11434.

1. 01
   Criar o agente

   Em um novo workflow, adicione um gatilho Chat Trigger (prático para testar) e depois um nó AI Agent.
2. 02
   Conectar o modelo

   Na entrada Chat Model do agente, adicione Ollama Chat Model. Crie a credencial Ollama com a URL base http://host.docker.internal:11434 (ou http://localhost:11434 se o n8n não estiver em contêiner) e depois selecione qwen3:8b.
3. 03
   Testar sem ferramentas

   Abra o chat do workflow e faça uma pergunta simples. Uma resposta confirma a conexão do n8n com o Ollama; o restante do guia adiciona ferramentas por cima disso.

#Etapa 2: consumir um servidor MCP a partir de um agente n8n

O nó MCP Client Tool se conecta à entrada Tool do AI Agent, como qualquer outra ferramenta. Na execução, ele consulta o servidor MCP, obtém a lista de ferramentas com suas descrições e seus esquemas de parâmetros e as apresenta ao modelo. É o modelo que decide chamar determinada ferramenta com determinados argumentos; o n8n se encarrega de repassar a chamada e devolver o resultado.

1. 01
   Adicionar o nó

   Abaixo do agente criado na etapa 1, clique no + da entrada Tool e escolha MCP Client Tool.
2. 02
   Informar o endpoint

   Cole a URL do servidor MCP e escolha o transporte oferecido por esse servidor. A documentação do n8n cita o fluxo HTTP (streamable HTTP), transporte atual do protocolo, e os Server-Sent Events (SSE), mais antigos e ainda oferecidos por alguns servidores. Se o servidor documentar uma URL terminada em /sse, geralmente é SSE; caso contrário, tente o HTTP.
3. 03
   Escolher a autenticação

   Nenhuma, Bearer (um token enviado no cabeçalho Authorization) ou um cabeçalho personalizado, conforme o que o servidor exigir. As opções exatas dependem da sua versão do n8n; o token é armazenado como uma credencial do n8n, e não em texto puro no workflow.
4. 04
   Filtrar as ferramentas

   O parâmetro Tools to Include oferece All, Selected ou All Except. Prefira Selected: um modelo local de 8B escolhe melhor entre três ferramentas bem descritas do que entre trinta, e você limita o que o agente pode acionar.
5. 05
   Testar

   Peça no chat uma ação que exija a ferramenta. No log de execução do agente, você vê a ferramenta chamada, os argumentos gerados pelo modelo e a resposta do servidor.

Lembrete prático: o n8n precisa conseguir acessar o servidor MCP. Um servidor iniciado na sua máquina no endereço localhost:3000 não é visível a partir do contêiner do n8n; a mesma regra de host.docker.internal ou nome de serviço do Docker se aplica.

#Etapa 3: expor seus workflows com o MCP Server Trigger

Essa é a direção mais procurada por trás da busca "n8n mcp": transformar automações existentes em ferramentas que um assistente pode chamar. O MCP Server Trigger é diferente dos gatilhos clássicos: ele não dispara uma sequência de nós, apenas se conecta a nós de ferramenta e os publica.

1. 01
   Criar o workflow do servidor

   Em um novo workflow, adicione o nó MCP Server Trigger. Ele exibe uma URL de teste e uma URL de produção, além de um campo Path que determina o final da URL. Substitua o identificador aleatório por um caminho legível, se quiser, mas mantenha-o difícil de adivinhar.
2. 02
   Vincular ferramentas

   Clique na entrada Tool do trigger e adicione ferramentas. A mais útil é a ferramenta que chama outro workflow do n8n (Call n8n Workflow Tool): sua automação existente se torna uma ferramenta MCP. Você também pode conectar o HTTP Request Tool ou ferramentas de integração fornecidas pelo n8n.
3. 03
   Caprichar no nome e na descrição

   O cliente vê apenas o nome da ferramenta, a descrição dela e o esquema dos parâmetros. É esse texto que o modelo lê para decidir fazer uma chamada. Escreva uma descrição explícita, em uma ou duas frases: o que a ferramenta faz, os parâmetros esperados e o que ela retorna.
4. 04
   Definir os parâmetros do sub-workflow

   No workflow chamado, declare os campos de entrada esperados (por exemplo, título e prioridade de um ticket). O cliente MCP receberá esse esquema e o modelo preencherá os valores.
5. 05
   Testar e depois ativar

   A URL de teste só responde enquanto o editor está escutando um evento de teste; as execuções então aparecem no canvas. A URL de produção só funciona depois que o workflow é ativado. Use a URL de teste para os ajustes e passe a URL de produção para seus clientes.

Test        : https://n8n.mondomaine.lan/mcp-test/<chemin>
Production  : https://n8n.mondomaine.lan/mcp/<chemin>

O endereço base é o mesmo que o n8n usa para seus webhooks. Se o n8n exibir localhost:5678 enquanto você o acessa por outro nome, corrija a variável WEBHOOK_URL da instância: é ela que determina a URL exibida no nó.

#Etapa 4: conectar um cliente MCP local ao n8n

Falta fazer com que essas ferramentas sejam chamadas por um assistente que também roda em um modelo local. Antes de qualquer cliente “inteligente”, verifique o servidor com o inspetor oficial do protocolo: ele lista as ferramentas expostas e permite chamá-las manualmente, sem nenhum modelo no circuito.

# Lance l'inspecteur MCP dans le navigateur (nécessite Node.js)
npx @modelcontextprotocol/inspector

Na interface, escolha o transporte correspondente, cole a URL de produção, adicione o cabeçalho Authorization se você tiver ativado a autenticação e, em seguida, liste as ferramentas. Se as suas ferramentas do n8n aparecerem com a descrição, o servidor está pronto.

#LM Studio e os clientes que aceitam uma URL

Os clientes recentes aceitam diretamente um servidor MCP remoto descrito por uma URL. O LM Studio, por exemplo, lê um arquivo mcp.json no formato mcpServers; uma entrada remota tem a forma abaixo. Confira na documentação do seu cliente o nome exato dos campos, que pode variar de um software para outro.

{
  "mcpServers": {
    "n8n": {
      "url": "https://n8n.mondomaine.lan/mcp/<chemin>",
      "headers": {
        "Authorization": "Bearer <votre-jeton>"
      }
    }
  }
}

#Clientes limitados a stdio: usar um gateway

Alguns clientes só conseguem iniciar servidores locais em stdio. Para esse caso, a documentação do n8n descreve o uso do gateway mcp-remote, que é iniciado como um servidor stdio e repassa as chamadas para a URL do n8n. O token é passado por uma variável de ambiente em vez de ficar fixo nos argumentos.

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://n8n.mondomaine.lan/mcp/<chemin>",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "<votre-jeton>"
      }
    }
  }
}

Do lado do modelo, valem as mesmas regras da etapa 2: carregue no seu cliente um modelo que suporte chamada de ferramentas, mantenha poucas ferramentas visíveis e teste primeiro com uma solicitação sem ambiguidade. O guia MCP e LLM local detalha a configuração do lado do cliente para o Ollama e suas interfaces.

#Proteger os endpoints MCP do n8n

Uma URL do MCP Server Trigger é um ponto de entrada que dispara seus workflows com as credenciais salvas no n8n. Qualquer pessoa que a conheça, sem autenticação, pode criar seus tickets ou ler seu CRM. Trate-a como uma chave de API.

Ativar a autenticação

O nó oferece autenticação por token Bearer ou por cabeçalho. Ative-a sempre, mesmo em uma rede local. Gere um token longo e aleatório, por exemplo com o comando openssl abaixo, e um token diferente para cada cliente, para poder revogar apenas um.

Não exponha o n8n na internet sem motivo

Para uso pessoal ou em uma equipe pequena, mantenha o n8n na rede local ou atrás de uma VPN (WireGuard, Tailscale). Se a exposição for necessária, use um proxy reverso em HTTPS, com filtragem de IP se possível.

Limitar o que cada ferramenta pode fazer

Uma ferramenta MCP deve fazer uma coisa específica com parâmetros delimitados. Evite expor uma ferramenta genérica do tipo “executar uma consulta SQL” ou “chamar uma URL qualquer”: um modelo que erre, ou um conteúdo malicioso lido pelo agente, pode desviá-la de sua finalidade.

Cuidado com a injeção de prompt

Se o agente lê conteúdos externos (e-mails, páginas web, documentos) e dispõe de ferramentas que executam ações, um texto malicioso pode ordenar que ele chame uma ferramenta. Separe as ferramentas de leitura das de ação e adicione uma validação humana (nó de espera ou de aprovação) antes de qualquer ação irreversível.

Auditar do lado do servidor MCP de terceiros

No sentido cliente, adicione a um agente apenas servidores MCP cujo desenvolvedor e código você conhece. As descrições de ferramentas fornecidas pelo servidor entram diretamente no contexto do modelo.

Monitorar as execuções

Cada chamada de ferramenta gera uma execução no n8n. Consulte regularmente o histórico do workflow servidor: ele é o seu registro de auditoria.

# Générer un jeton aléatoire de 64 caractères hexadécimaux
openssl rand -hex 32

Se houver um proxy reverso na frente do n8n, ele precisa deixar passar uma resposta em streaming. A documentação do n8n traz um exemplo de nginx que desativa o buffering para os caminhos MCP; o trecho abaixo reproduz essas diretivas, que devem ser adaptadas à sua configuração e complementadas com o caminho /mcp-test/ se você fizer testes através do proxy.

location /mcp/ {
    proxy_pass http://127.0.0.1:5678;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding off;
    gzip off;
}

#Solução de problemas do n8n MCP: os bloqueios mais comuns

O cliente não vê nenhuma ferramenta

Verifique se há ferramentas de fato conectadas à entrada Tool do MCP Server Trigger e se você está usando a URL de produção com um workflow ativado, ou a URL de teste enquanto o editor está escutando.

Erro 401 ou 403

O token não confere, ou o cliente não envia o cabeçalho. Teste com o inspetor MCP, que mostra exatamente os cabeçalhos enviados. Atenção ao espaço depois de “Bearer”.

Conexão que cai ou fica travada

Quase sempre é um proxy que faz buffer do fluxo, ou um transporte errado escolhido no cliente (SSE em vez de HTTP). Teste diretamente na porta 5678 para isolar o proxy.

A URL exibida contém localhost

A variável WEBHOOK_URL do n8n não está definida: a URL não poderá ser acessada de outra máquina. Defina-a com o endereço público ou de rede da instância e reinicie o n8n.

ECONNREFUSED para Ollama

O n8n em contêiner procura Ollama dentro do contêiner. Use host.docker.internal ou o nome do serviço Docker e verifique se Ollama escuta em uma interface acessível.

O modelo nunca chama a ferramenta

Modelo sem suporte a ferramentas, descrição de ferramenta vaga demais ou ferramentas demais expostas. Mude para um modelo marcado como tools, reescreva a descrição e reduza a seleção.

O modelo inventa parâmetros

O esquema do subworkflow está livre demais. Declare campos tipados e descreva os valores esperados; valide as entradas no workflow antes de qualquer ação.

#Para se aprofundar

Este guia aborda o MCP no n8n. Para os fundamentos do protocolo, a configuração dos clientes MCP no Ollama ou a conexão do n8n a um modelo local, estes guias dão continuidade.