MCP Server

The Hatchbox MCP server connects AI coding agents like Claude Code, Codex, and Cursor to your Hatchbox account. It wraps the Hatchbox /api/v1 API with one tool per operation, so your agent can inspect and manage your apps, deploys, databases, servers, domains, environment variables, cron jobs, and logs — authenticated with your own API token.

The server runs locally on your machine. npx fetches the package each time it runs, so there is nothing to install permanently and nothing to keep updated.

Requirements

• An active Hatchbox subscription (the 7 day free trial counts)
• Node.js installed locally (the server runs via npx)
• A Hatchbox API token

Create an API token

Go to API Tokens in Hatchbox, click New API Token, give it a name, and copy the value. You'll use it as the HATCHBOX_API_TOKEN environment variable below.

Claude Code

One command registers the server and sets both environment variables:

claude mcp add hatchbox \
  --env HATCHBOX_API_TOKEN=your-token-here \
  -- npx -y @hatchbox/hatchbox-mcp

Claude Desktop

Add the server to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "hatchbox": {
      "command": "npx",
      "args": ["-y", "@hatchbox/hatchbox-mcp"],
      "env": {
        "HATCHBOX_API_TOKEN": "your-token-here"
      }
    }
  }
}

Codex

From the command line:

codex mcp add hatchbox \
  --env HATCHBOX_API_TOKEN=your-token-here \
  -- npx -y @hatchbox/hatchbox-mcp

Or by hand in ~/.codex/config.toml:

[mcp_servers.hatchbox]
command = "npx"
args = ["-y", "@hatchbox/hatchbox-mcp"]

[mcp_servers.hatchbox.env]
HATCHBOX_API_TOKEN = "your-token-here"

Cursor

Add the same JSON block as Claude Desktop to ~/.cursor/mcp.json (or .cursor/mcp.json inside a project):

{
  "mcpServers": {
    "hatchbox": {
      "command": "npx",
      "args": ["-y", "@hatchbox/hatchbox-mcp"],
      "env": {
        "HATCHBOX_API_TOKEN": "your-token-here"
      }
    }
  }
}

VS Code

VS Code's agent mode uses the same entry in .vscode/mcp.json, nested under servers instead of mcpServers:

{
  "servers": {
    "hatchbox": {
      "command": "npx",
      "args": ["-y", "@hatchbox/hatchbox-mcp"],
      "env": {
        "HATCHBOX_API_TOKEN": "your-token-here"
      }
    }
  }
}

Other MCP clients

Any client that can launch a local stdio server works. The command is always npx -y @hatchbox/hatchbox-mcp with the two environment variables HATCHBOX_API_TOKEN.

Using it

Once connected, ask your agent about your infrastructure in plain language. A few examples:

• "Which of my apps haven't deployed in the last month?"
• "Why did last night's deploy fail?"
• "Restart the worker process on staging."
• "Add BUGSNAG_API_KEY to all three of my apps."
• "Point app.example.com at my Rails app."
• "Back up the production database and tell me when it's finished."

Read-only tools are annotated read-only and can't change anything. Write tools carry a standard MCP write annotation, so your client can ask for your approval before any of them run.

Security notes

• Treat your API token like a password: keep it in your client's environment variable config, don't commit it, and don't paste it into prompts.
• Each developer should use their own token rather than sharing one across a team.
• To revoke access, delete the token on the API Tokens page. The MCP server keeps no state of its own, so access stops immediately.

For more detail, see the @hatchbox/hatchbox-mcp package on npm.