MCP Tools Reference

The VMKit MCP server exposes infrastructure operations as callable tools to any MCP-compatible client (Claude Code, Cursor, custom agents). Every tool call is forwarded to gateway.vmkit.dev with your Bearer token; the same auth, rate limits, and audit trail apply as the REST API.

Connection

MCP config entry (~/.claude/mcp.json):

{
  "mcpServers": {
    "vmkit": {
      "type": "http",
      "url": "https://mcp.vmkit.dev",
      "headers": {
        "Authorization": "Bearer vmk_your_key_here"
      }
    }
  }
}

Tools

scan_repo

Scans a GitHub repository via the GitHub API and an AI classifier. Detects language, framework, and buildpack compatibility. Does not modify the repository.

Parameters

Returns

Example — Claude Code prompt

Scan badri/my-fastapi-app and tell me what buildpack it would use

Example — raw JSON call

{
  "tool": "scan_repo",
  "arguments": {
    "repo": "badri/my-fastapi-app"
  }
}

Response:

{
  "language": "python",
  "framework": "fastapi",
  "buildpack": "gcr.io/buildpacks/builder:v1",
  "procfile_detected": true,
  "dockerfile_detected": false,
  "scan_id": "sc_01jx4n8rz3q5m7k2p0d6w9b1e"
}

harden_vm

Runs security hardening on a provisioned VM. Creates the kamal OS user, grants Docker socket access, and tightens SSH configuration (disables root login and password auth). Must be called after the VM is provisioned and vmkit-agent is connected, before the first deploy.

Parameters

Returns

Example — Claude Code prompt

Harden the VM with instance ID inst_01jx4n9abc for my staging environment

Example — raw JSON call

{
  "tool": "harden_vm",
  "arguments": {
    "instance_id": "inst_01jx4n9abc"
  }
}

Response:

{
  "status": "hardened",
  "instance_id": "inst_01jx4n9abc"
}

deploy

Deploys a repository to a named environment. Manages the full lifecycle: onboarding PR (first call only), VM provisioning, hardening, DNS registration, and GitHub Actions dispatch.

Two-phase behavior:

• First call — if vmkit-deploy.yml does not exist in the repo, VMKit opens a pull request adding the workflow file and a starter Kamal config. Returns status: "scaffolding_pr_open" with the PR URL. Merge the PR, then call deploy again.
• Subsequent calls — provisions a VM (if none exists for the environment), hardens it, registers DNS, and dispatches the GitHub Actions workflow. Returns when the deploy completes or fails.

Parameters

Returns

Example — Claude Code prompts

Deploy badri/my-fastapi-app to staging

Deploy badri/my-fastapi-app to production at SHA abc1234

Example — raw JSON call

{
  "tool": "deploy",
  "arguments": {
    "repo": "badri/my-fastapi-app",
    "dest": "staging"
  }
}

Response (scaffolding phase):

{
  "status": "scaffolding_pr_open",
  "pr_url": "https://github.com/badri/my-fastapi-app/pull/12",
  "app_url": null,
  "run_url": null,
  "instance_id": null,
  "deploy_id": null
}

Response (deploy completed):

{
  "status": "succeeded",
  "pr_url": null,
  "app_url": "https://my-fastapi-app-staging.vmkit.app",
  "run_url": "https://github.com/badri/my-fastapi-app/actions/runs/14912345",
  "instance_id": "inst_01jx4n9abc",
  "deploy_id": "dep_01jx5p0qr8s6n3t4u2v7w0y1z"
}

Error Reference

Authentication error

Returned as a ToolError when the vmk_ token is missing, invalid, expired, or lacks scope.

Authentication failed — your vmk_ API key is missing, invalid, expired, or lacks the scope this tool requires.

Resolve by checking the token in your MCP config against Settings → API Keys in the dashboard.

Backend error propagation

Non-auth errors (4xx, 5xx from the REST API) are wrapped in a ToolError with the backend’s JSON error body as the message. Example:

{"error": "repo_not_found", "message": "No repo with id repo_abc123 found in this workspace."}