Vultr Codex MCP

A Codex plugin and local MCP server 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.

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.

Related MCP server: SSH Linux Control

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-mcp

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