VPSnet

vpsnet-mcp

Model Context Protocol (MCP) servidor para gerenciar serviços da VPSnet.com. Oferece a assistentes de IA acesso a operações do ciclo de vida de VPS, aplicativos gerenciados, zonas DNS, registro de domínios e contatos, cobrança, metadados de chaves de API, provisionamento de chaves SSH e ferramentas relacionadas à conta por meio da API VPSNet.

Recursos

• Mais de 280 ferramentas que cobrem gerenciamento de serviços VPSNet, aplicativos gerenciados, certificados TLS gratuitos e pagos, assinaturas SSL Automático, DNS, domínios, cobrança, chaves de API e operações de conta
• Gerenciamento de conta e perfil
• Ciclo de vida de VPS (iniciar, parar, reiniciar, reinstalar SO)
• Alterações de plano (upgrades/downgrades gratuitos; discos KVM/Firecracker não podem ser reduzidos)
• DNS reverso do serviço (registros rDNS/PTR)
• Zonas DNS diretas, registros, DNSSEC, modelos, importação/exportação e tokens DDNS
• Disponibilidade de domínios, contatos, cotações de registro/transferência/renovação/restauração e confirmações pagas
• Aplicativos gerenciados com publicação controlada, incluindo instalação, saúde, eventos e ações de ciclo de vida tipadas
• Gerenciamento de chaves SSH — implantar chaves e obter acesso direto ao servidor
• Inspeção de metadados de chaves de API (criação, alterações e revogação de chaves permanecem apenas na sessão)
• Backups, cobrança, faturas
• Solicitação de novas instâncias VPS
• Status do sistema e preços

Conector OAuth remoto

O perfil remoto também inclui DNS com escopo, gerenciamento de domínios e certificados, chaves SSH públicas, recuperação de servidor e navegação de backups. Ele usa as mesmas APIs de cliente do painel; as permissões são aplicadas pelo backend em cada solicitação.

O conector remoto usa https://mcp.vpsnet.com/mcp e consentimento do cliente por meio da VPSnet. Consulte Conexões de IA remotas para configuração de conexão, permissões e operações suportadas.

O README do plugin distribuível, manifestos e habilidades estão em inglês. Consulte prontidão do diretório para validação de pacotes e requisitos do editor, e casos de uso suportados para cenários de servidor, aplicativos e redes. A publicação no diretório e a disponibilidade da conta do provedor são separadas da instalação deste código-fonte.

Consulte Configuração de clientes de IA para Gemini CLI, Cursor, Kimi Code, Kiro, Cline e outros clientes OAuth remotos. Os pacotes deles compartilham o mesmo endpoint VPSnet e habilidades de tarefas. O pacote npm fornece o servidor MCP local; os pacotes de plugin instaláveis também carregam o manifesto e as habilidades do aplicativo de IA.

Compile todos os pacotes de clientes com python3 scripts/package-distribution.py. A saída inclui somas de verificação e identifica cada formato. Os materiais de submissão ao diretório público estão em o kit de catálogo.

Pedidos usam a conexão VPSnet existente, com permissões de compra controladas pelo cliente e limites de gastos. A IA mostra o preço final e pede aprovação antes de cobrar o saldo da conta. A disponibilidade segue as regras de distribuição do aplicativo.

As instruções abaixo descrevem o cliente local existente via stdio/chave de API.

Pré-requisitos

Antes de instalar, certifique-se de ter:

1. Node.js 20 ou mais recente

   • Verifique: node --version
   • Linux/macOS: nodejs.org ou seu gerenciador de pacotes
   • Windows: winget install OpenJS.NodeJS.LTS ou baixe de nodejs.org
   • Após instalar o Node.js, reinicie seu terminal/editor

2. Para usuários do Claude Code (extensão CLI ou VS Code):

   • CLI do Claude Code instalado globalmente: npm install -g @anthropic-ai/claude-code
   • Verifique: claude --version

3. Conta ativa na VPSnet.com com uma chave de API (consulte Obtendo uma chave de API)

Caminhos de configuração de credenciais

VPSNET_API_KEY é a credencial preferida por inicialização e tem precedência sobre arquivos. Para configuração baseada em arquivos, defina VPSNET_CONFIG_DIR para o diretório absoluto que contém .vpsnet-mcp-key ou .mcp.json. O arquivo de chave tem precedência sobre mcpServers.vpsnet.env.VPSNET_API_KEY nesse arquivo JSON. Alternativamente, VPSNET_API_KEY_FILE seleciona um caminho absoluto de arquivo de chave; um arquivo explícito ilegível ou inválido falha na inicialização em vez de escolher outra conta.

Sem VPSNET_CONFIG_DIR, os arquivos são lidos apenas do diretório de inicialização do processo (cwd). Isso é o mesmo para node /path/to/vpsnet-mcp/build/index.js e npx vpsnet-mcp: o diretório de instalação/cache do pacote e os diretórios pais nunca são pesquisados. Defina o diretório explicitamente quando um editor ou cliente MCP iniciar a partir de um diretório de trabalho diferente. Mantenha os arquivos de credenciais fora do controle de versão. VPSNET_API_URL tem precedência sobre a URL nesse mesmo .mcp.json; as verificações existentes de host confiável e HTTPS se aplicam a qualquer fonte.

Aplicativos gerenciados

Aplicativos gerenciados, SSH manual, DNS, APIs e outras superfícies de implantação são capacidades pares. A ordem deles neste documento e na lista de ferramentas não é uma recomendação. Escolha o caminho que melhor corresponda ao resultado solicitado pelo usuário, suporte alvo, estado existente e restrições explícitas. Uma entrada de catálogo é um caminho gerenciado disponível, não um motivo para substituir uma solicitação válida de implantação manual ou personalizada. Os aplicativos de catálogo são executados como contêineres Docker no servidor do cliente e usam ferramentas de instalação e ciclo de vida tipadas.

Leituras de aplicativos exigem applications:read. Alterações de instalação e ciclo de vida exigem applications:manage e uma chave de idempotência; alterações comuns de ciclo de vida de aplicativos não são operações pagas de chave de API. Os valores de CPU, RAM e disco são recomendações de dimensionamento, não portões de instalação: um aplicativo suportado permanece selecionável durante o pedido e instalável abaixo desses valores. Compatibilidade de produto, SO, arquitetura e runtime permanecem requisitos rígidos. As alterações são assíncronas, então verifique-as com get_application_installation e get_application_events. Use get_application_health para uma inspeção nova de saúde do contêiner e get_application_logs para logs de solução de problemas recentes com limite de tamanho, opcionalmente limitados a um único serviço Compose exato. As inspeções de logs aceitam no máximo 500 linhas e 131.072 bytes. Essas duas inspeções de leitura criam trabalhos de inspeção de curta duração, então a chave de API deve permitir solicitações POST.

Os detalhes de instalação incluem histórico limitado de CPU, memória, rede, reinicialização e armazenamento do aplicativo e por contêiner quando o worker o relata. Os contêineres são identificados apenas pelo serviço Compose e ordinal. Use configure_application_resource_thresholds após confirmação explícita para substituir limites de exibição opcionais. Valores omitidos limpam um limite; os limites apenas destacam medições e não impõem recursos, acionam ações no servidor ou afetam a cobrança. Defina email_enabled após confirmação explícita para enviar um e-mail de conta quando um limite for atingido e um quando for recuperado; medições repetidas acima do mesmo limite não reenviam.

Use configure_application_access para alterar como um aplicativo instalado é alcançado. Leia a instalação primeiro e passe sua revisão atual com uma nova chave de idempotência. platform_https aloca um hostname VPSnet opaco com DNS e HTTPS automáticos, private não tem listener público, public_http usa o IP público do servidor via HTTP, e managed_https usa uma zona DNS gerenciada pela VPSnet elegível. external_https registra um endereço HTTPS existente gerenciado pelo cliente; a VPSnet não configura nem valida seu DNS, certificado TLS ou proxy reverso.

Um acesso managed_https também pode listar additional_addresses (até 4 por endpoint, 8 por aplicativo): outros nomes nas zonas DNS VPSnet do próprio cliente, cada um com zone_id, name, action e approve_dns: true. Um name ou "@" vazio é o domínio nu da zona, então example.com pode ficar ao lado de www.example.com. action é redirect (padrão; um 301 para o endereço principal que mantém o caminho e a consulta) ou serve (abre o mesmo aplicativo). Adicionar ou remover um endereço adicional nunca altera o endereço principal. A lista é o conjunto desejado completo: uma alteração de acesso que omite additional_addresses remove os salvos, então passe-os novamente para mantê-los. Endereços adicionais são recusados em todos os outros modos de acesso, e a VPSnet não cobra nada por eles.

list_application_registry_credentials expõe apenas metadados de credenciais de registro privado. A criação e rotação de tokens de registro não são intencionalmente ferramentas MCP: use o painel VPSnet ou a API REST direta para que um token nunca entre em um prompt de modelo ou argumento de ferramenta. Os metadados podem identificar Docker Hub, GHCR ou um hostname de registro HTTPS personalizado exato.

Receitas de clientes são definições Compose de propriedade do cliente, separadas dos blueprints de catálogo da VPSnet. Elas podem ser validadas no worker alvo, salvas como revisões imutáveis, instaladas por meio do ciclo de vida gerenciado e exportadas sem valores secretos. Receitas de catálogo da VPSnet nunca são exportáveis. A descoberta de contêineres é limitada e somente leitura: ela relata contêineres de clientes e gerenciados sem retornar valores de ambiente ou montagens, e nunca adota ou modifica contêineres detectados. A adoção controlada é um fluxo separado de preparação, inspeção e confirmação explícita para um projeto Compose elegível. A aquisição inicial é única, mas sua vinculação exata de volume externo permanece assinada em ações posteriores do ciclo de vida. A recuperação reinicia a fonte somente após a substituição gerenciada estar conclusivamente contida; resultados incertos falham de forma segura.

Uma atualização imutável está disponível somente quando get_application_installation retorna uma entrada available_actions com type: "update". Após confirmação explícita do usuário, chame update_application com o expected_blueprint_version e expected_upstream_version anunciados exatos, e uma nova chave de idempotência. As chaves são globais ao cliente: reutilize uma chave apenas para repetir a mesma solicitação exata, nunca para outro serviço ou operação. O backend seleciona e congela a versão publicada elegível; o chamador não envia uma imagem, tag ou versão alvo.

Nenhum backup separado do aplicativo é criado. Em serviços Firecracker suportados, list_application_restore_points retorna pontos noturnos opacos de VM inteira consistentes com o aplicativo para a revisão exata da instalação atual. Visualizar pontos é gratuito, mas chaves de API exigem applications:manage, operações pagas habilitadas, escopo pago applications:restore e acesso total porque a resposta inclui o saldo da conta. quote_application_data_restore congela a cobrança exata sem debitar a conta. restore_application_data exige o token de cotação retornado, a mesma chave de idempotência e confirmação explícita de pagamento e substituição de dados. Chaves de API pagas também exigem applications:restore, operações pagas habilitadas e limites de gastos diários/mensais. Ele substitui apenas dados de aplicativos declarados derivados do worker, exclui segredos e dados não relacionados de Docker/servidor, e exige capacidade de reversão. Consulte get_application_data_restore; needs_attention permanece bloqueado e não deve ser tratado como sucesso. Essas ferramentas nunca aceitam ou expõem credenciais PBS, nomes de arquivos, dispositivos ou caminhos de sistema de arquivos.

As respostas de lista e detalhes de instalação carregam um bloco capabilities por plataforma — data_restore, console, compose_adoption, custom_projects e log_service_filter — além de um sinalizador access.capabilities.can_configure separado. Trate esses sinalizadores como a autoridade sobre o que uma instalação suporta em vez de tentar uma ação e ler a falha.

A desinstalação exclui permanentemente os contêineres gerenciados, configuração, credenciais salvas e dados do aplicativo; os backups existentes do servidor são retidos. A chamada uninstall_application exige acknowledge_data_loss=true, e ela só deve ser definida após confirmação explícita do usuário.

A superfície MCP é orientada a tarefas, em vez de um espelho um-para-um de cada rota REST. Integrações legadas de callback de micro-pagamento e macro-pagamento por SMS permanecem disponíveis por meio da API REST documentada e do painel de controle, mas são intencionalmente não expostas como ferramentas MCP. Rotas públicas de pedido pré-login e busca de domínios também têm equivalentes MCP autenticados onde uma operação de conta precisa deles.

Certificados TLS e SSL Automático

Os produtos de certificado não se limitam a aplicações gerenciadas. Pedidos portáteis de DV, OV e EV podem ser instalados em servidores web controlados pelo cliente, proxies, servidores de e-mail, balanceadores de carga, APIs ou outros sistemas compatíveis com TLS. Assinaturas automáticas de SSL, por outro lado, conectam um cliente ACME compatível na VPSnet ou em outro provedor e mantêm certificados de curta duração atualizados durante o período pago.

Contas elegíveis também podem solicitar certificados DV portáteis sem custo por meio de get_free_certificate_eligibility → preflight_free_certificate → create_free_certificate. Para implantação via API ou assistente, crie uma CSR no destino e mantenha a chave privada lá; o MCP aceita apenas a CSR pública e posteriormente retorna apenas a cadeia de certificados pública. Chaves gerenciadas pela VPSnet suportam renovação antecipada não assistida, mas sua exportação permanece somente no portal, protegida por verificação em duas etapas. Certificados gratuitos, arquivos de certificados pagos, SSL automático pago e HTTPS gerenciado de aplicações são produtos e superfícies de ciclo de vida separados.

Use list_certificate_catalog para distinguir portable_certificate de ofertas acme_subscription. O SSL automático segue quote_automatic_ssl_subscription → order_automatic_ssl_subscription, com a solicitação exata inalterada, token de cotação, chave de idempotência e aprovação explícita de pagamento. Leia o estado com list_automatic_ssl_subscriptions e get_automatic_ssl_subscription. Nomes adicionais usam quote_automatic_ssl_domain → order_automatic_ssl_domain; a API impede pagar duas vezes por nomes já cobertos pelas regras base/www ou curinga/base. Durante os últimos 30 dias, um próximo termo elegível usa quote_automatic_ssl_renewal → order_automatic_ssl_renewal e é pré-pago somente a partir do saldo da conta após a aprovação do total exato em EUR. Cancelamento, remoção de domínio e correção do mesmo tipo usam cancel_automatic_ssl_subscription, remove_automatic_ssl_domain e replace_automatic_ssl_domain; estado ambíguo é reconciliado com refresh_automatic_ssl_subscription, nunca inventando uma segunda mutação. Credenciais privadas do servidor ACME e EAB permanecem no portal do cliente protegido por duas etapas e estão intencionalmente indisponíveis para chaves de API e MCP, portanto não podem entrar no contexto do modelo.

Restaurando um serviço inteiro

request_restore é pago e destrutivo: ele cobra o preço da restauração do saldo da conta e sobrescreve o disco do serviço inteiro com o ponto de backup, perdendo tudo o que foi escrito desde então. É uma chamada de confirmação, não uma consulta de preço — a API recusa um corpo que não contenha uma confirmação explícita, e recusa a cobrança imediatamente se o preço mudou desde que foi divulgado.

Não há diálogo nesta superfície para coletar essa confirmação, então a ferramenta não a fabrica. acknowledge_data_replacement e acknowledge_restore_charge devem ser cada um true, e só devem ser definidos após o usuário ter realmente aprovado a substituição do disco e a cobrança — a mesma regra de acknowledge_data_loss em uninstall_application. Omitir qualquer um deles é um erro de esquema, então um chamador não assistido não pode cair em uma cobrança: nada é sequer cotado.

expected_total_charged é o total_charged com IVA incluído que você leu de get_restore_status e mostrou ao usuário, passado de volta inalterado. Não releia logo antes da chamada: ele deve ser o valor que o cliente concordou, e um número recém-buscado concordaria com qualquer que seja o preço atual e anularia a verificação completamente. Se o preço mudou, a restauração é recusada como restoreQuoteChanged com o total atual e nada é cobrado; divulgue o novo valor, obtenha aprovação novamente e tente novamente.

Navegando dentro de um backup

Olhar dentro de um backup é gratuito e completamente separado de pagar para restaurar um. list_restore_file_points, browse_restore_files e get_restore_file_browse apenas leem a listagem de diretórios de um backup: eles nunca cobram da conta, nunca sobrescrevem o disco e nunca colocam um arquivo de volta no servidor. Inicialmente suportado em VPS Firecracker.

A navegação é assíncrona. browse_restore_files cria um trabalho persistido e enfileira atividade do worker, então sua anotação MCP é readOnlyHint: false mesmo que o backup e o servidor em execução permaneçam inalterados. Ele retorna um ID de navegação em um estado pendente; consulte get_restore_file_browse até que state seja succeeded. As entradas existem apenas nesse estado — uma navegação failed carrega um errorCode e nenhuma listagem, e não deve ser apresentada como um diretório vazio.

Diretórios podem conter um número enorme de arquivos, então o servidor seleciona páginas de 200 ou 1.000 entradas de acordo com a capacidade do worker. Quando result.nextOffset não é nulo, chame novamente com o mesmo sourceBrowseId e directoryEntryId e defina offset para esse cursor. Use result.pageSize em vez de assumir 200 ao retroceder. Subdiretórios são acessados com o id opaco de uma entrada type: "directory"; caminhos de sistema de arquivos nunca são aceitos. Os tipos de entrada são file, directory, symlink e unsupported.

A pesquisa de pastas (o argumento filter) corresponde aos nomes das entradas no diretório que está sendo listado — substring sem diferenciar maiúsculas de minúsculas, nunca um caminho, nunca recursivo. Ela depende de uma capacidade do worker que nós mais antigos não relatam, então list_restore_file_points retorna searchAvailable. browse_restore_files verifica esse sinalizador antes de enviar um filtro e falha com serviceFileBrowseSearchUnavailable quando a pesquisa não é suportada, em vez de retornar silenciosamente uma listagem sem filtro que seria confundida com resultados de pesquisa. A navegação simples continua funcionando nesses nós.

Restaurar arquivos selecionados de volta ao servidor é uma operação paga e é deliberadamente não exposta aqui; use o painel da VPSnet para isso.

Fluxo de trabalho de acesso SSH

Este servidor MCP gerencia sua infraestrutura de VPS por meio da API da VPSnet.com, incluindo provisionamento de chaves SSH. Depois que uma chave SSH é implantada em uma VPS, o assistente de IA pode se conectar diretamente usando o terminal do seu ambiente (por exemplo, a ferramenta Bash do Claude Code, o terminal do Cline).

Fluxo típico:

1. A IA lê a chave pública da máquina local (~/.ssh/id_rsa.pub)
2. Envia para a VPSnet.com via create_ssh_key
3. Implanta em uma VPS via deploy_ssh_key com permissão explícita de vm:exec para OAuth remoto (ou a passa ao fazer o pedido com order_service)
4. Conecta diretamente: ssh root@<vps_ip>

A maioria dos ambientes de codificação de IA (Claude Code, Cline, Cursor, Codex) tem acesso integrado ao terminal, então a IA pode usar SSH na sua VPS imediatamente após implantar uma chave — sem ferramentas extras necessárias.

Para ambientes sem acesso SSH nativo, combine isso com mcp-server-ssh para conectividade direta ao servidor via ferramentas MCP.

Configuração combinada:

{
  "mcpServers": {
    "vpsnet": {
      "command": "npx",
      "args": ["-y", "vpsnet-mcp"],
      "env": {
        "VPSNET_API_KEY": "your_api_key_here"
      }
    },
    "ssh": {
      "command": "npx",
      "args": ["-y", "mcp-server-ssh"]
    }
  }
}

Começando

Escolha seu ambiente:

• Claude Code (CLI) — Codificação de IA baseada em terminal
• Claude Code para VS Code — Extensão do VS Code
• Claude Desktop — Aplicativo de desktop
• VS Code com GitHub Copilot — Modo agente do Copilot
• Cline / Cursor / Windsurf / Roo Code / Codex — Outros clientes

A configuração padrão funciona na maioria dos clientes MCP:

{
  "mcpServers": {
    "vpsnet": {
      "command": "npx",
      "args": ["-y", "vpsnet-mcp"],
      "env": {
        "VPSNET_API_KEY": "your_api_key_here",
        "VPSNET_API_TIMEOUT_MS": "45000"
      }
    }
  }
}

claude mcp add vpsnet -- npx -y vpsnet-mcp

export VPSNET_API_KEY="your_api_key_here"
export VPSNET_API_TIMEOUT_MS="45000"

npm install -g @anthropic-ai/claude-code

claude mcp add vpsnet -- npx -y vpsnet-mcp

"vpsnet": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "vpsnet-mcp"],
    "env": {
        "VPSNET_API_KEY": "your_api_key_here",
        "VPSNET_API_URL": "https://api.vpsnet.com"
    }
}

{
  "mcpServers": {
    "vpsnet": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "vpsnet-mcp"],
      "env": {
        "VPSNET_API_KEY": "your_api_key_here"
      },
      "disabled": false
    }
  }
}

codex mcp add vpsnet --env VPSNET_API_KEY=your_api_key_here -- npx -y vpsnet-mcp

[mcp_servers.vpsnet]
command = "npx"
args = ["-y", "vpsnet-mcp"]

[mcp_servers.vpsnet.env]
VPSNET_API_KEY = "your_api_key_here"

codex mcp add vpsnet --env VPSNET_API_KEY=your_api_key_here -- bash -lc 'source ~/.nvm/nvm.sh >/dev/null 2>&1 && nvm use --silent 20 && npx -y vpsnet-mcp'

{
  "mcpServers": {
    "vpsnet": {
      "command": "npx",
      "args": ["-y", "vpsnet-mcp"],
      "env": {
        "VPSNET_API_KEY": "your_api_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "vpsnet": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "vpsnet-mcp"],
      "env": {
        "VPSNET_API_KEY": "your_api_key_here"
      },
      "disabled": false
    }
  }
}

code --add-mcp '{"name":"vpsnet","command":"npx","args":["-y","vpsnet-mcp"],"env":{"VPSNET_API_KEY":"your_api_key_here"}}'

Usuários do Windows

• Use PowerShell ou CMD (não Git Bash) para comandos claude mcp add
• Local do arquivo de configuração: C:\Users\<YourUsername>\.claude.json
• Instale o Node.js: winget install OpenJS.NodeJS.LTS ou baixe de nodejs.org
• Após instalar o Node.js, reinicie seu terminal e o VS Code
• Variáveis de ambiente na extensão Claude Code devem estar no objeto env dentro de .claude.json, NÃO em variáveis de ambiente do sistema

Variáveis de ambiente

As solicitações saem da máquina que executa este servidor, não do seu navegador. Uma implantação que restringe o acesso por endereço de origem pode responder a uma solicitação bloqueada com uma página HTML 403 do seu servidor web; o resultado da ferramenta então diz isso (non_api_response: true, http_status: 403) em vez de passar a página adiante. Todo resultado de erro carrega http_status; um 429 também carrega retry_after.

Autenticação, escopos e operações pagas

Toda solicitação é enviada com o cabeçalho X-API-KEY (VPSNET_API_KEY).

• Use uma chave de gerenciamento. Seu nível de acesso é full (leitura e alteração) ou read (somente GET). Uma chave com escopo de IA é emitida apenas para inferência do assistente de IA do VPSnet e é recusada em todas as rotas de conta, então nenhuma ferramenta aqui funciona com ela; o resultado de erro traz auth_problem com o motivo e a correção.
• Escopos granulares apenas restringem uma chave. Uma chave com lista de escopos vazia mantém tudo o que seu nível de acesso permite; listar escopos (por exemplo, dns:read, services:manage) a restringe. X:manage inclui X:read. Rede é a exceção: networking:read / networking:manage / networking:order nunca são implícitos por full ou read e devem ser concedidos explicitamente.
• Operações pagas são uma etapa separada. Uma ferramenta marcada como Paid ou Quote nas tabelas abaixo precisa de uma chave com acesso full, paid_operations_enabled, o escopo pago nomeado (vps:order, vds:order, ds:order, fc:order, domains:order, domains:renew, domains:transfer, certificates:order, applications:restore, services:restore, fn:invoke, networking:order), limites de gastos diários e mensais configurados, e um idempotencyKey estável (reutilize a mesma chave para repetir uma tentativa incerta, nunca uma nova). Pedidos seguem cotação e depois confirmação com o quoteToken retornado; divulgue o total exato em EUR ao usuário antes de confirmar. Use list_api_keys para ver os escopos da sua chave, escopos pagos, limites e taxa de requisições.
• Limites de taxa. Requisições são limitadas por chave (rate_limit em list_api_keys, requisições por minuto). Em HTTP 429, aguarde e tente novamente após retry_after segundos em vez de tentar imediatamente.
• Chaves de API nunca podem criar, alterar ou revogar chaves de API, e nunca recebem acesso de administrador.

Ferramentas

As tabelas abaixo são geradas: edite scripts/tool-scopes.json (ou o registro da ferramenta) e execute npm run docs:tools; npm test falha quando elas divergem.

Escopo é o escopo granular de chave de API que a ferramenta precisa (none = qualquer chave de gerenciamento; a + b = ambos; a or b = qualquer um, dependendo do objeto). Pago: Paid: x gasta o saldo da conta e precisa do escopo pago x além das etapas acima; Quote: x cria uma cotação de preço sem cobrar, mas é limitado da mesma forma; Paid sozinho cobra o saldo com uma chave de acesso full e sem escopo pago separado; Needs paid scope: x é uma leitura que expõe dados de saldo ou preço; Billed while kept significa gratuito por uma janela inicial, depois medido; free é todo o resto.

Conta

Serviços

Aplicações Gerenciadas

Ações de Serviço

Configurações de Serviço

Reinstalação do SO

Alterações de Plano (gratuitas)

Renovação e Cobrança

Pedidos

Backups

Restauração

Chaves SSH

Chaves de API

A criação, alteração e revogação de chaves de API exigem login por navegador/sessão. Elas não podem ser realizadas por uma conexão MCP autenticada com uma chave de API.

Certificados TLS gratuitos

Para instalação portátil de API ou assistente, use customer_csr e retenha a chave privada onde o CSR foi gerado. Uma solicitação gerenciada pode renovar sem supervisão, mas o MCP não pode exportar sua chave privada. A emissão é assíncrona e limitada por cota: consulte get_free_certificate, siga get_free_certificate_instruction e não trate uma solicitação enfileirada como emitida.

Assinaturas SSL automáticas

SSL automático é uma assinatura ACME paga portátil. Funciona com um cliente compatível no VPSnet ou em outro provedor; não se limita a aplicações gerenciadas. A URL privada do servidor ACME e as credenciais EAB são reveladas apenas no portal do cliente protegido por dois fatores. Elas não são intencionalmente uma ferramenta MCP ou resposta de chave de API, então um assistente não pode copiá-las para o contexto do modelo.

Certificados TLS pagos

Certificados pagos são produtos de conta portáteis: os clientes podem instalá-los em Nginx, Apache, lighttpd, OpenLiteSpeed, HAProxy, Caddy, correio, API, balanceador de carga ou outros endpoints TLS. Eles são separados de HTTPS automático anexado a uma aplicação gerenciada pelo VPSnet. O MCP aceita apenas um CSR PKCS#10 público; a chave privada deve permanecer sob controle do cliente e nunca deve entrar em um argumento de ferramenta ou contexto de modelo. As respostas de orçamento contêm o preço final ao cliente em EUR, e o pedido requer aprovação explícita mais a mesma chave de idempotência e token de orçamento de curta duração.

Domínios

DNS

Snapshots

Resgate de Serviço

Funções Firecracker

Servidores sob demanda

O pedido pelo cliente está desativado enquanto o ciclo de vida do servidor sob demanda está sendo validado. As opções atuais informam que backups automáticos e snapshots não estão incluídos e que conexões de saída para portas TCP de entrega de e-mail 25, 2525, 465 e 587 são restritas. Sessões existentes permanecem disponíveis por meio de listar/obter/excluir para limpeza. Campos de TTL fixo e pré-pagos no esquema de compatibilidade desativado não são uma promessa de lançamento; o contrato de duração flexível e cobrança medida deve ser publicado de forma consistente antes que o pedido seja ativado.

Guest Agent

Histórico

Público

Rede SDN

As permissões de rede devem ser concedidas explicitamente: networking:read ou networking:manage; os padrões comuns de acesso total/leitura não as incluem. Comece pelas capacidades, depois leia o recurso pertencente exato e sua geração. O backend aplica propriedade do locatário, disponibilidade e bloqueios de 2FA do servidor. Aceito, pago e pronto são estados separados; consulte a operação ou recurso correspondente. Alterações de DNS são consultadas por meio do settings.dns_change da rede.

Novos balanceadores de carga privados/públicos, VPNs e endereços públicos usam um fluxo explícito de orçamento → checkout comum → status do pedido. Ferramentas de orçamento sempre enviam prepare_after_payment=true: nenhum provisionamento ocorre antes do pagamento. Mostre o valor exato em EUR gross_amount do orçamento, obtenha aprovação e passe o mesmo idempotencyKey, quote_id e quoteToken para order_network_product. Chaves de API adicionalmente precisam de acesso total, operações pagas habilitadas, networking:order e limites de gastos. Leia get_network_payment_methods e selecione system=balance; checkout sem saldo é recusado para chaves de API. Se a confirmação for incerta, recupere pelo ID e chave do orçamento original. Para um pedido SDN com status=paid_pending, billing_state=captured e reason_code=network_product_ip_inventory_wait, o pagamento é retido enquanto o inventário de IP público estiver indisponível. Consulte get_network_product_order com o mesmo ID do pedido; o backend retoma automaticamente quando o inventário retorna. Não crie outro pedido, cobre novamente ou envie uma nova tentativa manual. manual_review ou network_product_stock_reconciliation_required em vez disso exige revisão do operador; não autoriza uma nova tentativa automática.

Pedidos comuns de VPS expõem essa espera por meio de get_service.stateProcess.waitingReason=public_ip_inventory (também espelhado no campo legado stateProccess). Consulte o mesmo serviço sem refazer o pedido. stateProcess.attention=true exige atenção do operador. Um pagamento bem-sucedido ou criação aceita não estabelece que o servidor está pronto. Camadas públicas de balanceador de carga alb_proxy_3/alb_proxy_5 usam o tipo de solicitação proxy_lb; a camada privada nlb usa private_lb. Disponibilidade e preços vêm do catálogo de produtos ao vivo. Um endpoint legado não pago de criação de appliance não é uma alternativa ao checkout.

A coleta de configuração do dispositivo é uma ação de gerenciamento única, mesmo que seu método HTTP seja GET. Gere o par de chaves de revelação fora do MCP, envie apenas a chave pública X25519, salve o texto cifrado selado retornado e descriptografe-o fora da conversa. Nem chaves privadas nem configuração WireGuard em texto simples são solicitadas ou descriptografadas por essas ferramentas. Nunca repita automaticamente uma coleta após uma resposta incerta.

O backend atual não tem renomeação de rede do cliente, edição de IP fixo em porta existente, repetição de appliance ou API nativa de site a site nesta versão. Endereços DHCP fixos são selecionados na anexação; remover/recriar uma anexação requer aprovação separada e não é representado como uma edição no local. Rotas legadas não pagas de criação de LB/VPN, compras legadas de estoque antes do pagamento e ativação de renovação automática por meio de chaves de API não são expostas deliberadamente. O gerenciamento existente de bindings públicos permanece disponível; novos endereços públicos usam propriedade de conta e checkout comum. Uma ferramenta listada não habilita um recurso de backend.| Ferramenta | Descrição | Escopo | Pago | |------|-------------|-------|------| | get_network_payment_methods | Ler metadados do método de pagamento sem iniciar o pagamento | nenhum | gratuito | | get_networking_capabilities | Ler disponibilidade de rede da conta, cota, opções de criação e anexos elegíveis no momento do pedido | networking:read | gratuito | | get_networking_features | Ler os portões de recursos de rede atuais, opções de DNS e extensões de contrato suportadas. | networking:read | gratuito | | get_networking_overview | Ler redes próprias, cota e instantâneo de operações | networking:read | gratuito | | get_networking_topology | Ler a topologia da conta com identidades com escopo de rede | networking:read | gratuito | | list_networking_operations | Ler operações de rede recentes e operations_has_more | networking:read | gratuito | | get_networking_operation | Ler uma operação de rede ou porta aceita | networking:read | gratuito | | list_private_networks | Listar redes privadas próprias, incluindo exclusão pendente de limpeza verificada. | networking:read | gratuito | | get_private_network | Ler uma rede própria, incluindo reservas DHCP, progresso de alteração de DNS, geração e project_id. | networking:read | gratuito | | create_private_network | Criar uma intenção de rede privada | networking:manage | gratuito | | delete_private_network | Solicitar exclusão de uma rede vazia | networking:manage | gratuito | | retry_private_network | Repetir apenas a operação de rede atual com falha; preservar sua geração atual | networking:manage | gratuito | | set_private_network_dns | Alterar servidores DNS DHCP no local | networking:manage | gratuito | | set_private_network_names | Substituir o rótulo completo da zona DNS interna e a lista de aliases | networking:manage | gratuito | | list_private_network_ports | Ler portas de rede próprias, seus endereços DHCP fixos, gerações e estados de anexo | networking:read | gratuito | | list_service_private_ports | Ler portas privadas e estado de recuperação de anexo de pedido para um número de pedido de serviço próprio. | networking:read | gratuito | | list_network_attachment_candidates | Ler serviços anexáveis e cada attachment_mode | networking:read | gratuito | | attach_private_network_port | Anexar um serviço próprio; omitir ipv4 para alocação automática ou passar um endereço utilizável fixo | networking:manage | gratuito | | detach_private_network_port | Desanexar a porta do servidor próprio | networking:manage | gratuito | | retry_private_network_port | Repetir a operação de porta atual com falha usando a geração PORT e qualquer aprovação de reinicialização necessária. | networking:manage | gratuito | | get_network_vpn_summary | Ler o resumo VPN da rede, incluindo ausência verdadeira | networking:read | gratuito | | get_network_routed_egress | Ler o acesso NAT/internet desta rede, endereço público e estado de qualificação. | networking:read | gratuito | | set_network_routed_egress | Solicitar a transição NAT atualmente suportada para uma rede própria; o backend pode recusar alterações de modo | networking:manage | gratuito | | get_security_group_capabilities | Ler disponibilidade de grupos de segurança e se a política padrão da rede pode ser alterada. | networking:read | gratuito | | list_network_security_groups | Listar grupos no projeto próprio | networking:read | gratuito | | create_network_security_group | Criar um conjunto de regras de permissão nomeado | networking:manage | gratuito | | update_network_security_group | Substituir o nome completo do grupo e a lista de regras na revisão esperada | networking:manage | gratuito | | delete_network_security_group | Excluir um grupo de cliente não referenciado na revisão esperada; grupos referenciados são recusados. | networking:manage | gratuito | | clone_network_security_group | Clonar um grupo próprio para um novo nome; usar a revisão atual do grupo de origem. | networking:manage | gratuito | | get_network_security_policy | Ler política padrão, grupos atribuídos e estado de aplicação da política | networking:read | gratuito | | set_network_default_security_policy | Alterar aceitar/negar para servidores sem grupos personalizados | networking:manage | gratuito | | set_private_port_security_groups | Substituir a lista completa de grupos de cliente da porta | networking:manage | gratuito | | retry_network_security_policy | Repetir a política de segurança de rede com falha usando seu estado desejado atual. | networking:manage | gratuito | | retire_network_security_policy | Aposentar a política somente após as portas do servidor serem removidas | networking:manage | gratuito | | get_network_appliance_capabilities | Ler provedores/camadas de balanceador de carga disponíveis, qualificação pública, capacidades VPN e cota | networking:read | gratuito | | list_network_appliances | Ler balanceadores de carga próprios e gateways VPN com um cursor de fluxo. | networking:read | gratuito | | get_network_appliance_billing | Ler linhas de aparelhos recorrentes visíveis ao cliente e moeda. | networking:read | gratuito | | get_network_appliance_operation | Consultar uma operação de aparelho aceita | networking:read | gratuito | | list_network_load_balancers | Listar balanceadores de carga privados e públicos e estado de saúde/qualificação seguro para o cliente. | networking:read | gratuito | | get_network_load_balancer | Ler um balanceador de carga próprio, listeners, membros, geração e saúde | networking:read | gratuito | | estimate_network_load_balancer | Ler uma estimativa técnica de balanceador de carga para esta configuração exata | networking:read | gratuito | | delete_network_load_balancer | Solicitar desmontagem do aparelho na geração atual; isso não é reembolso ou cancelamento de período pago | networking:manage | gratuito | | add_network_load_balancer_member | Adicionar um endereço de servidor privado anexado ao listener selecionado; o backend valida a associação nesta rede. | networking:manage | gratuito | | remove_network_load_balancer_member | Remover um membro da rotação usando a geração do balanceador de carga. | networking:manage | gratuito | | add_network_load_balancer_listener | Adicionar um listener e membros iniciais opcionais usando capacidades de protocolo atualmente oferecidas | networking:manage | gratuito | | remove_network_load_balancer_listener | Remover um listener e seus membros; excluir o último listener é recusado. | networking:manage | gratuito | | list_network_vpn_gateways | Listar gateways VPN próprios, seus peers de dispositivo e status seguro | networking:read | gratuito | | get_network_vpn_gateway | Ler um gateway VPN próprio, geração atual, peers de dispositivo, candidatos a concessão e capacidade de anexo. | networking:read | gratuito | | delete_network_vpn_gateway | Solicitar desmontagem de um gateway VPN próprio; todos os dispositivos perdem conectividade | networking:manage | gratuito | | attach_network_vpn_gateway | Anexar ou mover uma VPN de conta para uma rede própria somente quando o anexo autônomo for anunciado | networking:manage | gratuito | | detach_network_vpn_gateway | Desanexar uma VPN de conta de sua rede quando suportado; ela mantém seu período pago e dispositivos, mas recria o gateway | networking:manage | gratuito | | set_vpn_server_access | Escolher accept ou groups_only para o acesso da VPN a servidores anexados quando essa capacidade estiver disponível | networking:manage | gratuito | | create_network_vpn_peer | Adicionar um dispositivo com uma chave de revelação PÚBLICA única gerada externamente | networking:manage | gratuito | | take_network_vpn_peer_config | Consumir a configuração selada do dispositivo UMA VEZ | networking:manage | gratuito | | revoke_network_vpn_peer | Revogar um dispositivo usando a geração do GATEWAY VPN | networking:manage | gratuito | | set_network_vpn_peer_grants | Substituir a lista completa de servidores alcançáveis do dispositivo quando VPN autônoma estiver disponível | networking:manage | gratuito | | get_network_vpn_egress_options | Ler saídas de Internet VPN suportadas e qualificação | networking:read | gratuito | | set_network_vpn_peer_egress | Definir a política de saída escolhida do dispositivo: somente privada, NAT herdado ou anunciada | networking:manage | gratuito | | list_network_products | Ler produtos pagos atuais, nomes de camadas ao vivo, preços e capacidade de compra; ofertas públicas de balanceador de carga proxy 3/5 nós devem vir deste catálogo. | networking:read | gratuito | | list_network_product_periods | Ler períodos de produtos próprios, disponibilidade de renovação e fatos do ciclo de vida. | networking:read | gratuito | | quote_network_product | Criar a cotação paga exata do produto de rede para CHECKOUT COMUM | networking:manage | Cotação: networking:order | | quote_account_vpn | Criar uma cotação de VPN de conta para checkout comum quando vpn_account_order for anunciado | networking:manage | Cotação: networking:order | | order_network_product | Confirmar uma compra de checkout comum a partir de uma cotação exata aprovada | networking:manage | Pago: networking:order | | get_network_product_order | Ler o estado de pagamento e cumprimento de um pedido de checkout comum próprio | networking:read | gratuito | | find_network_product_order | Recuperar um checkout incerto pelo quote_id ORIGINAL; order=null significa que nenhum pedido foi encontrado, não prova para usar uma nova chave de pagamento. | networking:read | gratuito | | quote_network_product_renewal | Cotar o próximo mês pago para um produto de rede; sem cobrança | networking:manage | Cotação: networking:order | | renew_network_product | Pagar a renovação exata previamente divulgada do saldo da conta | networking:manage | Pago: networking:order | | disable_network_product_auto_renew | Desativar renovação automática | networking:manage | gratuito | | quote_vpn_period_renewal | Cotar o próximo mês da VPN no escopo pago real; sem cobrança | networking:manage | Cotação: networking:order | | renew_vpn_period | Pagar a renovação aprovada do próximo mês da VPN do saldo da conta usando a cotação exata e a chave original. | networking:manage | Pago: networking:order | | disable_vpn_auto_renew | Desativar a renovação automática da VPN; o período pago atual permanece | networking:manage | gratuito | | list_network_public_addresses | Ler endereços públicos pagos próprios, limites da conta, suporte de destino e disponibilidade de compra. | networking:read | gratuito | | get_network_public_address | Ler um endereço público próprio, anexo e estado do período pago. | networking:read | gratuito | | quote_network_public_address | Cotar um novo endereço público pago para checkout comum; sem cobrança | networking:manage | Cotação: networking:order | | attach_public_address_to_network | Anexar ou mover um endereço já pago ao NAT de uma rede própria | networking:manage | gratuito | | attach_public_address_to_server | Anexar ou mover um endereço público pago próprio para a porta privada elegível de um servidor com zero IP público | networking:manage | gratuito | | detach_network_public_address | Desanexar um endereço público próprio do destino atual; ele permanece próprio pelo período pago | networking:manage | gratuito | | quote_public_address_renewal | Cotar o próximo mês do endereço sem cobrar; usar a cotação retornada e esta chave para confirmação. | networking:manage | Cotação: networking:order | | renew_network_public_address | Pagar a renovação aprovada do endereço do saldo com seu ID/token de cotação exato e chave original. | networking:manage | Pago: networking:order | | disable_public_address_auto_renew | Desativar renovação automática do endereço; a propriedade dura até paid_until | networking:manage | gratuito | | get_network_public_binding | Ler a geração, estado e endereço atribuído de um vínculo público próprio existente | networking:read | gratuito | | bind_network_public_ip | Vincular um vínculo público flutuante já reservado a uma porta privada própria quando suportado | networking:manage | gratuito | | move_network_public_ip | Mover um vínculo público flutuante preparado para outra porta privada própria; confirmar interrupção ao destino antigo. | networking:manage | gratuito | | configure_network_public_forwarding | Configurar os listeners TCP/UDP de um vínculo de encaminhamento reservado existente | networking:manage | gratuito | | delete_network_public_binding | Solicitar exclusão de um vínculo existente usando sua geração | networking:manage | gratuito |

Exemplos trabalhados

Cada exemplo é uma solicitação ao seu assistente e as ferramentas que ele chama.

Pedir um VPS (cotação, depois confirmação)

Pedir o Cloud VPS mais barato com Debian e minha chave SSH, pago do saldo.

1. get_order_plans para o produto, depois get_order_options para o plano escolhido (SO, período, IDs de recursos) e list_ssh_keys para o ID da chave.
2. order_service com plan, os, period, resources, sshKey (ou rootPassword, não ambos), payment: { payment: 1, successUrl: '', cancelUrl: '' } e um idempotencyKey estável. A primeira chamada retorna um orçamento sem cobrança. A chave de API precisa de vps:order (ou vds:order, ds:order, fc:order) e limites de gastos.
3. Mostre o total exato em EUR bruto e o período de cobrança. Após a aprovação do cliente, repita o pedido e a chave inalterados com o quoteToken retornado, expected_total_eur e acknowledge_charge: true. Inspecione a tentativa original no painel se o resultado for desconhecido; não crie outra chave para tentar novamente.
4. Consulte get_service para o número do pedido retornado; pagamento aceito não é servidor pronto.

Rede (orçamento, depois pedido)

Adicione um balanceador de carga privado à minha rede e pague pelo saldo.

1. get_networking_capabilities, list_network_products e get_network_payment_methods (escolha o método system=balance).
2. quote_network_product com kind (private_lb, proxy_lb ou vpn_gateway), tier e um idempotencyKey; mostre o gross_amount em EUR do orçamento.
3. Após a aprovação, order_network_product com o mesmo idempotencyKey, quote_id, quoteToken, o payment do saldo e acknowledge_charge: true. Se o resultado for incerto, find_network_product_order pelo quote_id original, depois consulte get_network_product_order. Nunca compre uma segunda cópia.

Atualização de registro DNS

Aponte www.example.com para 203.0.113.10 com TTL de 5 minutos.

1. list_dns_zones para encontrar o zone_id, depois get_dns_zone para inspecionar os registros existentes e seus IDs (precisa de dns:read).
2. Para adicionar um valor A, chame upsert_dns_record com zone_id, name: "www", type: "A", content: "203.0.113.10", ttl: 300 (precisa de dns:write). Conteúdo diferente adiciona outro registro e mantém os valores existentes. Um tupla nome/tipo/conteúdo idêntica atualiza seu TTL/comentário e o reativa se estiver desabilitado. Para substituir um valor existente, use update_dns_record com seu record_id exato e o nome, tipo, conteúdo e TTL desejados.
3. get_dns_zone para ler os registros desejados de volta, ou get_dns_zone_history para ver a alteração.

Para uma zona pendente cujo valor TXT de propriedade foi perdido, primeiro leia get_dns_zone.zone.verification.record.value. Use reissue_dns_zone_verification somente se esse valor for nulo/irrecuperável ou o cliente solicitar rotação. Ele suporta tanto pending_verification quanto verification_expired; o valor anterior deixa de ser aceito. Atualize o TXT no local fornecido por zone.verification.next_step, depois chame verify_dns_zone. Reemitir sozinho não verifica a zona nem redefine seu status.

Pedir um certificado pago

Compre um certificado DV de um ano para example.com; eu mesmo gerei o CSR.

1. list_certificate_catalog e get_certificate_catalog_product para escolher um produto e ler sua oferta atual em EUR.
2. quote_certificate com product_id, offer_id, offer_generation, common_name (mais qualquer alternative_names), o csr público PKCS#10, os IDs de contato de propriedade e um idempotencyKey (precisa de certificates:order, operações pagas e limites). Nunca envie uma chave privada.
3. Após o usuário aprovar o total exato, order_certificate com a mesma solicitação, o mesmo idempotencyKey, o quote_token, o payment e acknowledge_exact_quote_and_payment: true.
4. get_certificate_validation (publique o desafio, por exemplo através de upsert_dns_record), depois download_certificate assim que for emitido.

Obtendo uma chave de API

1. Faça login em vpsnet.com
2. Vá para Conta > Chaves de API
3. Clique em Criar chave de API
4. Dê um nome e copie a chave

A chave é mostrada apenas uma vez — armazene-a com segurança.

Solução de problemas

Ferramentas MCP não aparecendo na extensão Claude Code do VS Code

1. Instale o CLI do Claude Code: npm install -g @anthropic-ai/claude-code
2. Verifique: claude --version deve mostrar um número de versão
3. Adicione o servidor via CLI: claude mcp add vpsnet -- npx -y vpsnet-mcp
4. Reinicie completamente o VS Code (não apenas recarregue a janela)
5. Verifique ~/.claude.json para configuração correta

claude: command not found

Instale o CLI do Claude Code globalmente:

npm install -g @anthropic-ai/claude-code

Verifique se seu PATH inclui pacotes globais do npm. No Windows, reinicie o terminal após a instalação.

Variáveis de ambiente não funcionando

Para a extensão do Claude Code, as variáveis de ambiente devem estar no objeto env dentro de .claude.json, NÃO nas variáveis de ambiente do sistema:

"vpsnet": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "vpsnet-mcp"],
    "env": {
        "VPSNET_API_KEY": "your_actual_key_here"
    }
}

Erros de chave de API

Este servidor precisa de uma chave de API de gerenciamento. Cada falha abaixo é relatada pelas ferramentas com um objeto auth_problem contendo a causa e a correção, então leia isso em vez de adivinhar pelo status HTTP.

Falhas de ferramentas carregam isError: true enquanto preservam os detalhes do erro da API e orientações de recuperação. Resultados desconhecidos de mutações devem ser verificados antes de outra tentativa. Números de pedidos de serviço devem ser copiados de list_services; letras ASCII, dígitos e hífens são suportados, incluindo sufixos de múltiplos pedidos. Identificadores de URL malformados ou superdimensionados são rejeitados antes de uma solicitação de API.

• Verifique se a chave está correta (começa com vpsnet_ seguido de 43 caracteres)
• As chaves são mostradas apenas uma vez na criação — se perdida, crie uma nova
• Verifique se a chave não expirou (Conta > Chaves de API)

deploy_ssh_key foi bem-sucedido, mas o SSH ainda falha

• Todos os servidores VPSnet.com usam root como nome de usuário SSH
• A implantação da chave é assíncrona — aguarde 15-30 segundos após implantar antes de tentar SSH

fetch is not defined ou erros inesperados

Este servidor requer Node.js 20+. Se seu node padrão for mais antigo (comum com configurações nvm), ou:

• Defina Node 20+ como padrão: nvm alias default 20
• Ou use o wrapper nvm mostrado na seção Codex

Licença

MIT