VPSnet

vpsnet-mcp

Model Context Protocol (MCP) servidor para gestionar los servicios de VPSnet.com. Proporciona a los asistentes de IA acceso a operaciones del ciclo de vida de VPS, aplicaciones gestionadas, zonas DNS, registro de dominios y contactos, facturación, metadatos de claves API, aprovisionamiento de claves SSH y herramientas de cuenta relacionadas a través de la API de VPSNet.

Características

• Más de 280 herramientas que cubren la gestión de servicios VPSNet, aplicaciones gestionadas, certificados TLS gratuitos y de pago, suscripciones SSL automáticas, DNS, dominios, facturación, claves API y operaciones de cuenta
• Gestión de cuenta y perfil
• Ciclo de vida de VPS (iniciar, detener, reiniciar, reinstalar sistema operativo)
• Cambios de plan (actualizaciones/descensos gratuitos; los discos KVM/Firecracker no se pueden reducir)
• DNS inverso del servicio (registros rDNS/PTR)
• Zonas DNS directas, registros, DNSSEC, plantillas, importación/exportación y tokens DDNS
• Disponibilidad de dominios, contactos, cotizaciones de registro/transferencia/renovación/restauración y confirmaciones de pago
• Aplicaciones gestionadas con publicación controlada, que incluyen instalación, estado, eventos y acciones de ciclo de vida tipadas
• Gestión de claves SSH: implementar claves y obtener acceso directo al servidor
• Inspección de metadatos de claves API (la creación, cambios y revocación de claves siguen siendo solo de sesión)
• Copias de seguridad, facturación, recibos
• Solicitud de nuevas instancias VPS
• Estado del sistema y precios

Conector OAuth remoto

El perfil remoto también incluye gestión de DNS, dominios y certificados con alcance limitado, claves SSH públicas, recuperación de servidores y exploración de copias de seguridad. Utiliza las mismas API de cliente que el panel; los permisos se aplican en el backend en cada solicitud.

El conector remoto utiliza https://mcp.vpsnet.com/mcp y el consentimiento del cliente a través de VPSnet. Consulte Conexiones de IA remotas para la configuración de la conexión, permisos y operaciones admitidas.

El README del plugin distribuible, los manifiestos y las habilidades están en inglés. Consulte preparación del directorio para la validación de paquetes y requisitos del editor, y casos de uso admitidos para escenarios de servidor, aplicación y red. La publicación en el directorio y la disponibilidad de la cuenta del proveedor son independientes de la instalación de este código fuente.

Consulte Configuración de clientes de IA para Gemini CLI, Cursor, Kimi Code, Kiro, Cline y otros clientes OAuth remotos. Sus paquetes comparten el mismo punto de conexión de VPSnet y las habilidades de tareas. El paquete npm proporciona el servidor MCP local; los paquetes de plugin instalables también incluyen el manifiesto y las habilidades de la aplicación de IA.

Compile todos los paquetes de clientes con python3 scripts/package-distribution.py. La salida incluye sumas de verificación e identifica cada formato. Los materiales de presentación al directorio público están en el kit de catálogo.

Realizar pedidos utiliza la conexión VPSnet existente, con permisos de compra controlados por el cliente y límites de gasto. La IA muestra el precio final y solicita aprobación antes de cargar el saldo de la cuenta. La disponibilidad sigue las reglas de distribución de la aplicación.

Las instrucciones a continuación describen el cliente local existente de stdio/clave API.

Requisitos previos

Antes de instalar, asegúrese de tener:

1. Node.js 20 o más reciente

   • Verificar: node --version
   • Linux/macOS: nodejs.org o su gestor de paquetes
   • Windows: winget install OpenJS.NodeJS.LTS o descargue desde nodejs.org
   • Después de instalar Node.js, reinicie su terminal/editor

2. Para usuarios de Claude Code (extensión CLI o VS Code):

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

3. Cuenta activa de VPSnet.com con una clave API (consulte Cómo obtener una clave API)

Rutas de configuración de credenciales

VPSNET_API_KEY es la credencial preferida por lanzamiento y tiene prioridad sobre los archivos. Para la configuración basada en archivos, establezca VPSNET_CONFIG_DIR en el directorio absoluto que contiene .vpsnet-mcp-key o .mcp.json. El archivo de claves tiene prioridad sobre mcpServers.vpsnet.env.VPSNET_API_KEY en ese archivo JSON. Alternativamente, VPSNET_API_KEY_FILE selecciona una ruta absoluta de archivo de claves; un archivo explícito ilegible o inválido provoca un fallo al iniciar en lugar de elegir otra cuenta.

Sin VPSNET_CONFIG_DIR, los archivos se leen solo desde el directorio de lanzamiento del proceso (cwd). Esto es lo mismo para node /path/to/vpsnet-mcp/build/index.js y npx vpsnet-mcp: el directorio de instalación/caché del paquete y los directorios principales nunca se buscan. Establezca el directorio explícitamente cuando un editor o cliente MCP se inicie desde un directorio de trabajo diferente. Mantenga los archivos de credenciales fuera del control de versiones. VPSNET_API_URL tiene prioridad sobre la URL en ese mismo .mcp.json; las comprobaciones existentes de host de confianza y HTTPS se aplican a cualquiera de las dos fuentes.

Aplicaciones gestionadas

Las aplicaciones gestionadas, SSH manual, DNS, API y otras superficies de implementación son capacidades pares. Su orden en este documento y en la lista de herramientas no es una recomendación. Elija la ruta que mejor se adapte al resultado solicitado por el usuario, al soporte objetivo, al estado existente y a las restricciones explícitas. Una entrada de catálogo es una ruta gestionada disponible, no una razón para anular una solicitud de implementación manual o personalizada válida. Las aplicaciones del catálogo se ejecutan como contenedores Docker en el servidor del cliente y utilizan herramientas de instalación y ciclo de vida tipadas.

Las lecturas de aplicaciones requieren applications:read. La instalación y los cambios del ciclo de vida requieren applications:manage y una clave de idempotencia; los cambios ordinarios del ciclo de vida de aplicaciones no son operaciones de clave API de pago. Las cifras de CPU, RAM y disco son recomendaciones de tamaño, no requisitos de instalación: una aplicación admitida permanece seleccionable durante el pedido y se puede instalar por debajo de esas cifras. La compatibilidad de producto, sistema operativo, arquitectura y tiempo de ejecución siguen siendo requisitos estrictos. Los cambios son asíncronos, así que verifíquelos con get_application_installation y get_application_events. Utilice get_application_health para una inspección nueva del estado del contenedor y get_application_logs para registros de solución de problemas recientes con límite de tamaño, opcionalmente limitados a un servicio Compose exacto. Las inspecciones de registros aceptan como máximo 500 líneas y 131,072 bytes. Estas dos inspecciones de solo lectura crean trabajos de inspección de corta duración, por lo que la clave API debe permitir solicitudes POST.

El detalle de instalación incluye historial limitado de CPU, memoria, red, reinicio y almacenamiento de la aplicación y por contenedor cuando el trabajador lo informa. Los contenedores se identifican solo por servicio Compose y ordinal. Utilice configure_application_resource_thresholds después de confirmación explícita para reemplazar los umbrales de visualización opcionales. Los valores omitidos borran un umbral; los umbrales solo resaltan mediciones y no imponen recursos, activan acciones del servidor ni afectan la facturación. Establezca email_enabled después de confirmación explícita para enviar un correo electrónico de cuenta cuando se alcanza un umbral y uno cuando se recupera; las mediciones repetidas por encima del mismo umbral no se reenvían.

Utilice configure_application_access para cambiar cómo se accede a una aplicación instalada. Lea primero la instalación y pase su revisión actual con una nueva clave de idempotencia. platform_https asigna un nombre de host VPSnet opaco con DNS y HTTPS automáticos, private no tiene listener público, public_http utiliza la IP pública del servidor sobre HTTP y managed_https utiliza una zona DNS gestionada por VPSnet elegible. external_https registra una dirección HTTPS existente gestionada por el cliente; VPSnet no configura ni valida su DNS, certificado TLS ni proxy inverso.

Un acceso managed_https también puede listar additional_addresses (hasta 4 por punto de conexión, 8 por aplicación): otros nombres en las zonas DNS de VPSnet del propio cliente, cada uno con zone_id, name, action y approve_dns: true. Un name o "@" vacío es el dominio desnudo de la zona, por lo que example.com puede estar junto a www.example.com. action es redirect (predeterminado; un 301 a la dirección principal que conserva la ruta y la consulta) o serve (abre la misma aplicación). Agregar o eliminar una dirección adicional nunca cambia la dirección principal. La lista es el conjunto deseado completo: un cambio de acceso que omita additional_addresses elimina las guardadas, así que pásalas de nuevo para conservarlas. Las direcciones adicionales se rechazan en cualquier otro modo de acceso, y VPSnet no cobra nada por ellas.

list_application_registry_credentials expone solo metadatos de credenciales de registros privados. La creación y rotación de tokens de registro no son intencionalmente herramientas MCP: utilice el panel de VPSnet o la API REST directa para que un token nunca entre en un prompt de modelo o argumento de herramienta. Los metadatos pueden identificar Docker Hub, GHCR o un nombre de host de registro HTTPS personalizado exacto.

Las recetas de cliente son definiciones Compose propiedad del cliente, separadas de los planos del catálogo de VPSnet. Pueden validarse en el trabajador objetivo, guardarse como revisiones inmutables, instalarse a través del ciclo de vida gestionado y exportarse sin valores secretos. Las recetas del catálogo de VPSnet nunca son exportables. El descubrimiento de contenedores es limitado y de solo lectura: informa contenedores de cliente y gestionados sin devolver valores de entorno ni montajes, y nunca adopta ni modifica contenedores detectados. La adopción controlada es un flujo separado de preparación, inspección y confirmación explícita para un proyecto Compose elegible. La toma de control inicial es única, pero su enlace exacto de volumen externo permanece firmado en acciones posteriores del ciclo de vida. La recuperación reinicia la fuente solo después de que el reemplazo gestionado esté concluyentemente contenido; los resultados inciertos fallan de forma segura.

Una actualización inmutable está disponible solo cuando get_application_installation devuelve una entrada available_actions con type: "update". Después de la confirmación explícita del usuario, llame a update_application con el expected_blueprint_version y expected_upstream_version anunciados exactos, y una nueva clave de idempotencia. Las claves son globales del cliente: reutilice una clave solo para reproducir la misma solicitud exacta, nunca para otro servicio u operación. El backend selecciona y congela la versión publicada elegible; el llamador no envía una imagen, etiqueta o versión objetivo.

No se crea una copia de seguridad de aplicación separada. En servicios Firecracker admitidos, list_application_restore_points devuelve puntos nocturnos opacos de VM completa con consistencia de aplicación para la revisión de instalación actual exacta. Ver puntos es gratuito, pero las claves API requieren applications:manage, operaciones de pago habilitadas, applications:restore de alcance de pago y acceso completo porque la respuesta incluye el saldo de la cuenta. quote_application_data_restore congela el cargo exacto sin debitar la cuenta. restore_application_data requiere el token de cotización devuelto, la misma clave de idempotencia y confirmación explícita de tanto el pago como el reemplazo de datos. Las claves API de pago también requieren applications:restore, operaciones de pago habilitadas y límites de gasto diarios/mensuales. Reemplaza solo datos de aplicación declarados derivados del trabajador, excluye secretos y datos no relacionados de Docker/servidor, y requiere capacidad de reversión. Consulte get_application_data_restore; needs_attention permanece bloqueado y no debe tratarse como éxito. Estas herramientas nunca aceptan ni exponen credenciales PBS, nombres de archivo, dispositivos o rutas de sistema de archivos.

Las respuestas de lista y detalle de instalación incluyen un bloque capabilities por plataforma — data_restore, console, compose_adoption, custom_projects y log_service_filter — más un indicador access.capabilities.can_configure separado. Trate esos indicadores como la autoridad sobre lo que admite una instalación en lugar de intentar una acción y leer el fallo.

La desinstalación elimina permanentemente los contenedores gestionados, la configuración, las credenciales guardadas y los datos de la aplicación; las copias de seguridad existentes del servidor se conservan. La llamada uninstall_application requiere acknowledge_data_loss=true, y solo debe establecerse después de la confirmación explícita del usuario.

La superficie MCP está orientada a tareas en lugar de ser un espejo uno a uno de cada ruta REST. Las integraciones heredadas de devolución de llamada de micro-pagos y macro-pagos por SMS siguen disponibles a través de la API REST documentada y el panel de control, pero intencionalmente no se exponen como herramientas MCP. Las rutas públicas de pedido previo al inicio de sesión y búsqueda de dominios también tienen equivalentes MCP autenticados donde una operación de cuenta los necesita.

Certificados TLS y SSL automático

Los productos de certificados no se limitan a aplicaciones gestionadas. Los pedidos portátiles de DV, OV y EV pueden instalarse en servidores web controlados por el cliente, proxies, servidores de correo, balanceadores de carga, APIs u otros sistemas compatibles con TLS. Las suscripciones SSL automáticas, en cambio, conectan un cliente ACME compatible en VPSnet u otro proveedor y mantienen actualizados los certificados de corta duración durante el período de pago.

Las cuentas elegibles también pueden solicitar certificados DV portátiles sin costo a través de get_free_certificate_eligibility → preflight_free_certificate → create_free_certificate. Para implementación con API o asistente, cree una CSR en el destino y conserve su clave privada allí; MCP acepta solo la CSR pública y posteriormente devuelve solo la cadena de certificados pública. Las claves gestionadas por VPSnet admiten la renovación anticipada sin supervisión, pero su exportación sigue siendo solo a través del portal, protegida por verificación de dos factores. Los certificados gratuitos, los archivos de certificados de pago, el SSL automático de pago y el HTTPS gestionado de aplicaciones son productos y superficies de ciclo de vida separados.

Use list_certificate_catalog para distinguir portable_certificate de las ofertas acme_subscription. El SSL automático sigue quote_automatic_ssl_subscription → order_automatic_ssl_subscription, con la solicitud exacta sin cambios, el token de cotización, la clave de idempotencia y la aprobación explícita de pago. Lea el estado con list_automatic_ssl_subscriptions y get_automatic_ssl_subscription. Los nombres adicionales usan quote_automatic_ssl_domain → order_automatic_ssl_domain; la API evita pagar dos veces por nombres ya cubiertos por las reglas base/www o comodín/base. Durante los últimos 30 días, un término siguiente elegible usa quote_automatic_ssl_renewal → order_automatic_ssl_renewal y se paga por adelantado solo desde el saldo de la cuenta después de que se apruebe el total exacto en EUR. La cancelación, la eliminación de dominios y la corrección del mismo tipo usan cancel_automatic_ssl_subscription, remove_automatic_ssl_domain y replace_automatic_ssl_domain; el estado ambiguo se reconcilia con refresh_automatic_ssl_subscription, nunca inventando una segunda mutación. El servidor ACME privado y las credenciales EAB permanecen en el portal del cliente protegido por dos factores y no están disponibles intencionalmente para claves API y MCP, por lo que no pueden entrar en el contexto del modelo.

Restaurar un servicio completo

request_restore es de pago y destructivo: cobra el precio de restauración del saldo de la cuenta y sobrescribe el disco del servicio completo con el punto de respaldo, perdiendo todo lo escrito desde entonces. Es una llamada de confirmación, no una consulta de precio: la API rechaza un cuerpo que no incluya una confirmación explícita, y rechaza el cargo directamente si el precio ha cambiado desde que se informó.

No hay ningún diálogo en esta superficie para recopilar esa confirmación, por lo que la herramienta no la fabrica. acknowledge_data_replacement y acknowledge_restore_charge deben ser cada uno true, y solo deben establecerse después de que el usuario haya aprobado realmente el reemplazo del disco y el cargo, la misma regla que acknowledge_data_loss en uninstall_application. Omitir cualquiera de ellos es un error de esquema, por lo que un llamador sin supervisión no puede caer en un cargo: ni siquiera se cotiza nada.

expected_total_charged es el total_charged con IVA incluido que leyó de get_restore_status y mostró al usuario, devuelto sin cambios. No lo vuelva a leer justo antes de la llamada: se supone que es la cifra que el cliente aceptó, y un número recién obtenido coincidiría con el precio actual y anularía la verificación por completo. Si el precio ha cambiado, la restauración se rechaza como restoreQuoteChanged con el total actual y no se cobra nada; informe la nueva cifra, obtenga la aprobación nuevamente y reintente.

Navegar dentro de un respaldo

Mirar dentro de un respaldo es gratuito y completamente separado de pagar por restaurarlo. list_restore_file_points, browse_restore_files y get_restore_file_browse solo leen el listado de directorios de un respaldo: nunca cobran a la cuenta, nunca sobrescriben el disco y nunca devuelven un archivo al servidor. Inicialmente compatible con Firecracker VPS.

La navegación es asíncrona. browse_restore_files crea un trabajo persistente y pone en cola la actividad del trabajador, por lo que su anotación MCP es readOnlyHint: false aunque el respaldo y el servidor en ejecución no cambien. Devuelve un ID de navegación en estado pendiente; consulte get_restore_file_browse hasta que state sea succeeded. Las entradas existen solo en ese estado: una navegación failed lleva un errorCode y sin listado, y no debe presentarse como un directorio vacío.

Los directorios pueden contener una cantidad enorme de archivos, por lo que el servidor selecciona páginas de 200 o 1,000 entradas según la capacidad del trabajador. Cuando result.nextOffset no sea nulo, llame nuevamente con el mismo sourceBrowseId y directoryEntryId y establezca offset a ese cursor. Use result.pageSize en lugar de asumir 200 al retroceder. Los subdirectorios se ingresan con el id opaco de una entrada type: "directory"; las rutas de archivos nunca se aceptan. Los tipos de entrada son file, directory, symlink y unsupported.

La búsqueda de carpetas (el argumento filter) coincide con los nombres de las entradas en el único directorio que se está listando: subcadena sin distinción de mayúsculas y minúsculas, nunca una ruta, nunca recursiva. Depende de una capacidad del trabajador que los nodos más antiguos no informan, por lo que list_restore_file_points devuelve searchAvailable. browse_restore_files verifica esa marca antes de enviar un filtro y falla con serviceFileBrowseSearchUnavailable cuando la búsqueda no es compatible, en lugar de devolver silenciosamente un listado sin filtrar que podría confundirse con resultados de búsqueda. La navegación simple sigue funcionando en esos nodos.

Restaurar archivos seleccionados en el servidor es una operación de pago y deliberadamente no está expuesta aquí; use el panel de VPSnet para ello.

Flujo de trabajo de acceso SSH

Este servidor MCP gestiona su infraestructura VPS a través de la API de VPSnet.com, incluido el aprovisionamiento de claves SSH. Una vez que una clave SSH se implementa en un VPS, el asistente de IA puede conectarse directamente usando la terminal de su entorno (por ejemplo, la herramienta Bash de Claude Code, la terminal de Cline).

Flujo típico:

1. La IA lee la clave pública de la máquina local (~/.ssh/id_rsa.pub)
2. La sube a VPSnet.com a través de create_ssh_key
3. La implementa en un VPS a través de deploy_ssh_key con permiso explícito de vm:exec para OAuth remoto (o la pasa al hacer el pedido con order_service)
4. Se conecta directamente: ssh root@<vps_ip>

La mayoría de los entornos de codificación de IA (Claude Code, Cline, Cursor, Codex) tienen acceso integrado a la terminal, por lo que la IA puede conectarse por SSH a su VPS inmediatamente después de implementar una clave, sin necesidad de herramientas adicionales.

Para entornos sin acceso SSH nativo, combine esto con mcp-server-ssh para conectividad directa al servidor a través de herramientas MCP.

Configuración 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"]
    }
  }
}

Primeros pasos

Elija su entorno:

• Claude Code (CLI) — Codificación de IA basada en terminal
• Claude Code para VS Code — Extensión de VS Code
• Claude Desktop — Aplicación de escritorio
• VS Code con GitHub Copilot — Modo agente de Copilot
• Cline / Cursor / Windsurf / Roo Code / Codex — Otros clientes

La configuración estándar funciona en la mayoría de los 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"}}'

Usuarios de Windows

• Use PowerShell o CMD (no Git Bash) para comandos claude mcp add
• Ubicación del archivo de configuración: C:\Users\<YourUsername>\.claude.json
• Instale Node.js: winget install OpenJS.NodeJS.LTS o descárguelo de nodejs.org
• Después de instalar Node.js, reinicie su terminal y VS Code
• Las variables de entorno en la extensión Claude Code deben estar en el objeto env dentro de .claude.json, NO en las variables de entorno del sistema

Variables de entorno

Las solicitudes salen de la máquina que ejecuta este servidor, no de su navegador. Una implementación que restrinja el acceso por dirección de origen puede responder a una solicitud bloqueada con una página HTML 403 desde su servidor web; el resultado de la herramienta entonces lo indica (non_api_response: true, http_status: 403) en lugar de pasar la página. Cada resultado de error lleva http_status; un 429 también lleva retry_after.

Autenticación, alcances y operaciones de pago

Cada solicitud se envía con el encabezado X-API-KEY (VPSNET_API_KEY).

• Usa una clave de gestión. Su nivel de acceso es full (lectura y cambios) o read (solo GET). Una clave con ámbito de IA se emite únicamente para la inferencia del asistente de IA de VPSnet y se rechaza en todas las rutas de cuenta, por lo que ninguna herramienta aquí funciona con una; el resultado de error incluye auth_problem con el motivo y la solución.
• Los ámbitos granulares solo restringen una clave. Una clave con una lista de ámbitos vacía conserva todo lo que su nivel de acceso permite; enumerar ámbitos (por ejemplo dns:read, services:manage) la restringe. X:manage incluye X:read. La red es la excepción: networking:read / networking:manage / networking:order nunca están implícitos en full o read y deben otorgarse explícitamente.
• Las operaciones de pago son una puerta separada. Una herramienta marcada como Paid o Quote en las tablas siguientes necesita una clave de acceso full, paid_operations_enabled, el ámbito de pago nombrado (vps:order, vds:order, ds:order, fc:order, domains:order, domains:renew, domains:transfer, certificates:order, applications:restore, services:restore, fn:invoke, networking:order), límites de gasto diarios y mensuales configurados, y un idempotencyKey estable (reutiliza la misma clave para reproducir un intento incierto, nunca una nueva). Los pedidos se ejecutan con presupuesto y luego se confirman con el quoteToken devuelto; revela el total exacto en EUR al usuario antes de confirmar. Usa list_api_keys para ver los ámbitos de tu clave, ámbitos de pago, límites y límite de velocidad.
• Límites de velocidad. Las solicitudes tienen límite de velocidad por clave (rate_limit en list_api_keys, solicitudes por minuto). En HTTP 429, retrocede y reintenta después de retry_after segundos en lugar de reintentar inmediatamente.
• Las claves de API nunca pueden crear, cambiar o revocar claves de API, y nunca reciben acceso de administrador.

Herramientas

Las tablas siguientes se generan: edita scripts/tool-scopes.json (o el registro de la herramienta) y ejecuta npm run docs:tools; npm test falla cuando se desvían.

Ámbito es el ámbito de clave de API granular que la herramienta necesita (none = cualquier clave de gestión; a + b = ambas; a or b = cualquiera, según el objeto). Pago: Paid: x gasta el saldo de la cuenta y necesita el ámbito de pago x más las puertas anteriores; Quote: x crea un presupuesto sin cobrar pero está limitado de la misma manera; Paid solo carga el saldo con una clave de acceso full y sin ámbito de pago separado; Needs paid scope: x es una lectura que expone datos de saldo o precio; Billed while kept significa gratis durante una ventana inicial, luego medido; free es todo lo demás.

Cuenta

Servicios

Aplicaciones gestionadas

Acciones de servicio

Configuración del servicio

Reinstalación del sistema operativo

Cambios de plan (gratis)

Renovación y facturación

Pedidos

Copias de seguridad

Restauración

Claves SSH

Claves de API

La creación, los cambios y la revocación de claves de API requieren un inicio de sesión en el navegador/sesión. No pueden realizarse mediante una conexión MCP autenticada con una clave de API.

Certificados TLS gratuitos

Para instalación portátil de API o asistente, use customer_csr y conserve la clave privada donde se generó la CSR. Una solicitud administrada puede renovarse sin supervisión, pero MCP no puede exportar su clave privada. La emisión es asíncrona y limitada por cuota: consulte get_free_certificate, siga get_free_certificate_instruction y no trate una solicitud en cola como emitida.

Suscripciones SSL automáticas

Automatic SSL es una suscripción ACME de pago portátil. Funciona con un cliente compatible en VPSnet u otro proveedor; no se limita a aplicaciones administradas. La URL privada del servidor ACME y las credenciales EAB se revelan solo en el portal del cliente protegido con dos factores. Intencionalmente no son una herramienta MCP ni una respuesta de clave de API, por lo que un asistente no puede copiarlas en el contexto del modelo.

Certificados TLS de pago

Los certificados de pago son productos de cuenta portátiles: los clientes pueden instalarlos en Nginx, Apache, lighttpd, OpenLiteSpeed, HAProxy, Caddy, correo, API, balanceadores de carga u otros puntos finales TLS. Son independientes del HTTPS automático adjunto a una aplicación administrada por VPSnet. El MCP acepta solo una CSR PKCS#10 pública; la clave privada debe permanecer bajo el control del cliente y nunca debe ingresar en un argumento de herramienta ni en el contexto del modelo. Las respuestas de cotización contienen el precio final al cliente en EUR, y los pedidos requieren aprobación explícita más la misma clave de idempotencia y un token de cotización de corta duración.

Dominios

DNS

Instantáneas

Rescate de Servicio

Funciones Firecracker

Servidores bajo demanda

Los pedidos de clientes están deshabilitados mientras se valida el ciclo de vida del servidor bajo demanda. Las opciones actuales revelan que las copias de seguridad automáticas y las instantáneas no están incluidas y que las conexiones salientes a los puertos TCP de entrega de correo 25, 2525, 465 y 587 están restringidas. Las sesiones existentes permanecen disponibles mediante listar/obtener/eliminar para limpieza. Los campos de TTL fijo y prepago en el esquema de compatibilidad deshabilitado no son una promesa de lanzamiento; el contrato de duración flexible y facturación medida debe publicarse de manera consistente antes de habilitar los pedidos.

Agente Invitado

Historial

Público

Redes SDN

Los permisos de red deben otorgarse explícitamente: networking:read o networking:manage; los valores predeterminados ordinarios de acceso completo/lectura no los incluyen. Comience con capacidades, luego lea el recurso propio exacto y su generación. El backend aplica propiedad del inquilino, disponibilidad y bloqueos 2FA del servidor. Aceptado, pagado y listo son estados separados; consulte la operación o recurso correspondiente. Los cambios de DNS se consultan a través del settings.dns_change de la red.

Los nuevos balanceadores de carga privados/públicos, VPNs y direcciones públicas utilizan un flujo explícito de cotización → pago común → estado de pedido. Las herramientas de cotización siempre envían prepare_after_payment=true: no se realiza aprovisionamiento antes del pago. Muestre el EUR exacto de la cotización gross_amount, obtenga aprobación y pase el mismo idempotencyKey, quote_id y quoteToken a order_network_product. Las claves API además necesitan acceso completo, operaciones de pago habilitadas, networking:order y límites de gasto. Lea get_network_payment_methods y seleccione system=balance; el pago sin saldo se rechaza para claves API. Si la confirmación es incierta, recupere por el ID de cotización original y la clave. Para un pedido SDN con status=paid_pending, billing_state=captured y reason_code=network_product_ip_inventory_wait, el pago se retiene mientras el inventario de IP públicas no esté disponible. Consulte get_network_product_order con el mismo ID de pedido; el backend se reanuda automáticamente cuando el inventario regresa. No cree otro pedido, cobre nuevamente ni envíe un reintento manual. manual_review o network_product_stock_reconciliation_required en su lugar requiere revisión del operador; no autoriza un reintento automático.

Los pedidos ordinarios de VPS exponen esta espera mediante get_service.stateProcess.waitingReason=public_ip_inventory (también reflejado en el campo heredado stateProccess). Consulte el mismo servicio sin reordenar. stateProcess.attention=true requiere atención del operador. Un pago exitoso o una creación aceptada no establece que el servidor esté listo. Los niveles públicos de balanceador de carga alb_proxy_3/alb_proxy_5 utilizan el tipo de solicitud proxy_lb; el nivel privado nlb utiliza private_lb. La disponibilidad y los precios provienen del catálogo de productos en vivo. Un endpoint heredado de creación de aplicaciones impago no es una alternativa al proceso de pago.

La recogida de configuración del dispositivo es una acción de gestión única, aunque su método HTTP sea GET. Genere el par de claves de revelación fuera de MCP, envíe solo la clave pública X25519, guarde el texto cifrado sellado devuelto y descifrelo fuera de la conversación. Ni las claves privadas ni la configuración de WireGuard en texto plano son solicitadas o descifradas por estas herramientas. Nunca repita automáticamente una recogida después de una respuesta incierta.

El backend actual no tiene cambio de nombre de red de cliente, edición de IP fija en puertos existentes, reintento de aplicaciones ni API nativa de sitio a sitio en esta versión. Las direcciones DHCP fijas se seleccionan al adjuntar; eliminar/recrear un adjunto requiere aprobación por separado y no se representa como una edición en el lugar. Las rutas heredadas de creación de LB/VPN impagas, las compras heredadas de stock antes del pago y la habilitación de renovación automática mediante claves de API no se exponen deliberadamente. La gestión existente de enlaces públicos sigue disponible; las nuevas direcciones públicas utilizan propiedad de cuenta y proceso de pago común. Que una herramienta esté listada no habilita una puerta de función del backend.

Ejemplos trabajados

Cada ejemplo es una solicitud a tu asistente y las herramientas que llama.

Pedir un VPS (cotizar, luego confirmar)

Pedir el Cloud VPS más barato con Debian y mi clave SSH, pagado desde el saldo.

1. get_order_plans para el producto, luego get_order_options para el plan elegido (SO, período, IDs de recursos) y list_ssh_keys para el ID de la clave.
2. order_service con plan, os, period, resources, sshKey (o rootPassword, no ambos), payment: { payment: 1, successUrl: '', cancelUrl: '' } y un idempotencyKey estable. La primera llamada devuelve un presupuesto sin cobrar. La clave API necesita vps:order (o vds:order, ds:order, fc:order) y límites de gasto.
3. Muestra el total exacto en EUR bruto y el período de facturación. Tras la aprobación del cliente, repite el pedido y la clave sin cambios con el quoteToken devuelto, expected_total_eur y acknowledge_charge: true. Inspecciona el intento original en el panel si su resultado es desconocido; no crees otra clave para reintentarlo.
4. Consulta get_service para el número de pedido devuelto; el pago aceptado no es servidor listo.

Redes (presupuesto, luego pedido)

Añade un balanceador de carga privado a mi red y paga desde el saldo.

1. get_networking_capabilities, list_network_products y get_network_payment_methods (elige el método system=balance).
2. quote_network_product con kind (private_lb, proxy_lb o vpn_gateway), tier y un idempotencyKey; muestra el gross_amount en EUR del presupuesto.
3. Tras la aprobación, order_network_product con el mismo idempotencyKey, quote_id, quoteToken, el payment del saldo y acknowledge_charge: true. Si el resultado es incierto, find_network_product_order por el quote_id original, luego consulta get_network_product_order. Nunca compres una segunda copia.

Actualización de registros DNS

Apunta www.example.com a 203.0.113.10 con un TTL de 5 minutos.

1. list_dns_zones para encontrar el zone_id, luego get_dns_zone para inspeccionar los registros existentes y sus IDs (necesita dns:read).
2. Para añadir un valor A, llama a upsert_dns_record con zone_id, name: "www", type: "A", content: "203.0.113.10", ttl: 300 (necesita dns:write). Un contenido diferente añade otro registro y conserva los valores existentes. Una tupla idéntica de nombre/tipo/contenido actualiza su TTL/comentario y lo reactiva si estaba deshabilitado. Para reemplazar un valor existente, usa update_dns_record con su record_id exacto y el nombre, tipo, contenido y TTL deseados.
3. get_dns_zone para leer los registros deseados de vuelta, o get_dns_zone_history para ver el cambio.

Para una zona en espera cuyo valor TXT de propiedad se perdió, primero lee get_dns_zone.zone.verification.record.value. Usa reissue_dns_zone_verification solo si ese valor es nulo/irrecuperable o el cliente solicita rotación. Admite tanto pending_verification como verification_expired; el valor anterior deja de aceptarse. Actualiza el TXT en la ubicación indicada por zone.verification.next_step, luego llama a verify_dns_zone. Reemitir solo no verifica la zona ni restablece su estado.

Pedir un certificado de pago

Compra un certificado DV de un año para example.com; generé el CSR yo mismo.

1. list_certificate_catalog y get_certificate_catalog_product para elegir un producto y leer su oferta actual en EUR.
2. quote_certificate con product_id, offer_id, offer_generation, common_name (más cualquier alternative_names), el csr público PKCS#10, los IDs de contacto propios y un idempotencyKey (necesita certificates:order, operaciones de pago y límites). Nunca envíes una clave privada.
3. Tras la aprobación del usuario del total exacto, order_certificate con la misma solicitud, el mismo idempotencyKey, el quote_token, el payment y acknowledge_exact_quote_and_payment: true.
4. get_certificate_validation (publica el desafío, por ejemplo a través de upsert_dns_record), luego download_certificate una vez emitido.

Obtención de una clave API

1. Inicia sesión en vpsnet.com
2. Ve a Cuenta > Claves API
3. Haz clic en Crear clave API
4. Ponle un nombre y copia la clave

La clave se muestra solo una vez: guárdala de forma segura.

Solución de problemas

Las herramientas MCP no aparecen en la extensión de Claude Code para VS Code

1. Instala la CLI de Claude Code: npm install -g @anthropic-ai/claude-code
2. Verifica: claude --version debería mostrar un número de versión
3. Añade el servidor mediante la CLI: claude mcp add vpsnet -- npx -y vpsnet-mcp
4. Reinicia VS Code por completo (no solo recargar la ventana)
5. Revisa ~/.claude.json para la configuración correcta

claude: command not found

Instala la CLI de Claude Code globalmente:

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

Verifica que tu PATH incluya los paquetes globales de npm. En Windows, reinicia tu terminal después de instalar.

Las variables de entorno no funcionan

Para la extensión de Claude Code, las variables de entorno deben estar en el objeto env dentro de .claude.json, NO en las variables de entorno del sistema:

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

Errores de clave API

Este servidor necesita una clave API de gestión. Cada fallo a continuación es informado por las herramientas con un objeto auth_problem que contiene la causa y la solución, así que léelo en lugar de adivinar por el estado HTTP.

Los fallos de herramientas llevan isError: true mientras conservan los detalles del error de la API y la guía de recuperación. Los resultados desconocidos de mutaciones deben verificarse antes de otro intento. Los números de pedido de servicio deben copiarse de list_services; se admiten letras ASCII, dígitos y guiones, incluidos los sufijos de múltiples pedidos. Los identificadores de URL malformados o sobredimensionados se rechazan antes de una solicitud a la API.

• Verifica que la clave sea correcta (comienza con vpsnet_ seguido de 43 caracteres)
• Las claves se muestran solo una vez al crearlas: si se pierden, crea una nueva
• Comprueba que la clave no haya expirado (Cuenta > Claves API)

deploy_ssh_key se realizó correctamente pero SSH aún falla

• Todos los servidores de VPSnet.com usan root como nombre de usuario SSH
• El despliegue de claves es asíncrono: espera 15-30 segundos después de desplegar antes de intentar SSH

fetch is not defined o errores inesperados

Este servidor requiere Node.js 20+. Si tu node predeterminado es más antiguo (común con configuraciones de nvm), ya sea:

• Establece Node 20+ como predeterminado: nvm alias default 20
• O usa el envoltorio de nvm que se muestra en la sección Codex

Licencia

MIT