Vultr Codex

A Codex plugin for managing Vultr with explicit safety guards. The first version focuses on small VPS workflows: inspect account state, preview instance creation, then perform selected mutations only after exact confirmation.

The plugin's tools are implemented through a local MCP server, but the user-facing product is a Codex plugin.

Features

• List Vultr account, instances, plans, regions, OS images, SSH keys, and firewall groups.
• Check whether vultr-cli is available locally for optional manual workflows.
• Preview instance creation before spending money.
• Restrict instance creation by plan, region, and monthly cost.
• Require exact confirmation strings for create, reboot, snapshot, and delete.
• Read the Vultr token only from VULTR_API_KEY.

Quick Start

npm install
npm run verify
export VULTR_API_KEY="your-vultr-api-key"

The Codex plugin manifest is in .codex-plugin/plugin.json; the MCP configuration is in .mcp.json. The bundled server entrypoint is mcp/server.mjs.

Codex Plugin Install

During local development, keep the repository under:

/Users/zeyuwang/Documents/project/vultr-codex-plugin

Then install the plugin from a local marketplace entry or copy/symlink the repository into your personal plugin marketplace. The plugin does not need the Vultr token at install time, but Vultr API tools require VULTR_API_KEY in the environment where Codex launches the MCP server.

If you only want to smoke-test the MCP server without installing the plugin:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | node ./mcp/server.mjs

Safety Policy

By default, create operations are limited to:

• Plans: vc2-1c-1gb, vc2-1c-2gb, vc2-2c-2gb
• Regions: nrt, itm, sgp, icn, lax, sjc, sea
• Maximum monthly cost: $20

Override these with environment variables:

VULTR_ALLOWED_PLANS=vc2-1c-1gb,vc2-1c-2gb
VULTR_ALLOWED_REGIONS=nrt,sgp,lax
VULTR_MAX_MONTHLY_COST_USD=10

Confirmation Strings

Mutation tools reject calls unless the confirm field exactly matches the expected string returned by preview or described by the tool:

create:<label>:<plan>:<region>
reboot:<instance_id>
snapshot:<instance_id>
delete:<instance_id>:<label>

For deletion, the server first fetches the instance and checks that the Vultr label matches the provided label.

Tools

• get_policy
• get_account
• get_vultr_cli_status
• list_instances
• get_instance
• list_regions
• list_plans
• list_os
• list_ssh_keys
• list_firewall_groups
• create_instance_preview
• create_instance
• reboot_instance
• create_snapshot
• delete_instance

Development

npm install
npm run check
npm test
npm run build

The source lives under src/. npm run build bundles it into mcp/server.mjs, which is what Codex launches.

Local Context

For this machine, the preferred code repository root is:

/Users/zeyuwang/Documents/project