Acessando o servidor MCP do n8n

Conecte clientes MCP compatíveis ao seu fluxo de trabalho do n8n por meio do servidor MCP integrado ao n8n.

Esse servidor permite que clientes como Lovable ou Claude Desktop se conectem com segurança à sua instância do n8n. Após a conexão, esses clientes podem:

• Pesquisar em fluxos de trabalho marcados como disponíveis para MCP
• Obter metadados e informações de gatilho dos fluxos de trabalho
• Disparar e executar fluxos de trabalho expostos ao MCP

Diferença entre acesso MCP no nível da instância e o nó MCP Server Trigger

O acesso MCP no nível da instância permite criar uma única conexão por instância do n8n, usando autenticação centralizada, e escolher quais fluxos de trabalho podem ser acessados. Os fluxos de trabalho habilitados podem ser facilmente encontrados e executados sem necessidade de configuração individual por fluxo.

Por outro lado, o nó MCP Server Trigger é configurado dentro de um único fluxo de trabalho. Esse nó expõe apenas as ferramentas desse fluxo específico para o MCP, sendo útil quando você deseja personalizar o comportamento do servidor MCP dentro de um fluxo específico.

Considerações importantes ao usar o acesso MCP no nível da instância

• Não é uma forma de criar ou editar fluxos de trabalho por meio de clientes de IA; a criação de fluxos continua sendo feita diretamente no n8n.
• Não expõe automaticamente todos os fluxos de trabalho da instância; você precisa primeiro habilitar o MCP no nível da instância e, em seguida, habilitar cada fluxo de trabalho individualmente.
• Não há escopo por cliente MCP; qualquer cliente conectado poderá ver todos os fluxos de trabalho que você habilitou para acesso MCP.

Habilitando o acesso MCP

Para instâncias Cloud e autohospedadas

1. Navegue até Configurações > MCP no nível da instância
2. Ative a opção Habilitar acesso MCP (requer permissões de proprietário ou administrador da instância).

Após habilitar, você verá:

1. Lista de fluxos de trabalho disponibilizados para clientes MCP
2. Lista de clientes OAuth conectados
3. Chave principal do MCP para habilitar/desabilitar o acesso no nível da instância
4. Botão Detalhes da conexão, que exibe instruções detalhadas para conectar clientes MCP

Para desabilitar: Basta desativar a chave principal do MCP.

Para usuários autohospedados: desabilitação completa

Para remover completamente essa funcionalidade, defina a seguinte variável de ambiente:

N8N_DISABLED_MODULES=mcp

Essa ação remove os endpoints MCP e oculta todos os elementos da interface relacionados.

Configurando a autenticação MCP

O menu suspenso Detalhes da conexão oferece duas opções de autenticação para clientes MCP:

• OAuth2
• Token de acesso (Access Token)

Usando OAuth2

Copie a URL do servidor da sua instância na aba OAuth e use-a para configurar seu cliente MCP. Após a conexão, o cliente redirecionará você ao n8n para autorização.

Revogando o acesso do cliente

Para revogar o acesso de um cliente MCP já conectado:

1. Navegue até Configurações > MCP no nível da instância.
2. Alterne para a aba Clientes conectados para ver a tabela de clientes OAuth conectados.
3. Use o menu de ações em cada linha do cliente para revogar o acesso específico.

Usando token de acesso

Use a URL do seu servidor de instância juntamente com o token de acesso MCP pessoal obtido na aba Token de acesso do menu Detalhes da conexão.

Na primeira vez que você acessar a página de acesso MCP, o n8n gerará automaticamente um token de acesso MCP pessoal vinculado à sua conta de usuário.

Atenção: Copie imediatamente seu token. Em acessos futuros, você verá apenas um valor mascarado e o botão de cópia será desabilitado.

Rotacionando o token

Se você perder o token ou precisar rotacioná-lo:

1. Navegue até Configurações > MCP no nível da instância.
2. Clique no botão no canto superior direito para abrir o menu Detalhes da conexão.
3. Alterne para a aba Token de acesso.
4. Use o botão ao lado do valor mascarado para gerar um novo token.

Ao gerar um novo token, o n8n revoga automaticamente o token anterior.

5. Atualize todos os clientes MCP conectados com o novo valor.

Disponibilizando fluxos de trabalho para clientes MCP

Requisitos de elegibilidade do fluxo de trabalho

Para que um fluxo de trabalho possa ser acessado por clientes MCP, ele deve atender aos seguintes critérios:

1. Estar publicado
2. Conter um dos seguintes nós de gatilho:
   • Webhook
   • Schedule (agendamento)
   • Chat
   • Form (formulário)

Por padrão, nenhum fluxo de trabalho está visível para clientes MCP. Você deve habilitar explicitamente o acesso para cada fluxo de trabalho elegível que deseja disponibilizar.

Ao avaliar a elegibilidade do fluxo de trabalho, o n8n considera apenas a versão publicada. Se você adicionar um gatilho compatível na versão rascunho de um fluxo, ele só será considerado elegível após a publicação dessa versão.

Atenção: Quando um fluxo de trabalho é despublicado, o n8n remove automaticamente seu acesso MCP. Ao republicar o fluxo, você precisará reabilitar o acesso manualmente.

Habilitando o acesso

Método 1: Pela página de configurações MCP (disponível no n8n v2.2.0 e superior)

1. Clique no botão Habilitar fluxo de trabalho (exibido no cabeçalho da tabela de fluxos ou quando a tabela está vazia)
2. Pesquise o fluxo de trabalho desejado (por nome ou descrição) e selecione-o na lista
3. Clique no botão Habilitar para confirmar

Método 2: Pelo editor de fluxos de trabalho

1. Abra o fluxo de trabalho.
2. Clique no menu principal do fluxo de trabalho (...) no canto superior direito.
3. Selecione Configurações.
4. Ative a opção Disponível no MCP.

Método 3: Pela lista de fluxos de trabalho

1. Vá para Fluxos de trabalho.
2. Abra o menu no cartão do fluxo de trabalho.
3. Selecione Habilitar acesso MCP.

Gerenciando permissões de acesso

A página de configurações MCP no nível da instância exibe todos os fluxos de trabalho disponíveis para clientes MCP. A partir dessa lista, você pode:

• Abrir diretamente o fluxo de trabalho, seu projeto ou pasta pai
• Usar o menu de ações para revogar o acesso (ou usar a opção Desabilitar acesso MCP no menu do cartão do fluxo)
• Usar o menu de ações para atualizar a descrição do fluxo (ou usar o menu no editor de fluxos)
• Usar o botão Habilitar fluxo de trabalho para disponibilizar mais fluxos (disponível no n8n v2.2.0 e superior)

Descrição do fluxo de trabalho

Para ajudar os clientes MCP a identificar os fluxos de trabalho, você pode adicionar uma descrição em texto livre da seguinte forma:

1. Método 1: Pela página MCP no nível da instância

   1. Navegue até Configurações > MCP no nível da instância.
   2. Certifique-se de estar na aba Fluxos de trabalho.
   3. Use o menu de ações na linha do fluxo de trabalho desejado e selecione Editar descrição.
   4. Ou clique diretamente no texto da descrição para abrir o diálogo de edição.

2. Método 2: Pelo editor de fluxos de trabalho

   1. Abra o fluxo de trabalho.
   2. Clique no menu principal do fluxo de trabalho (...) no canto superior direito.
   3. Selecione Editar descrição.

Executando fluxos de trabalho por meio de clientes MCP

Clientes MCP podem executar fluxos de trabalho elegíveis conforme solicitado. Quando um cliente dispara um fluxo de trabalho, ele é executado normalmente no n8n, e você pode monitorar sua execução na lista de Execuções. Após a conclusão, o cliente MCP recebe os resultados.

Fornecendo dados de entrada

Clientes MCP geralmente conseguem avaliar as entradas necessárias para o fluxo de trabalho. Se você tiver um gatilho Webhook e perceber que o cliente tem dificuldade para determinar as entradas corretas, recomenda-se fornecer essas informações na descrição do fluxo de trabalho.

Tempo limite do fluxo de trabalho

O n8n impõe um tempo limite de 5 minutos para execuções de fluxos de trabalho disparadas por clientes MCP. Se o fluxo não for concluído dentro desse período, o n8n interromperá a execução e enviará um erro ao cliente MCP, ignorando qualquer tempo limite configurado nas configurações do fluxo para execuções MCP.

Limitações

• Se um fluxo de trabalho tiver múltiplos gatilhos compatíveis, o cliente MCP poderá usar apenas um deles (geralmente o primeiro) para disparar o fluxo.
• Não há suporte para execução de fluxos com formulários de múltiplas etapas ou qualquer tipo de fluxo interativo que exija intervenção humana.
• Não há suporte para dados binários de entrada; clientes MCP só podem fornecer entradas baseadas em texto para os fluxos de trabalho.

Exemplos

Conectando o Lovable ao servidor MCP do n8n

1. Configure o servidor MCP no Lovable (OAuth).
   • Navegue até Configurações > Integrações da sua área de trabalho.
   • Na seção Servidores MCP, encontre o n8n e clique em Conectar.
   • Insira a URL do seu servidor n8n (exibida na página Acesso MCP).
   • Salve a conexão. Se bem-sucedida, o n8n redirecionará você para autorizar o Lovable.
2. Verifique a conexão.
   • Após a conexão, o Lovable poderá consultar fluxos de trabalho com acesso MCP habilitado.
   • Exemplo: Peça ao Lovable para construir uma interface que liste usuários e permita excluí-los.

Conectando o Claude Desktop ao servidor MCP do n8n

Usando OAuth2

1. No Claude Desktop, navegue até Configurações > Conectores.
2. Clique em Adicionar conector personalizado.
3. Insira as seguintes informações:
   • Nome: n8n MCP
   • URL do servidor MCP remoto: Sua URL base do n8n (exibida na página MCP no nível da instância)
4. Salve o conector.
5. Quando solicitado, autorize o Claude Desktop a acessar sua instância do n8n.

Usando token de acesso

Atenção: Esta operação requer a versão mais recente do Node.js.

Adicione a seguinte entrada ao seu arquivo claude_desktop_config.json:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--streamableHttp",
        "https://<YOUR_N8N_HOST>/mcp-server/http",
        "--header",
        "authorization: Bearer <YOUR_TOKEN>"
      ]
    }
  }
}

Substitua:

• <YOUR_N8N_HOST>: Sua URL base do n8n (exibida na página MCP no nível da instância)
• <YOUR_TOKEN>: Seu token gerado

Conectando o Claude Code ao servidor MCP do n8n

Use o seguinte comando CLI:

claude mcp add --transport http n8n-mcp https://<YOUR_N8N_HOST>/mcp-server/http \
  --header "Authorization: Bearer <YOUR_TOKEN>"

Ou adicione a seguinte entrada ao seu arquivo claude.json (substituindo os mesmos valores conforme explicado acima).

Conectando o Codex CLI ao servidor MCP do n8n

Adicione a seguinte entrada ao seu arquivo ~/.codex/config.toml:

[mcp_servers.n8n_mcp]
command = "npx"
args = [
    "-y",
    "supergateway",
    "--streamableHttp",
    "https://<YOUR_N8N_HOST>/mcp-server/http",
    "--header",
    "authorization: Bearer <YOUR_TOKEN>"
]

(Substitua os placeholders pela sua URL base do n8n e pelo token gerado.)

Conectando um agente Google ADK ao servidor MCP do n8n

Abaixo está um exemplo de código para criar um agente que se conecta a um servidor MCP remoto do n8n:

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPServerParams

N8N_INSTANCE_URL = "https://localhost:5678"
N8N_MCP_TOKEN = "YOUR_N8N_MCP_TOKEN"

root_agent = Agent(
    model="gemini-2.5-pro",
    name="n8n_agent",
    instruction="Help users manage and execute workflows in n8n",
    tools=[
        McpToolset(
            connection_params=StreamableHTTPServerParams(
                url=f"{N8N_INSTANCE_URL}/mcp-server/http",
                headers={"Authorization": f"Bearer {N8N_MCP_TOKEN}"},
            ),
        )
    ],
)

Para mais detalhes, consulte Connect ADK agent to n8n.

Solução de problemas

Se você encontrar problemas ao conectar clientes MCP à sua instância do n8n, considere os seguintes pontos:

• Se estiver usando um cliente MCP baseado em nuvem, certifique-se de que sua instância do n8n seja acessível publicamente.
• Verifique se o acesso MCP está habilitado nas configurações do n8n.
• Confirme se o fluxo de trabalho que deseja acessar está marcado como disponível no MCP.
• Verifique se o método de autenticação no cliente MCP (OAuth2 ou token de acesso) está configurado corretamente.
• Consulte os logs do servidor n8n em busca de mensagens de erro relacionadas à conexão MCP.
• Se estiver usando um cliente MCP desktop, certifique-se de ter instalado a versão mais recente do Node.js.