Acessar o servidor MCP do n8n

Conecte clientes MCP compatíveis aos seus workflows do n8n por meio do servidor MCP integrado do n8n.

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

• pesquisar workflows marcados como disponíveis para MCP
• obter metadados e informações de gatilho dos workflows
• acionar e executar workflows com acesso habilitado

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

O acesso MCP em nível de instância permite criar uma conexão por instância do n8n, usando autenticação centralizada e permitindo selecionar quais workflows podem ser acessados. Os workflows habilitados podem ser encontrados e executados facilmente, sem precisar configurar o MCP separadamente em cada workflow.

Em contraste, o nó MCP Server Trigger é configurado dentro de um único workflow. Esse nó expõe ao MCP apenas as ferramentas daquele workflow, o que é útil quando você quer personalizar um comportamento específico do servidor MCP dentro de um workflow.

Observações importantes ao usar o acesso MCP em nível de instância

• Isso não é uma forma de criar ou editar workflows por meio de um cliente de IA; a criação dos workflows continua sendo feita no n8n.
• Isso não expõe todos os workflows da instância. Primeiro, você precisa habilitar o MCP no nível da instância e, depois, habilitar cada workflow individualmente.
• O escopo não é separado por cliente MCP: qualquer cliente conectado poderá ver todos os workflows que você habilitou para acesso via MCP.

Habilitar acesso MCP

Para instâncias Cloud e auto-hospedadas

1. Vá para Configurações > MCP em nível de instância
2. Ative Habilitar acesso MCP (requer permissão de proprietário da instância ou administrador).

Depois de habilitar, você verá:

1. uma lista de workflows disponibilizados a clientes MCP
2. uma lista de clientes OAuth conectados
3. o interruptor principal do MCP para ativar/desativar o acesso em nível de instância
4. o botão Detalhes da conexão, que mostra instruções detalhadas para conectar um cliente MCP

Desativar: basta desligar o interruptor principal do MCP.

Para usuários auto-hospedados: desativar completamente

Para remover esse recurso por completo, defina a seguinte variável de ambiente:

N8N_DISABLED_MODULES=mcp

Isso removerá o endpoint MCP e ocultará todos os elementos da interface relacionados.

Configurar autenticação MCP

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

• OAuth2
• Token de acesso (Access Token)

Usar 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ê para o n8n para autorizar o acesso.

Revogar acesso de um cliente

Para revogar o acesso de um cliente MCP conectado:

1. Vá para Configurações > MCP em nível de instância.
2. Mude para a aba Clientes conectados; você verá uma tabela com os clientes OAuth conectados.
3. Use o menu de ações em cada linha para revogar o acesso do cliente desejado.

Usar token de acesso

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

Ao acessar a página de acesso MCP pela primeira vez, o n8n gera automaticamente para sua conta um token pessoal de acesso MCP associado à sua conta de usuário.

Observação

Copie seu token imediatamente. Nas próximas visitas, você verá apenas o valor mascarado, e o botão de cópia ficará desativado.

Renovar o token

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

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

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

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

Disponibilizar workflows para clientes MCP

Requisitos de elegibilidade do workflow

Para que um workflow possa ser acessado por um cliente MCP, ele deve atender aos seguintes requisitos:

1. estar publicado
2. conter um dos seguintes nós de gatilho:
   • Webhook
   • Schedule
   • Chat
   • Form

Por padrão, nenhum workflow fica visível para clientes MCP. Você deve habilitar explicitamente o acesso para cada workflow elegível que quiser expor.

Ao avaliar a elegibilidade do workflow, o n8n considera apenas a versão publicada. Se um gatilho compatível for adicionado à versão de rascunho de um workflow, ele não será considerado elegível até que essa versão seja publicada.

Observação

Quando um workflow deixa de estar publicado, o n8n remove sua permissão de acesso MCP. Ao publicar novamente o workflow, você precisará habilitar o acesso novamente.

Habilitar acesso

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

1. Clique no botão Habilitar workflow (mostrado no cabeçalho da tabela ou quando a tabela estiver vazia)
2. Pesquise o workflow 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 workflow

1. Abra o workflow.
2. Clique no menu principal do workflow no canto superior direito (...).
3. Selecione Configurações.
4. Ative Disponível no MCP.

Método 3: pela lista de workflows

1. Vá para Workflows.
2. Abra o menu no cartão do workflow.
3. Selecione Habilitar acesso MCP.

Gerenciar permissões de acesso

A página MCP em nível de instância mostra todos os workflows disponíveis para clientes MCP. Nessa lista, você pode:

• abrir diretamente o workflow, o projeto ao qual ele pertence ou a pasta pai
• usar o menu de ações para revogar o acesso (ou usar Desabilitar acesso MCP no menu do cartão do workflow)
• usar o menu de ações para atualizar a descrição do workflow (ou usar o menu no editor do workflow)
• usar o botão Habilitar workflow para habilitar o acesso a mais workflows (disponível no n8n v2.2.0 e superior)

Descrição do workflow

Para ajudar clientes MCP a identificar um workflow, você pode adicionar uma descrição em texto livre da seguinte forma:

1. Método 1: pela página MCP em nível de instância

   1. Vá para Configurações > MCP em nível de instância.
   2. Certifique-se de estar na aba Workflows.
   3. Use o menu de ações na linha do workflow desejado e selecione Editar descrição.
   4. Ou clique diretamente no texto da descrição para abrir a janela de edição.

2. Método 2: pelo editor de workflow

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

Executar workflows por meio de um cliente MCP

Clientes MCP podem executar workflows elegíveis com base na sua solicitação. Quando o cliente aciona um workflow, ele é executado no n8n como de costume, e você pode acompanhar a execução na lista de execuções. Quando a execução for concluída, o cliente MCP receberá o resultado.

Fornecer dados de entrada

Em geral, clientes MCP conseguem avaliar quais dados de entrada um workflow precisa. Se você usar um gatilho Webhook e perceber que o cliente tem dificuldade para determinar a entrada correta, recomenda-se incluir essas informações na descrição do workflow.

Tempo limite do workflow

O n8n aplicará um tempo limite fixo de 5 minutos às execuções de workflow acionadas por clientes MCP. Se o workflow não terminar a tempo, o n8n interromperá a execução e enviará um erro ao cliente MCP, ignorando o tempo limite configurado nas definições do workflow para execuções via MCP.

Limitações

• Se um workflow tiver vários gatilhos compatíveis, o cliente MCP talvez consiga usar apenas um deles (o primeiro) para acionar o workflow.
• Não há suporte para executar workflows com formulários de múltiplas etapas ou fluxos que exijam interação humana.
• Dados de entrada binários não são compatíveis; clientes MCP só podem fornecer entradas baseadas em texto para o workflow.

Exemplos

Conectar o Lovable ao servidor MCP do n8n

1. Configure o servidor MCP no Lovable (OAuth).
   • Vá para Configurações > Integrações no seu espaço de trabalho.
   • Na seção MCP Servers, encontre n8n e clique em Connect.
   • Insira a URL do seu servidor n8n (mostrada na página Acesso MCP).
   • Salve a conexão. Se tudo der certo, o n8n redirecionará você para autorizar o Lovable.
2. Verifique a conexão.
   • Após a conexão, o Lovable poderá consultar os workflows com acesso MCP habilitado.
   • Exemplo: peça ao Lovable para criar uma interface de workflow que liste usuários e permita excluir usuários.

Conectar o Claude Desktop ao servidor MCP do n8n

Usar OAuth2

1. No Claude Desktop, vá para Configurações > Connectors.
2. Clique em Add custom connector.
3. Informe os seguintes detalhes:
   • Name: n8n MCP
   • Remote MCP server URL: a URL base do seu n8n (mostrada na página MCP em nível de instância)
4. Salve o conector.
5. Quando solicitado, autorize o Claude Desktop a acessar sua instância do n8n.

Usar token de acesso

Observação

Essa 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>: a URL base do seu n8n (mostrada na página MCP em nível de instância)
• <YOUR_TOKEN>: o token gerado por você

Conectar 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 (também substituindo os marcadores de posição pelos valores descritos acima).

Conectar 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 marcadores de posição correspondentes pela URL base do seu n8n e pelo token gerado.)

Conectar um agente do Google ADK ao servidor MCP do n8n

A seguir está um exemplo de código para criar um agente conectado 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 um cliente MCP à sua instância do n8n, considere os seguintes pontos:

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