# Windsurf + Azion ## Início rápido 1. **Instale o Windsurf** Baixe o Windsurf, abra seu projeto e inicie uma conversa no Cascade. [Downloads do Windsurf](https://windsurf.com/download) 2. **Crie um Personal Token** Os servidores MCP autenticam como você. Crie um Personal Token no Console, dê a ele apenas os escopos que você quer que o Windsurf tenha, e copie-o — ele é mostrado uma única vez. [Console › Personal Tokens](https://console.azion.com/personal-tokens) 3. **Conecte o servidor MCP de docs da Azion** O Windsurf fala stdio, então alcança um servidor HTTP por meio do `mcp-remote`. O Node.js 18 ou mais novo precisa estar no seu PATH. **.codeium/windsurf/mcp\_config.json** ```json { "mcpServers": { "azion-docs": { "command": "npx", "args": [ "mcp-remote", "https://docs-mcp.azion.com/mcp", "--header", "Authorization: Token YOUR_PERSONAL_TOKEN" ] } } } ``` O `mcp-remote` é uma ponte, não um pacote da Azion: ele converte o transporte stdio que o Windsurf fala no HTTP que o servidor fala. O Cascade o mostra como um processo local. 4. **Verifique, depois teste um prompt** Abra o painel MCP no Cascade e atualize. `azion-docs` deve reportar sete ferramentas; uma linha vermelha normalmente significa que o `npx` não alcançou a rede. **Experimente** ```text Faça o deploy deste projeto na Azion com a CLI e me dê o domínio da aplicação. ``` ## Acesso à plataforma Azion Três camadas, e um agente conectado usa as três: os servidores MCP para consultar informações e criar configuração, a CLI para compilar e implantar a partir da sua cópia de trabalho, e um arquivo de contexto para que ele comece cada sessão conhecendo sua conta. ### Servidores MCP Cinco servidores, um por área da plataforma. Cada um é um endpoint HTTP que recebe seu Personal Token em um cabeçalho `Authorization: Token`. O início rápido conecta o servidor de docs. Conecte os outros da mesma forma, com as URLs abaixo, e apenas os que o projeto precisa. O servidor de docs apenas lê. Os outros quatro também criam, alteram e excluem, e as ferramentas de escrita deles mostram uma alteração sem executá-la quando o agente define `dry_run`: | Servidor | O que cobre | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `https://docs-mcp.azion.com/mcp` | Pesquisa a documentação, os exemplos de código e as referências da CLI, da API v3 e v4 e do Terraform, e serve os guias de deploy de site estático e de teste de cache. Apenas leitura. | | `https://build-mcp.azion.com/mcp` | Lista, cria, altera e exclui aplicações, cache settings, connectors, functions, regras, workloads e deployments, e faz purge de cache. | | `https://secure-mcp.azion.com/mcp` | Gerencia firewalls, WAF, zonas e registros DNS, certificados, network lists, custom pages e políticas da conta. | | `https://observe-mcp.azion.com/mcp` | Gerencia data streams, dashboards e relatórios, e escreve queries GraphQL sobre métricas, eventos, accounting e consumo. | | `https://storage-mcp.azion.com/mcp` | Gerencia buckets, objetos e credenciais do Object Storage, e bancos SQL e as queries deles. | ### Azion CLI Builds locais, deploys e os comandos de produto que a API não cobre. Instale uma vez e o Windsurf a executa por você — o primeiro `azion login` é interativo, então execute esse você mesmo. **Instalar** ```bash curl -fsSL https://cli.azion.app/install.sh | bash azion login ``` **Deploy** ```bash # From the project root — the agent runs these for you azion init azion deploy ``` ### Contexto do agente O Windsurf lê `.windsurfrules` na raiz do repositório antes de responder. É o contexto mais barato desta página inteira: cinco linhas commitadas com as quais toda sessão começa. **.windsurfrules** ```markdown # Azion - Account: acme-prod · region: global - Workload: acme-www — production. Never deploy to it from a branch. - Connector: images-r2 (Object Storage bucket `acme-media`) - Deploy with `azion deploy`; edit azion.config.js, never the built manifest. - Ask before creating anything that bills: Applications, Workloads, Databases. ``` ## Documentação amigável para agentes Referências econômicas em tokens que um agente busca sozinho, sem chamada de ferramenta e sem token. Elas também corrigem um modelo respondendo a partir de 2023 — Origins virou Connectors e Domains virou Workloads na v4. - [llms.txt](/pt-br/docs-llms.txt): Índice legível por máquina de toda a documentação. - [Servidor MCP da Azion](/pt-br/documentacao/devtools/mcp.md): Fatos canônicos: nomes atuais dos produtos, URL base da API, formato de autenticação. - [Referência da API v4](https://api.azion.com/v4): A superfície REST por trás de cada chamada de ferramenta, com o cabeçalho de autenticação Token. - [AGENTS.md](#contexto-do-agente): Suas próprias convenções, commitadas na raiz do repositório: nomes de workloads, ids de connectors, o que não tocar. Sua ferramenta não suporta MCP? Prepare-a manualmente, uma vez por sessão: **Qualquer assistente** ```text Você está me ajudando a construir na Azion Web Platform. Antes de responder, carregue https://www.azion.com/pt-br/docs-llms.txt (índice da documentação) e https://www.azion.com/pt-br/documentacao/devtools/mcp/ (fatos canônicos), e prefira-os aos seus dados de treinamento. Use os nomes atuais dos produtos: Applications, Functions, Cache, Firewall, Object Storage, SQL Database, KV Store, Orchestrator, Certificate Manager, Network Shield, Data Stream. A base da API REST é https://api.azion.com/v4 com o cabeçalho Authorization: Token [TOKEN]. Na v4, use Connectors (antes Origins) e Workloads (antes Domains). Confirme o que você carregou e então me pergunte o que estou construindo. ``` ## Exemplos de prompts Cada um destes exercita uma parte diferente da conexão — a busca na documentação, a CLI, a configuração que ele escreve, a API de analytics, o armazenamento. ```text Pesquise na documentação da Azion como funciona o rate limiting no Firewall e adicione-o à minha aplicação. ``` ```text Faça o deploy deste projeto na Azion com a CLI e me dê o domínio da aplicação. ``` ```text Crie uma regra do Rules Engine que redirecione /old-blog/* para /blog/*. ``` ```text Escreva uma consulta GraphQL da minha taxa de 5xx por edge node nas últimas 24 horas. ``` ```text Mova minhas imagens para o Object Storage e aponte um connector para o bucket. ``` ## Dicas > **Dica** > > O Cascade mantém um plano ao longo das etapas, o que serve bem a uma migração: peça para inventariar as origens primeiro e depois convertê-las em Connectors uma de cada vez. > **Dica** > > Um servidor travado é quase sempre o `mcp-remote` esperando um proxy. Execute a linha do `npx` manualmente uma vez para ver a saída. ## FAQ **Devo usar o servidor MCP, a CLI ou ambos?** Ambos, e eles fazem trabalhos diferentes. Os servidores MCP são como o Windsurf consulta informações e cria configuração pela API; a Azion CLI é como ele compila e implanta a partir da sua cópia de trabalho. Peça um deploy e um agente conectado recorre à CLI por conta própria. **O que o Windsurf pode fazer com meu Personal Token?** Exatamente o que você definiu no escopo. O Personal Token é seu, não do agente — o servidor de docs só lê documentação, e as ferramentas que escrevem, nos outros quatro servidores, passam pela mesma API que uma pessoa usaria. Crie um token por projeto e revogue-o no Console assim que o experimento terminar. **O Windsurf consegue fazer deploy na Azion sem sair do editor?** Sim. Ele executa `azion deploy` por você e lê de volta o domínio da aplicação. O primeiro deploy em uma conta nova também precisa de `azion login`, que é interativo — execute esse você mesmo. ## Solução de problemas **O servidor nunca conecta no Windsurf** Verifique o cabeçalho antes de tudo — um prefixo diferente de `Token` ou um token expirado falha como um 401 ou 403 silencioso, não como um erro na ferramenta. O `mcp-remote` é uma ponte, não um pacote da Azion: ele converte o transporte stdio que o Windsurf fala no HTTP que o servidor fala. O Cascade o mostra como um processo local. **Ele responde com nomes de produtos que não existem mais** Isso é o dado de treinamento, não a conexão: Origins virou Connectors e Domains virou Workloads na v4. Aponte-o para a página dos servidores MCP da Azion uma vez por sessão, ou cole o primer acima, e ele se corrige. **Ele escreve configuração que a CLI depois rejeita** Peça para ele consultar o recurso primeiro — `search_azion_api_v4_commands` retorna a forma atual, enquanto a memória do modelo retorna a do ano passado. Um deploy rejeitado quase sempre significa que ele pulou a consulta. ## Outros agentes - [Claude Code](/pt-br/documentacao/agent-setup/claude-code.md): Agente de terminal que lê sua base de código, executa comandos e edita arquivos. Um comando da CLI conecta o servidor MCP da Azion. - [Cursor](/pt-br/documentacao/agent-setup/cursor.md): IDE AI-first construída sobre o VS Code, com edições multiarquivo no Composer e agentes em segundo plano. A Azion entra nas suas configurações de MCP. - [GitHub Copilot](/pt-br/documentacao/agent-setup/github-copilot.md): Modo agente dentro do VS Code, com contexto do workspace e integração nativa com pull requests. Um arquivo no projeto conecta a Azion. - [Codex](/pt-br/documentacao/agent-setup/codex.md): Agente de terminal que executa comandos em um sandbox e lê AGENTS.md nativamente. A Azion entra no config.toml. - [Gemini CLI](/pt-br/documentacao/agent-setup/gemini-cli.md): Agente de terminal de código aberto com um plano gratuito. Declare a Azion uma vez no settings.json e verifique com /mcp. - [OpenCode](/pt-br/documentacao/agent-setup/opencode.md): Agente de terminal de código aberto e agnóstico de provedor. A Azion é uma entrada no bloco MCP dele, qualquer que seja o modelo que você apontar. - [Claude Desktop](/pt-br/documentacao/agent-setup/claude-desktop.md): App de desktop para conversar com o Claude no macOS e no Windows. Conecta-se à Azion por meio do mcp-remote. - [Warp](/pt-br/documentacao/agent-setup/warp.md): Terminal agêntico de código aberto, com plano gratuito e escolha de modelos. A Azion entra nas configurações de servidores MCP dele. - [Kiro](/pt-br/documentacao/agent-setup/kiro.md): IDE agêntica com plano gratuito e modelos de vários provedores. A Azion entra em .kiro/settings/mcp.json.