sexta-feira, 20 de novembro de 2026 Edição nº 244
Buscar
Avaliação Conduzido por humano, com apoio de IA · Infraestrutura · 15 min de leitura

Cloudflare MCP Server Portals: Hands-On com Três Workers Atrás de um Único Portal

Por Fabio Douek

Conduzido por humano, com apoio de IA. Pesquisa e implementação feitas com ferramentas de IA, conduzidas, testadas e editadas por mim. Como os posts são classificados

Ir para seção
Explica (TLDR) como se eu fosse...
O que é isso?

Imagine uma escola com uma porta de entrada e um adulto parado nela. Atrás da porta há três salas de aula, e cada uma tem seus próprios ajudantes. Em vez de aprender onde fica cada sala, o visitante só precisa conhecer a porta da frente, e o adulto deixa entrar as pessoas certas e mostra a elas os ajudantes certos.

O adulto também pode esconder um ajudante que não é para visitantes. Mas a sala de aula ainda tem uma porta lateral, e quem a encontrar consegue entrar, então a porta lateral também precisa da sua própria tranca.

Um portal é um gateway único na frente de vários servidores MCP. As políticas de acesso decidem quem entra, e cada chamada é registrada com o servidor, a tool e o resultado. Isso dá um lugar único para revisar e um único registro para apresentar.

A ressalva relevante é que esconder uma tool no portal não é enforcement. No meu teste, o servidor por trás dele ainda aceitou uma chamada destrutiva feita diretamente ao seu próprio endereço, sem credenciais. O enforcement precisa estar também no servidor. A exportação de logs é um recurso Enterprise.

Pense no portal como uma triagem posta na frente de três clínicas especializadas. Ele verifica a identidade, decide quais clínicas a pessoa pode ver e escreve uma anotação no prontuário a cada visita. As medições do primeiro dia foram benignas: cerca de 90 milissegundos de atraso adicional por chamada nas minhas execuções.

O achado a observar é uma contraindicação. Esconder um procedimento na triagem não impede quem entra direto na clínica. A clínica precisa da sua própria verificação, e confirmei que essa funciona.

Um portal tira uma preocupação das costas do time: ninguém precisa lembrar qual de vários endereços de servidor colar em qual ferramenta. Um endereço, um login e uma lista que já foi curada.

O sentimento que ele pode criar é um falso conforto. Ver uma tool perigosa sumir da lista parece segurança, mas o servidor em si ainda responde a quem o chamar diretamente. Nomear essa lacuna cedo, e combinar quem é dono da tranca de cada servidor, evita uma conversa constrangedora depois.

Pense no portal como uma mesa de som com uma única saída. Três instrumentos se conectam, e você decide quais canais chegam aos alto-falantes e como cada um aparece na etiqueta. A plateia só ouve a mix.

O porém é a latência: o hop extra adicionou cerca de 90 milissegundos por chamada nas minhas execuções, o que é aceitável para um agente e perceptível para qualquer coisa que precise parecer ao vivo. E silenciar um canal na mesa não desconecta o instrumento, que ainda pode tocar se alguém o alcançar diretamente.

A história é um endpoint em vez de vários. As equipes configuram uma única URL de portal no seu cliente de IA, e os administradores decidem quais servidores e quais tools ficam atrás dela, com um log de cada chamada. Numa conta Free levou cerca de um minuto das chamadas de API até um portal no ar.

O posicionamento honesto é "uma porta de entrada", não "um cofre". O post mostra onde a porta termina: uma tool escondida ainda pode ser alcançada no endereço do próprio servidor até que você coloque uma verificação de acesso ali. Essa clareza é a parte que vale a pena emprestar para um case study.

GitHub Veja o código-fonte aqui: cloudflare-mcp-server-portals

Visão Geral

Um Cloudflare MCP Server Portal coloca vários servidores MCP remotos atrás de um único hostname. O cliente é configurado com uma só URL, https://<host>/mcp. O Cloudflare Access cuida de quem pode se conectar, o portal prefixa cada tool com o id do seu servidor (notes_get_note, tickets_list_tickets), e um administrador decide quais servidores e quais tools aparecem. Os portais entraram em open beta em 2025-08-26 e ficaram disponíveis para todos (GA) em 2026-09-24, segundo o changelog do Access da Cloudflare.

A pergunta que eu queria responder é a que o material de lançamento deixa em aberto: um portal é um launcher que organiza uma lista de servidores, ou um ponto de enforcement? A própria documentação da Cloudflare diz que um usuário bloqueado em um servidor ainda consegue alcançá-lo pela URL direta. Eu queria ver isso acontecer, fechar a brecha e medir quanto custa o hop. Usei uma conta Free com o Zero Trust ativado e um domínio que eu já tinha nela, e criei tudo pela API, então o dashboard mostra o que os scripts fizeram, e não o que eu cliquei.

Testei três servidores MCP em Workers: notes (três tools somente leitura, sem autenticação), tickets (quatro tools, uma delas a destrutiva delete_ticket) e catalog (40 tools pequenas, para ver quanto custa uma lista grande de tools). O código está no repositório complementar.

Arquitetura

CONTA CLOUDFLARE (PLANO FREE, ZERO TRUST FREE) Agente cliente MCP headless service token MCP Server Portal mcp-portal-demo.<domain>/mcp app Access + política prefixo de tool {server}_{tool} esconder / renomear tools opções de Code Mode timeout upstream de 60 s log: servidor, tool, status, duração notes Worker, workers.dev aberto, 3 tools tickets Worker, domínio customizado app Access self-hosted 4 tools, incl. delete_ticket catalog Worker, workers.dev aberto, 40 tools HTTPS + token

DNS: CNAME com proxy mcp-portal-demo para gateway.agents.cloudflare.com

Qualquer pessoa que conheça a URL própria de um Worker sem credenciais ignora o portal tickets: bloqueado após a correção

Setup

Usei uma conta Cloudflare Free com o Zero Trust ativado, um domínio que já era uma zona ativa nela e um API token com escopo restrito. A documentação pede um domínio ativo na Cloudflare para a URL do portal. Primeiro tentei delegar um subdomínio do meu domínio principal para esta conta, e o dashboard se recusou a adicioná-lo como zona: zonas de subdomínio são exclusivas do Enterprise, então usei um domínio separado. Duas execuções de wrangler deploy colocaram os servidores em workers.dev. Os Workers têm cerca de 60 linhas cada: um McpServer de @modelcontextprotocol/server envolvido por createMcpHandler do pacote agents, que é stateless, sem Durable Object. O Worker tickets o envolve assim; o notes monta o handler a cada request para poder ler uma variável.

const handler = createMcpHandler(createServer);
export default {
  fetch: (request: Request, env: unknown, ctx: ExecutionContext) => handler(request, env, ctx),
} satisfies ExportedHandler;

A API faz menos que o dashboard. POST .../access/ai-controls/mcp/servers e .../portals criam os servidores e o portal, e a documentação diz que a API não cria o registro DNS, então você mesmo adiciona um CNAME com proxy para gateway.agents.cloudflare.com. Descobri que ela também não cria as aplicações Access, então criei a política, a aplicação do portal e uma aplicação por servidor também. Depois disso, o dashboard mostrou “This portal is protected by portal-demo portal”. Da primeira chamada de API até um portal que responde, levou 65 segundos na minha execução gravada:

Segundos após a primeira chamadaO que https://mcp-portal-demo.<domain>/mcp fez
8O nome não resolveu na minha máquina
13Erro 1014 da Cloudflare, “CNAME Cross-User Banned” (HTTP 403)
65HTTP 401 com metadados de descoberta OAuth, que é o portal funcionando

Aba MCP Servers no dashboard: Tickets, Notes e Catalog, cada um Ready, com seus endpoints e contagem de tools

Registros DNS do domínio do laboratório: o CNAME com proxy do portal e o custom domain do Worker para tickets

Como Funciona

O primeiro contato de um cliente

Sem credenciais, o portal responde 401 com um header WWW-Authenticate que aponta para os metadados OAuth de protected-resource, que nomeiam o próprio portal como servidor de autorização e listam os endpoints de autorização, registro, revogação e token. Um cliente interativo consegue percorrer esse caminho. Um agente headless pode, em vez disso, enviar um service token do Access nos headers CF-Access-Client-Id e CF-Access-Client-Secret, que foi o que eu fiz. Um token que a política não permite recebe a página de bloqueio do Access da Cloudflare (HTTP 403), e o token permitido recebe um id de sessão (Mcp-Session-Id) que todas as chamadas seguintes precisam carregar. Um Worker stateless não precisa de nada disso, então o portal adiciona o estado para clientes da era de 2025.

Mais uma coisa que encontrei: o erro 1014 não é apenas um artefato de start-up. Numa execução anterior ele apareceu no meio de um teste de latência, depois que o portal já vinha respondendo, então o cliente complementar reenvia uma chamada nesse caso.

Quanto custa o hop

Chamei get_note 30 vezes diretamente no Worker notes e 30 vezes pelo portal, a partir de uma conexão doméstica, depois de uma chamada de warm-up em cada caminho.

Caminhomínmedianap95máx
Direto ao Worker12 ms14 ms30 ms41 ms
Pelo portal93 ms105 ms143 ms154 ms

O overhead mediano foi de 91 ms nessa execução, e de 92 ms e 118 ms em duas execuções anteriores que não guardei. Isso é o hop do portal mais a sua própria chamada ao Worker, medido de um único lugar, então trate como uma ordem de grandeza: cerca de um décimo de segundo por chamada.

Curadoria da lista de tools

A lista do portal para o agente tinha as três tools de gerenciamento do portal (portal_list_servers, portal_toggle_servers, portal_toggle_single_server) mais todas as tools upstream com o prefixo do seu servidor. Escondi delete_ticket e renomeei list_tickets com um alias no nível do portal por meio de PUT .../portals/demo.

Tabela de servidores na página de edição do portal: Notes com 3/3 tools autorizadas, Tickets 3/4, Catalog 40/40

Uma sessão nova viu tickets_recent em vez de tickets_list_tickets e nenhuma tool de delete, e chamar a tool escondida pelo nome retornou Tool tickets_delete_ticket not found. A mudança chegou a uma sessão nova depois de 1 a 16 segundos ao longo de várias execuções, então um script que altera a lista deve fazer polling em vez de presumir. Quando refiz o deploy de notes com mais uma tool e chamei POST .../servers/notes/sync, o portal a tinha em menos de um segundo, e o agente a viu como notes_count_notes após 12 a 15 segundos.

Esconder não é enforcement

Com delete_ticket escondida no portal, chamei a URL workers.dev do próprio Worker tickets sem credenciais e ela executou: deleted 2. Essa é a limitação documentada, agora reproduzida. Para fechá-la, movi o Worker para um domínio customizado com workers.dev desligado, coloquei na frente dele uma aplicação Access self-hosted com uma política de Service Auth e o registrei no portal como um servidor bearer levando esse segundo service token como headers.

Dois detalhes me custaram tempo. O hostname e o auth_type de um servidor não podem ser alterados com PUT (o endpoint aceita nome, credenciais e overrides de tools), então apaguei o servidor e o registrei de novo, e com ele a aplicação Access do servidor. E um servidor bearer assume por padrão autorização por usuário no mapeamento do portal, algo que uma sessão com service token nunca vê, até que o mapeamento diga on_behalf: false.

Tentativa após a correçãoResultado
URL antiga de workers.dev, sem credenciaisHTTP 404
Domínio customizado, sem credenciaisHTTP 403
Domínio customizado, o outro service tokenHTTP 403
Domínio customizado, o token da origemHTTP 200
Pelo portal, token do agenteHTTP 200

O mesmo código do Worker rodou nos dois casos. O portal não aplicou enforcement por conta própria; quem aplicou foi a aplicação Access na origem.

Quem entra e quem vê o quê

Usei dois service tokens e algumas políticas do Access. Com a política do portal permitindo apenas o token do agente, o outro token recebeu 403. Quando o portal e o notes permitiam os dois tokens mas o tickets permitia apenas o agente, o segundo token se conectou e viu somente as três tools de notes. Isso confere com a documentação, que diz que um servidor aparece em um portal apenas para usuários que correspondem a uma política Allow nele. A documentação também diz que MFA independente, justificativa de propósito e autenticação temporária não são aplicados para servidores autorizados por meio de um portal, o que eu não testei.

Lista de aplicações Access: uma aplicação MCP por servidor, a aplicação do portal e a aplicação self-hosted da origem

Logs

O portal registra cada chamada de tool com o servidor, a capability, a tool, o status e a duração.

Logs do portal no dashboard: chamadas de notes e tickets com Success ou Error e durações, incluindo uma chamada de tickets de 60008 ms que falhou

Essas linhas vieram dos meus scripts: uma chamada a uma tool escondida e uma chamada para uma nota que não existe são ambas Error, e uma chamada que ultrapassa o timeout aparece com 60008 ms. Uma request que a política de Access do portal bloqueou não aparece ali; ela está no log de requests do Access, com allowed: false. O endpoint de analytics deu contagens por status (success, error, all), e a documentação lista a exportação via Logpush como exclusiva do Enterprise. Descobri que GET .../access/ai-controls/mcp/logs também retorna essas linhas, mas ele não está na documentação que li, então eu não construiria nada em cima dele.

Tamanho do contexto

Adicionei catalog com 40 tools pequenas e comparei o que o agente recebe. Os tamanhos são o comprimento em JSON do resultado de tools/list, e os números de tokens são caracteres divididos por quatro, uma estimativa e não uma contagem de tokenizer.

Query na URL do portalTools listadasCaracteresTokens aprox.
nenhuma4913.3063.300
?optimize_context=minimize_tools508.3872.100
?optimize_context=search_and_execute52.058510
?codemode=search_and_execute54.7841.200

Com search_and_execute, o agente encontra uma tool com portal_query_tools(pattern=...) e a chama com portal_execute(tool_name, arguments), e ambas funcionaram contra o catalog. A Cloudflare relata uma redução de 94% em um deployment interno (52 tools, cerca de 9.400 tokens para cerca de 600). Minhas 49 tools foram de cerca de 3.300 para cerca de 510 com search_and_execute, uma lista menor e um corte menor. Numa execução anterior, antes de eu adicionar o catalog, o portal listava nove tools (três de notes, três de tickets com a tool de delete escondida, e as três próprias) com cerca de 2.400 caracteres, e nenhuma dessas opções economizou nada. As opções de contexto compensam com listas grandes.

Quando as coisas falham

Uma chamada de tool que leva 65 segundos retornou um erro após 60,1 segundos: Request timed out - server is slow or unresponsive, código -32001, timeout: 60000. Uma chamada de cinco segundos funcionou normalmente. Um servidor apontado para um Worker que não existe foi registrado e depois mostrou status: error com HTTP 404 | error code: 1042 e nenhuma tool. Registrar o servidor tickets no seu novo domínio customizado também mostrou status: error por cerca de 19 segundos, com uma mensagem que sugeria rotear pelo Gateway, até que syncs repetidos o deixaram ready, e é por isso que o script pede outro sync.

Limpeza

Tudo o que os scripts criam é removido por 99_cleanup.py: o portal, os três servidores, as cinco aplicações Access, as três políticas, os três service tokens, o attachment do domínio customizado, o registro com proxy e os três Workers. Em seguida ele lista os portais, servidores, aplicações Access, políticas, service tokens, Workers e registros DNS da conta; todas as contagens foram zero depois, na minha execução. O plano Free não me custou nada: Workers Free e Zero Trust Free (até 50 usuários) não cobram nada, e não encontrei nenhuma cobrança separada por portais em nenhuma página da Cloudflare que li.

.venv/bin/python 99_cleanup.py

Veredito

O que funciona. Um portal é rápido de montar pela API numa conta Free, a única URL com nomes de tools prefixados é o que você esperaria, e a curadoria (esconder, renomear, sincronizar) é simples. O log por chamada com servidor, tool, status e duração é útil. O caminho com service token o torna automatizável por scripts para agentes.

O que não funciona. O portal não é um ponto de enforcement para os servidores atrás dele. Reproduzi o bypass pela URL direta e foi preciso uma aplicação Access na origem para fechá-lo. A API deixa de fora o registro DNS e as aplicações Access que o dashboard cria, hostname e tipo de autenticação ficam fixos depois da criação, as mudanças levam segundos para chegar a uma sessão, e encontrei um erro 1014 da Cloudflare no start-up e uma vez no meio de uma execução. O hop custa cerca de 100 ms por chamada a partir da minha conexão.

Quem deve usar. Times que já estão no Cloudflare One e querem uma URL MCP estável, listas de tools curadas e um log, e que também vão colocar o Access na frente dos seus próprios servidores. Times que precisam de servidores stdio (a documentação diz que portais aceitam apenas servidores HTTP remotos) ou de listas de tools que variam por papel (os toggles são por portal) vão achá-lo limitante. Trate o portal como a porta da frente e tranque cada servidor separadamente.

Comments