vastai-host-mcp

Production-ready Model Context Protocol (MCP) server for Vast.ai host/provider operations using FastMCP and TypeScript.

This project is the host/provider counterpart to renter-focused tools. For renting GPUs as a customer, use CryDevOk/vastai-mcp.

Table of contents

<!-- TOC -->

• What this server is for
• Feature summary
• Getting started
• Environment variables
• Development workflow
• Connect from MCP clients
• Use with GitHub Copilot
• Where to check Vast API
• Run on Vast.ai machines
• Project layout
• Contributing
• License

<!-- /TOC -->

What this server is for

This MCP server is purpose-built for Vast.ai providers (hosts who own and operate machines). It focuses on host-side workflows including:

• Viewing and managing hosted machines.
• Updating default jobs, pricing, and offer settings.
• Running verification and self-test operations.
• Inspecting reliability, uptime, and host operational signals.
• Managing host scripts and daemon restart workflows.

Feature summary

• TypeScript-first server implementation with strict compiler settings.
• FastMCP tool definitions with rich tool metadata and strict Zod schemas.
• Singleton Vast.ai host client with:
  • Bearer token API auth
  • /api/v0/... endpoint targeting
  • robust error handling
  • timestamped logging via Pino
• API-first execution with optional Vast CLI fallback for host commands.
• stdio and httpStream transport support.
• Host automation helper rules for pricing and reliability recommendations.

Getting started

Prerequisites

• Node.js 20+
• pnpm 9+
• Vast.ai API key with host/provider permissions

Install and run

• Install dependencies:

pnpm install

• Copy environment file and edit values:

cp .env.example .env

• Set at least VAST_API_KEY in .env.

• Start development server (FastMCP dev mode):

pnpm dev

• Inspect tools interactively:

pnpm inspect

• Build and run production bundle:

pnpm build
pnpm start

Environment variables

Variable	Required	Default	Purpose
VAST_API_KEY	Yes	none	Vast.ai API token for host/provider operations
VAST_SERVER_URL	No	https://console.vast.ai	Vast.ai API base URL
MCP_TRANSPORT	No	stdio	Transport mode: stdio or httpStream
MCP_HTTP_HOST	No	0.0.0.0	Host bind for httpStream transport
MCP_HTTP_PORT	No	8080	Port for httpStream transport
VAST_REQUEST_TIMEOUT_MS	No	30000	API and CLI timeout in milliseconds
VAST_USE_CLI_FALLBACK	No	true	Enable CLI fallback for host operations
VAST_CLI_PATH	No	vastai	Vast CLI executable path
VAST_AUTO_PRICING_ENABLED	No	false	Toggle automation hints for price workflows
VAST_AUTO_RELIABILITY_GUARD	No	false	Toggle automation hints for reliability workflows
LOG_LEVEL	No	info	Pino log level

Development workflow

Default local development workflow (warning-free in pnpm-managed environments):

pnpm dev

FastMCP terminal harness workflow (optional):

pnpm dev:fastmcp
pnpm inspect

Codespaces inspector workflow:

# If you had a prior inspector run, free default ports first
pkill -f mcp-inspector || true

# Start inspector with Codespaces-safe host and origin settings
pnpm inspect:codespaces

# If token/auth forwarding is problematic, use no-auth mode in dev only
pnpm inspect:codespaces:noauth

If the browser opens but cannot connect, ensure both forwarded ports are active:

• 6274 (Inspector UI)
• 6277 (Inspector proxy)

If the UI still shows Disconnected, use these manual values in Inspector:

• Transport Type: STDIO
• Command: pnpm
• Arguments: exec tsx src/index.ts
• Then click Connect

If auth is enabled, open Auth Settings and paste the MCP_PROXY_AUTH_TOKEN printed in terminal.

Production build workflow:

pnpm build
pnpm start

Key host tools currently implemented:

• vastai_host_show_machines
• vastai_host_set_defjob
• vastai_host_upsert_offer
• vastai_host_set_min_bid
• vastai_host_verification_status
• vastai_host_self_test_machine
• vastai_host_get_stats
• vastai_host_recommend_pricing
• vastai_host_update_script
• vastai_host_restart_daemon
• vastai_host_search_offers
• vastai_host_show_logs
• vastai_host_network_status
• vastai_host_reliability_actions

Connect from MCP clients

Use stdio transport for desktop tools unless you specifically need network transport.

Claude Desktop example

{
  "mcpServers": {
    "vastai-host": {
      "command": "pnpm",
      "args": ["start"],
      "cwd": "/absolute/path/to/vastai-host-mcp",
      "env": {
        "VAST_API_KEY": "YOUR_VAST_API_KEY",
        "VAST_SERVER_URL": "https://console.vast.ai",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Cursor example

{
  "mcpServers": {
    "vastai-host": {
      "command": "pnpm",
      "args": ["start"],
      "cwd": "/absolute/path/to/vastai-host-mcp",
      "env": {
        "VAST_API_KEY": "YOUR_VAST_API_KEY",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

VS Code MCP example

{
  "servers": {
    "vastai-host": {
      "type": "stdio",
      "command": "pnpm",
      "args": ["start"],
      "cwd": "/absolute/path/to/vastai-host-mcp",
      "env": {
        "VAST_API_KEY": "YOUR_VAST_API_KEY"
      }
    }
  }
}

Use with GitHub Copilot

For GitHub Copilot Chat in VS Code, this repository already includes a workspace MCP config at .vscode/mcp.json.

Recommended flow:

1. Set your real VAST_API_KEY in .vscode/mcp.json.
2. Stop any manually running local server process (pnpm dev) so VS Code can own the MCP process lifecycle.
3. In VS Code, reload MCP servers from the Command Palette.
4. In Copilot Chat, test a tool call such as vastai_host_show_machines.

Note: For VS Code MCP usage, you usually do not need to run pnpm dev manually.

Where to check Vast API

Use these sources to validate endpoint existence and request format:

• API docs index: llms.txt
• API intro: Vast API Reference
• Machines: show machines
• Machines: set min-bid
• Machines: set defjob
• Machines: list machine
• Search: search offers

The current endpoint mapping used by this MCP server is implemented in src/client/VastAIHostClient.ts.

Quick local checks:

pnpm build
pnpm inspect

When using the Inspector, a command returning HTTP 404 is usually a route mismatch, while HTTP 400/403/500 generally means the route exists and your payload, permissions, or backend state should be checked.

Run on Vast.ai machines

When deploying this MCP server inside a Vast.ai instance:

1. Keep API keys in environment variables only. Never hardcode secrets.
2. Use stdio mode for local desktop tunneling workflows.
3. Use httpStream only behind trusted network boundaries or a reverse proxy.
4. Install Vast CLI in the runtime if you want CLI fallback behavior.
5. Monitor logs with your preferred process manager (systemd, pm2, supervisord).

For onboarding guidance, see Building your first MCP server on Vast.ai.

Project layout

.
├── src/
│   ├── client/
│   │   └── VastAIHostClient.ts
│   ├── rules/
│   │   └── MCPRules.ts
│   ├── tools/
│   │   └── hostTools.ts
│   ├── config.ts
│   ├── index.ts
│   └── logger.ts
├── .env.example
├── package.json
├── tsconfig.json
└── README.md

Contributing

1. Open an issue describing the host/provider workflow or API gap.
2. Keep additions host-focused (not renter workflow features).
3. Add or update tool descriptions so they remain LLM-friendly and explicit.
4. Run local checks before opening a PR.

Repository-wide conventions and agent behavior are documented in AGENTS.md.

License

This project is licensed under the MIT License. See LICENSE.

<!-- Named links -->