Vast.ai

You can run a Vast.ai MCP Server to manage GPU instances through a lightweight client, automate common workflows, and expose a rich set of tools for inventory, provisioning, and monitoring. This guide walks you through installing the server on macOS, configuring your MCP client, and using key workflows to create and manage instances on Vast.ai.

How to use

You interact with the Vast.ai MCP Server through an MCP client. After you connect, you can list your account, search for GPU offers, create and manage instances, label resources, run commands, and monitor long-running tasks. The server provides a collection of endpoints (tools) that cover common GPU provisioning tasks, from showing user info to launching and tracking training jobs.

How to install

brew install uv

git clone https://github.com/your-repo/vastai-mcp.git
cd vastai-mcp

uv sync

uv tool install -e .   # Install from current directory

# MCP client configuration to connect to the local Vast.ai MCP Server
{
  "mcpServers": {
     "vast-ai": {
       "command": "uv",
       "args": [
           "run",
           "vast-mcp-server"
       ],
       "env": {
           "VAST_API_KEY": "your_vast_api_key_here",
           "SSH_KEY_FILE": "~/.ssh/id_rsa",
           "SSH_KEY_PUBLIC_FILE": "~/.ssh/id_rsa.pub"
       }
     }
  }
}

Additional sections

Configuration details, security considerations, and practical workflows help you get up and running quickly. Below you’ll find explicit steps for API key setup, how to run the server, and common usage patterns with MCP clients.

Configuration

API Key Setup You must provide a Vast.ai API key to interact with the GPU cloud. Use one of these methods:

export VAST_API_KEY="your_api_key_here"

Or place the key in a dedicated file at your home directory for convenient loading when starting the server.

Running the server to listen on default or custom host/port is straightforward once dependencies are installed.

Common workflows

Basic usage typically follows: check your account, search for offers, create an instance, and monitor status. You can also manage storage, attach SSH keys, and execute remote commands. The following workflows reflect common tasks you’ll perform.

Notes on security and maintenance

Keep your API key secure. Use SSH keys for accessing instances, and rotate credentials as needed. Regularly verify network access to Vast.ai endpoints and monitor logs for unusual activity.

Troubleshooting

If you encounter permission errors, ensure your SSH private key has correct permissions and matches the public key you’ve configured. If API keys are rejected, double-check permissions and validity. Network issues may block access to Vast.ai endpoints; verify connectivity from your host.

Notes

The MCP server can be run locally and controlled through an MCP client. Use the provided configuration snippet to connect your client to run commands against the server. Ensure you supply the required API key and SSH key references when configuring your client.

Security and validation

Always validate your configuration before heavy usage. Confirm that the MCP client references the correct command and environment variables, and that the server is reachable at the expected host and port.

Available tools

show_user_info

Show current user information including username, email, balance, and spending details.

show_instances

List all user instances with status, GPU, image, IP, and creation date.

search_offers

Query available GPU offers with filters, limit, and sort order.

create_instance

Provision a new instance from a selected offer with options for image, disk, SSH, Jupyter, environment, and labeling.

destroy_instance

Destroy an instance and remove it from the system.

start_instance

Start a stopped instance to resume usage.

stop_instance

Stop a running instance without destroying it.

search_volumes

Search for storage volume offers by query and limit.

label_instance

Attach a label to an instance for easier identification.

launch_instance_workflow

Launch a streamlined workflow to select a GPU, image, and region and create an instance.

prepay_instance

Prepay credits to a reserved instance for discounted rates.

reboot_instance

Reboot an instance without losing GPU priority.

recycle_instance

Recycle an instance with a new image while preserving GPU priority.

show_instance

Show detailed information about a specific instance.

logs

Fetch logs for an instance with optional tail and filter.

attach_ssh

Attach your SSH key to an instance for secure access.

search_templates

List available templates that simplify instance creation.

execute_command

Execute a constrained command on stopped instances via the MCP interface.

ssh_execute_command

Execute a command on a running instance through SSH.

ssh_execute_background_command

Run a long-running command on a remote host in the background via SSH.

ssh_check_background_task

Check progress and output of a background SSH task.

ssh_kill_background_task

Terminate a running background SSH task and clean up.

disable_sudo_password

Disable password prompts for sudo for automation on a remote host.

configure_mcp_rules

Configure automation rules for MCP behavior during instance creation.