Publique um servidor MCP remoto no Cloudflare Workers com McpAgent e OAuth, reduza o contexto das ferramentas com o padrão de busca e execução do Code Mode e depois agrupe seus servidores atrás de um MCP Server Portal, com políticas de Access do Zero Trust, filtragem de ferramentas e logs de acesso.
Seu servidor Model Context Protocol (MCP) funciona bem no seu notebook. Depois, um colega pede a URL, um segundo editor precisa dela em outra máquina, e alguém da segurança pergunta quem pode chamar qual ferramenta. Um processo local não consegue responder a nada disso. A Cloudflare oferece três peças para esse momento: Workers para hospedar o servidor, Code Mode para reduzir o que o modelo precisa ler e MCP Server Portals para colocar todos os servidores atrás de uma porta controlada. A seguir, você encontra cada peça em ordem, com os comandos, a configuração e as armadilhas que importam, para ir de uma pasta vazia até uma configuração governada sem adivinhar.
Um servidor stdio é um processo filho de um cliente, em uma máquina. Isso funciona num projeto de fim de semana. Deixa de funcionar no momento em que uma segunda pessoa entra: cada um instala a sua cópia, os segredos ficam em arquivos de configuração locais e ninguém consegue ver quais ferramentas são chamadas. Um servidor remoto resolve todos esses problemas de uma vez. Você tem uma URL, uma publicação e um lugar para ler os logs.
O local ainda vence em um caso: uma ferramenta que mexe em arquivos da máquina de uma única pessoa, como uma pasta privada de anotações. A hospedagem remota serve para ferramentas que várias pessoas ou vários agentes compartilham.
Os Workers executam seu código na rede de borda da Cloudflare, perto de quem está chamando. Para MCP, especificamente, a Cloudflare oferece três blocos de construção:
McpAgent, uma classe do Agents SDK que cuida do transporte remoto. O SDK serve Streamable HTTP para você.workers-oauth-provider, uma biblioteca provedora de OAuth 2.1 que envolve seu Worker e adiciona autorização aos seus endpoints, inclusive os endpoints MCP.mcp-remote, um adaptador que permite que clientes que só falam stdio se conectem a um servidor remoto.| Necessidade | Servidor stdio local | Servidor remoto em Workers |
|---|---|---|
| Quem pode usar | Uma máquina | Qualquer pessoa com a URL e um login |
| Atualização | Reinstalar em cada máquina | Um wrangler deploy |
| Segredos | Arquivos de configuração locais | Segredos do Worker |
| Estado por sessão | Memória do processo | Durable Objects |
| Visibilidade | Nenhuma integrada | Logs de acesso do portal |
💡 Lembre-se: remoto não significa público. Trate a URL como uma API exposta à internet desde a primeira publicação.
A Cloudflare mantém um template para um servidor sem login, que é a forma mais rápida de ver as partes em movimento:
npm create cloudflare@latest -- my-mcp-server --template=cloudflare/ai/demos/remote-mcp-authless
cd my-mcp-server
npm start
Seu servidor agora escuta localmente em http://localhost:8788/mcp. Não há mais nada para instalar.
O coração do projeto é uma classe que estende McpAgent. Você registra as ferramentas dentro de init(), exatamente como faria com o SDK oficial de TypeScript:
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
export class MyMCP extends McpAgent {
server = new McpServer({ name: "math", version: "1.0.0" });
async init() {
this.server.tool("add", { a: z.number(), b: z.number() }, async ({ a, b }) => ({
content: [{ type: "text", text: String(a + b) }],
}));
}
}
export default MyMCP.serve("/mcp");
Essa classe também é um Durable Object, e por isso a configuração do projeto declara um binding e uma migração para ela. Os Durable Objects dão a cada sessão MCP o seu próprio estado, sem um banco de dados do seu lado. Se suas ferramentas só devolvem resultados puros, você nunca vai mexer nesse estado. No momento em que você acompanhar um carrinho, um rascunho ou uma conversa longa, vai ficar feliz por ele existir.
Execute o MCP Inspector em um segundo terminal e aponte-o para a URL local:
npx @modelcontextprotocol/inspector@latest
Chame sua ferramenta pela interface web. Quando ela se comportar como esperado, publique:
npx wrangler@latest deploy
Seu servidor fica então no ar em https://my-mcp-server.<your-account>.workers.dev/mcp. Clientes que só falam stdio, como o Claude Desktop, se conectam pelo adaptador:
{
"mcpServers": {
"math": {
"command": "npx",
"args": ["mcp-remote", "https://my-mcp-server.<your-account>.workers.dev/mcp"]
}
}
}
Você também pode colar a URL no Cloudflare AI Playground ou no Inspector para testar a versão publicada.
Um servidor sem autenticação serve para uma demo, e é uma má ideia para qualquer coisa que toque em dados reais. O segundo template da Cloudflare conecta o GitHub como provedor de identidade:
npm create cloudflare@latest -- my-mcp-server-github-auth --template=cloudflare/ai/demos/remote-mcp-github-oauth
A configuração é uma checklist curta:
npx wrangler secret put GITHUB_CLIENT_ID e npx wrangler secret put GITHUB_CLIENT_SECRET, além do segredo de criptografia de cookies citado no README do template.npx wrangler kv namespace create "OAUTH_KV".wrangler.jsonc e, então, publique.Por baixo dos panos, workers-oauth-provider envolve seu Worker, então suas ferramentas recebem os dados do usuário já autenticado como parâmetro. Você não escreve verificações de token na mão, e esse é justamente o ponto.
💡 Dica: o GitHub é só uma opção. A mesma biblioteca provedora pode ficar na frente de qualquer provedor de identidade OAuth, o que importa quando você planeja colocar o servidor atrás de um portal.
Cada definição de ferramenta que você expõe é um texto que o modelo precisa ler antes de fazer algo útil. Isso é administrável com dez ferramentas. Desmorona com uma plataforma inteira. A Cloudflare informa que expor a própria API, com mais de 2.500 endpoints, como ferramentas MCP comuns consumiria mais de 1,17 milhão de tokens. Com o Code Mode, o mesmo alcance cabe em cerca de 1.000 tokens.
Há um segundo custo que recebe menos atenção. Em um loop normal de chamadas de ferramentas, cada resultado intermediário passa de volta pelo modelo. Se o passo dois precisa da saída do passo um, o modelo lê, reescreve e encaminha adiante. O Code Mode permite que o modelo escreva um programa curto. As chamadas dependentes rodam dentro do sandbox, os dados intermediários ficam lá e só a resposta final volta para a conversa. Menos idas e vindas significam menos texto para ler e menos chances de copiar um valor errado.
O padrão para APIs grandes, openApiMcpServer(), expõe apenas duas ferramentas:
search roda código escrito pelo modelo contra um documento OpenAPI dentro de um sandbox e devolve apenas as operações, parâmetros ou schemas que a tarefa precisa.execute roda código escrito pelo modelo com uma função de requisição autenticada que o seu Worker fornece.Como dizem os docs, apenas o subconjunto devolvido entra no contexto do modelo. O modelo faz uma pergunta estreita, recebe uma resposta estreita e então age.
Imagine um pedido como liste os registros DNS da minha zona. O modelo primeiro escreve um pequeno trecho para search que filtra os caminhos do OpenAPI até as operações de DNS, e recebe de volta alguns resultados em vez de milhares. Depois escreve um trecho para execute que chama a operação certa pela sua função de requisição e devolve somente os campos de que precisa. Duas idas e vindas curtas substituem uma lista de ferramentas do tamanho de uma lista telefônica.
Para criar um, você precisa de um projeto de Workers, de um documento OpenAPI 3.x e de um método do lado do host para autenticar as requisições.
O código escrito pelo modelo roda em um Worker isolado, e o acesso de rede de saída direto é bloqueado por padrão. O código gerado só consegue alcançar o mundo externo por meio de ferramentas MCP upstream ou do callback de requisição que você fornece. Esse é um padrão forte, mas não faz a autorização por você:
codeMcpServer() | openApiMcpServer() | |
|---|---|---|
| Ideal para | Envolver um servidor MCP existente com um conjunto gerenciável de ferramentas | Catálogos grandes de APIs |
| O que o modelo vê | Uma ferramenta code com definições em TypeScript de cada operação upstream | Duas ferramentas: search e execute |
| Como as chamadas acontecem | Por meio de um namespace codemode, então chamadas dependentes se compõem dentro do sandbox | Operações selecionadas chamadas por uma função de requisição fornecida pelo host |
| Custo de contexto | Cresce com o número de ferramentas upstream | Limitado, porque só os resultados de search voltam |
💡 Regra prática: envolva o que você já tem com
codeMcpServer(). Recorra aopenApiMcpServer()quando sua lista de ferramentas virar um catálogo, e não uma caixa de ferramentas.
Os MCP Server Portals foram lançados em beta aberta em agosto de 2025, como parte do Cloudflare One. A ideia é simples: direcionar cada requisição MCP por um único endpoint de portal, aplicar ali as políticas do Zero Trust e registrar tudo.
Antes de abrir o painel, confirme três coisas:
https://<subdomain>.<domain>/mcp.Um servidor só aparece no portal para pessoas que correspondem a uma política Allow. Os rótulos do menu podem mudar enquanto um recurso está em beta, então confie no painel atual mais do que em qualquer captura de tela.
Nas configurações do portal, você pode desligar o interruptor ao lado de qualquer ferramenta ou prompt que queira ocultar. Cada servidor mostra uma contagem de Tools authorized, para você ver quanto expôs. Alguns controles que vale conhecer:
{server_id}_{tool_name}, para que dois servidores possam ter cada um uma ferramenta search sem colisão.Os logs do portal registram horário, status, nome do servidor, tipo de recurso e duração, por portal ou por servidor. Eles podem ser exportados com o Logpush para armazenamento de terceiros ou para um SIEM. Para a implantação em equipe, é aqui que você responde à pergunta que a segurança fez no primeiro parágrafo: quem chamou o quê, e quando.
Uma ordem de implantação que mantém as surpresas pequenas:
/mcp ativo antes de adicioná-lo a um portal.💡 Teste rápido: abra o portal como um usuário que não está na sua política Allow. Se você vir algum servidor, sua política está errada.
Qualquer cliente que chame seu servidor precisa de um modelo capaz por trás. Estes modelos de linguagem do PicassoIA valem a pena para testar com suas ferramentas:
| Modelo | Destaque listado |
|---|---|
| Claude Sonnet 5 | Automatizar tarefas de programação |
| GPT 5.6 Sol | Resolver tarefas complexas de programação |
| Kimi K2.6 | Criar agentes de IA e escrever código |
| Gemini 3.5 Flash | Chat rápido, código e imagens |
Eles também são úteis antes de você publicar qualquer coisa: peça que um deles rascunhe as descrições das ferramentas, escreva o TypeScript que você daria ao Code Mode ou revise seu documento OpenAPI em busca de operações que você preferiria não expor.
Um Worker pode chamar qualquer API HTTP, então uma ferramenta MCP pode chamar a do PicassoIA. A API do PicassoIA fica em https://api.picassoia.com/v1, aceita um bearer token que começa com pia_sk_ e segue um padrão no estilo Replicate: POST /v1/models/{owner}/{name}/predictions cria um job e GET /v1/predictions/{id} lê o status dele. Os jobs são assíncronos, e uma conta executa até 5 predições ao mesmo tempo.
Esse formato se encaixa bem em duas ferramentas: uma que inicia uma geração e devolve um id, e outra que consulta o resultado. Guarde o token com npx wrangler secret put PICASSOIA_API_TOKEN e nunca o imprima em um resultado de ferramenta. Se preferir não construir nada, o PicassoIA também oferece sua própria conexão MCP, que dá ao seu cliente os mesmos modelos de imagem e vídeo diretamente.
Agora você tem o caminho completo: um Worker que serve MCP, OAuth na frente dele, Code Mode para manter o contexto pequeno e um portal para governar tudo. A recompensa mais rápida é fazer o servidor produzir algo visual.
Abra o Seedream 5 Pro, o GPT Image 2 ou o FLUX 2 Pro e escreva um prompt para a foto que você gostaria que seu último projeto tivesse. Depois, vá além com o Seedance 2.0 ou o Veo 3.1 Fast e transforme a imagem parada em movimento. Experimente iluminação, lente e ângulo até o resultado parecer uma filmagem real.
Todos os modelos estão listados em picassoia.com/en/all-models. Escolha um, rode um prompt e veja o que volta.
Escolha seu idioma
