O que é

Há dois jeitos de ligar um agente de IA ao GW Server. Conectar com um clique (OAuth) é o caminho do claude.ai, do Claude Desktop, do app do celular, do ChatGPT e do Claude Code: você cola o endereço do painel, autoriza numa janela do próprio painel e pronto, sem chave para copiar. Conectar com uma chave serve para o Codex, o Cursor, o n8n e quando você quer prender o acesso a uma lista de IPs.

Antes de conectar

  • Licença Pro ativa e o módulo ligado em Configurações → Automação/MCP (Beta) (ver Agente de IA no GW Server).
  • Domínio do painel com SSL (ver Domínio do painel). O endereço do conector é https://<domínio do painel>/mcp. Pela porta 22222 não funciona: os agentes recusam o certificado próprio dela.
  • Acesso de fora do servidor ligado (aba Chaves). Na conexão com um clique, o painel liga sozinho ao você autorizar.

O endereço certo, com botão Copiar, está na aba Agente de IA, em Endereço do conector.

Conectar com um clique (claude.ai e Claude Desktop)

  1. No claude.ai: Personalizar → Conectores → Adicionar conector personalizado.
  2. Nome: GW Server. URL: https://<domínio do painel>/mcp. Clique em Adicionar.
  3. Clique em Conectar: o painel abre numa janela.
  4. Entre com o seu usuário (e o código de duas etapas, se tiver), escolha o que o agente pode fazer e clique em Autorizar.

O conector vale também no Claude Desktop e no app do celular, na mesma conta.

Conectar com um clique (ChatGPT)

  1. No ChatGPT: Configurações → Conectores (no modo desenvolvedor) → criar conector.
  2. URL do servidor MCP: https://<domínio do painel>/mcp.
  3. Autenticação: OAuth → Criar.
  4. Entre no painel, escolha o nível e os sites e clique em Autorizar.

Conectar com um clique (Claude Code)

No terminal do seu computador:

claude mcp add --transport http --scope user gw-servidor https://SEU-PAINEL/mcp

Depois, numa sessão do Claude Code, rode /mcp, escolha gw-servidor e Authenticate: o navegador abre o painel para você autorizar.

A tela de autorização

Na janela Conectar agente de IA você decide:

Campo Opções
O que o agente pode fazer Somente leitura (consulta, não muda nada) · Operar (recomendado) · Acesso total
Sites e aplicações Todos, inclusive os criados depois · Só os que eu escolher (com a opção de incluir os criados depois)
Nome da conexão Aparece em Chaves e na Atividade

Com Acesso total, o agente sempre para e espera o seu “sim” antes do que é destrutivo (ver Desfazer e aprovação). A tela mostra quem está pedindo: para o claude.ai e o Claude Code, o domínio do aplicativo com o selo verificado; para outros apps, o nome que o próprio app declarou e para onde você volta depois.

A conexão fica ativa enquanto for usada: só vence depois de 30 dias parada, e aí o aplicativo pede para conectar de novo. Quando ela for usada de uma rede nova, você recebe um e-mail (precisa do SMTP do painel configurado).

Conectar com uma chave (Codex, Cursor, n8n)

  1. Na aba Agente de IA, clique em Nova chave para agente.
  2. Escolha nível, sites, onde a chave é usada e a validade (ver Chaves, níveis e permissões) e clique em Criar chave.
  3. Copie a chave na hora: ela não aparece de novo. A tela mostra o comando pronto para cada cliente, já com a chave.
  4. Cole no computador onde o agente roda. A tela fica em Aguardando a primeira conexão do agente e confirma sozinha quando ele entrar.

Os formatos que a tela gera:

# Claude Code
claude mcp add --transport http gw-NOME --scope user https://SEU-PAINEL/mcp \
  --header "Authorization: Bearer gwm_SUA_CHAVE"

# Codex: a chave numa variável de ambiente (export GW_TOKEN_NOME="gwm_...")
# e no ~/.codex/config.toml
[mcp_servers.gw-NOME]
url = "https://SEU-PAINEL/mcp"
bearer_token_env_var = "GW_TOKEN_NOME"
  • Cursor: ~/.cursor/mcp.json com a URL e o cabeçalho Authorization: Bearer gwm_...; reinicie o Cursor e o servidor aparece em Settings → MCP.
  • n8n: nó AI Agent → Tools → MCP Client Tool, endpoint https://SEU-PAINEL/mcp, transporte HTTP Streamable, autenticação Bearer Auth. Guarde o token numa credencial do n8n, não no fluxo.
  • Outros: qualquer cliente MCP com transporte Streamable HTTP e cabeçalho de autorização.

Testar a conexão

O botão Testar conexão (aba Agente de IA) chama o /mcp pelo domínio público e diz se a rota responde. Abaixo dele, a tela mostra a última conexão de agente (“Conectado: claude-code …”).

Painel atrás do proxy da Cloudflare

Desde a versão 2.35.39, o agente e a API passam pela Cloudflare com o proxy ligado (nuvem laranja): o servidor reconhece a Cloudflare e confere o IP real de quem chama. Outros proxies (CDN, balanceador) continuam recusados, com o motivo na Atividade.

Se o Testar conexão avisar que o servidor ainda não reconhece a Cloudflare, rode a atualização do painel e teste de novo. Persistindo, deixe o registro do domínio do painel como Somente DNS (nuvem cinza).

Problemas comuns

  • O claude.ai pede para conectar de novo sem parar: a chamada chegou por um proxy não reconhecido ou a conexão foi revogada. Veja o motivo em Atividade.
  • “Precisa do domínio do painel com SSL”: configure em Configurações → Domínio do Painel.
  • Erro 401 com uma chave: chave errada, vencida ou origem fora da lista de IPs. A resposta é a mesma de propósito (quem sonda não descobre o motivo); o motivo real fica na Atividade.
  • Erro 403: o pedido está fora do escopo da chave (nível ou site).
  • O fail2ban do painel não bane as recusas do /mcp e do OAuth: a saída da Anthropic é compartilhada por todos os usuários dela, e um banimento derrubaria o seu conector.

Veja também

Anterior Agente de IA no GW Server (MCP) Próxima Chaves, níveis e permissões