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.

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

Boas práticas

  • Mantenha um veloz.json na raiz. Assim o agente sabe qual projeto/serviço operar sem você precisar dizer toda vez.
  • Restrinja API keys quando ativar em CI. A autenticação local do veloz mcp usa sua sessão pessoal — adequada para uso individual no editor.
  • Peça confirmações destrutivas. Quando pedir para deletar serviços, bancos ou volumes, peça que o agente confirme primeiro com --dry-run ou liste antes.

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