Fazer deploy ↗
docs

MCP & Agentes IA

A CLI da Veloz tem servidor MCP embutido. Conecte Claude Code, Cursor, Windsurf ou Claude Desktop e deixe a IA fazer deploy por você.

A Veloz CLI é um servidor MCP (Model Context Protocol). Todos os comandos da CLI são expostos como ferramentas que agentes IA podem chamar. Em vez de você descrever o que fazer, a IA executa direto.

Primeira vez na Veloz? Rode veloz init, o wizard te oferece registrar o MCP automaticamente no agente que você já usa. Veja Quickstart com veloz init.

Por que isso importa

Sua IDE com IA já entende seu código. Com o MCP da Veloz conectado, ela também:

  • Cria projetos e serviços
  • Faz deploy
  • Lê logs de erro e busca na sua frota
  • Lista, cria e consulta bancos de dados
  • Configura variáveis de ambiente
  • Adiciona domínios e verifica DNS
  • Lê métricas e detecta regressões

Tudo sem você sair do chat ou do editor.

Conectar em um clique

Na raiz de qualquer projeto (ou qualquer pasta):

veloz mcp add

A CLI detecta os agentes instalados (Claude Code, Cursor, Claude Desktop, Windsurf, Codex CLI, Continue, etc.) e te pergunta onde quer registrar o servidor. Depois disso, basta abrir o agente e começar a pedir.

Pré-requisito: você precisa estar autenticado na Veloz (veloz login). O agente usa o seu login.

Configuração manual

Se preferir configurar manualmente, o servidor é iniciado por:

npx -y onveloz --mcp

Claude Desktop

Adicione em ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "veloz": {
      "command": "npx",
      "args": ["-y", "onveloz", "--mcp"]
    }
  }
}

Cursor

Em Settings → MCP, adicione um novo servidor com:

  • Command: npx
  • Args: -y onveloz --mcp

Claude Code, Windsurf, Codex CLI

Use o helper:

veloz mcp add

Ele coloca a configuração no lugar certo automaticamente.

Lista de ferramentas expostas

Cada comando da CLI vira uma ferramenta MCP. Os nomes são achatados com _:

Ferramenta MCP Equivalente CLI O que faz
deploy veloz deploy Faz deploy de um serviço
services_list veloz services list Lista serviços do projeto
services_delete veloz services delete Remove um serviço
logs_show veloz logs show Mostra logs recentes
logs_search veloz logs search Busca em logs com LogsQL
metrics_show veloz metrics show Métricas atuais
metrics_range veloz metrics range Métricas em janela de tempo
metrics_query veloz metrics query Query MetricsQL custom
builds_list veloz builds list Histórico de builds
builds_show veloz builds show Detalhes de um build
builds_logs veloz builds logs Logs de build
env_list / _set / _delete / _import / _export veloz env ... Variáveis de ambiente
domains_list / _add / _delete / _verify veloz domains ... Domínios
db_list / _create / _credentials / _query / _tunnel / _update / _restart / _delete veloz db ... Bancos de dados
volumes_list / _create / _expand / _delete / _sync veloz volumes ... Volumes
template_list / _deploy veloz template ... Templates 1‑click
github_setup / _status veloz github ... Integração GitHub
apikey_list / _create / _delete veloz apikey ... API keys
projects_list veloz projects list Lista projetos
orgs_list / _use veloz orgs ... Workspaces

Skills, descoberta token-eficiente

Alguns agentes (como Claude Code) suportam skills: arquivos compactos por grupo de comandos que descrevem a CLI sem o agente precisar carregar a doc completa. Para gerar:

veloz skills add

Isso cria um SKILL.md por grupo (db, logs, metrics, etc.) no diretório de skills do agente detectado. Útil em projetos grandes onde você quer respostas rápidas sem queimar tokens.

Boas práticas

  • Mantenha um veloz.json na raiz. Assim o agente sabe qual projeto/serviço operar sem você precisar dizer toda vez.
  • A autenticação do MCP usa sua sessão. A CLI usa o token salvo pelo veloz login. Para uso pessoal no editor é o ideal. Em CI, prefira API keys (veja API keys).
  • Peça confirmações destrutivas. Quando pedir para deletar serviços, bancos ou volumes, peça que o agente confirme primeiro ou liste antes. veloz deploy --dry-run também é seguro.

Exemplos de prompts

"Lista os serviços do projeto e me diz quais estão consumindo mais memória."

"Procura nos logs do api qualquer erro 500 nas últimas 2 horas."

"Cria um Postgres com o tamanho essencial e adiciona o DATABASE_URL ao serviço web."

"Adiciona o domínio app.meudominio.com.br ao serviço web e me passa o registro DNS para configurar."

"Faz deploy de todos os apps do monorepo e me avisa quando terminarem."

Troubleshooting

O agente não vê as ferramentas. Verifique se veloz login foi feito e se a configuração do agente aponta para npx -y onveloz --mcp. Reinicie o agente após adicionar.

Erro de autenticação. Rode veloz whoami no terminal — se falhar, refaça veloz login.

Conflito de organização. Se você pertence a vários workspaces, o agente pode receber MULTIPLE_ORGS. Rode veloz orgs use <slug> para fixar a org default.

Próximos passos