# MCP Server

Connect Claude Code, Claude Desktop, Codex, Cursor, and other MCP clients to your Hatchbox account

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](https://hatchbox.io/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](https://hatchbox.io/api_tokens) page. The MCP server keeps no state of its own, so access stops immediately.

For more detail, see the [@hatchbox/hatchbox-mcp](https://www.npmjs.com/package/@hatchbox/hatchbox-mcp) package on npm.