hatchbox — Claude Code MCP server: what it does, how to install
Connects your assistant to Hatchbox to manage Rails deployments and inspect or edit environment variables directly from chat.
claude mcp add --env HATCHBOX_API_KEY=<HATCHBOX_API_KEY> --env HATCHBOX_ACCOUNT_ID=<HATCHBOX_ACCOUNT_ID> --env HATCHBOX_APP_ID=<HATCHBOX_APP_ID> --env HATCHBOX_DEPLOY_KEY=<HATCHBOX_DEPLOY_KEY> --env WEB_SERVER_IP_ADDRESS=<WEB_SERVER_IP_ADDRESS> --transport stdio hatchbox -- npx -y hatchbox-mcp-serverWhat hatchbox does
The server links AI clients to the Hatchbox platform via its HTTP API and server SSH connections. It triggers application deployments for the latest code or a specified Git commit SHA, checks build progress, and handles application environment keys.
Safety controls are turned on from the start. The default READONLY mode blocks any variable creation or deletion until you explicitly set READONLY=false in the configuration. Reading server variables relies on SSH rather than the API. Without WEB_SERVER_IP_ADDRESS and an authorized SSH key, variable inspection calls will fail.
When several Rails apps share a single server, supply HATCHBOX_APP_NAME. This filters the target Puma processes so the tool reads values from the correct application environment.
What it helps with
- Trigger a Rails app deploy for a specific Git commit
- Inspect active environment variables over SSH
- Track deployment progress using the returned activity ID
- Update or delete configuration keys in Hatchbox
Example prompts for the agent
- Check the value of the RAILS_ENV environment variable
- Deploy commit abc123def456 to Hatchbox and track the activity status
- Delete the UNUSED_VAR variable from my Rails app settings
How to install hatchbox
Platform CLI
claude mcp add --env HATCHBOX_API_KEY=<HATCHBOX_API_KEY> --env HATCHBOX_ACCOUNT_ID=<HATCHBOX_ACCOUNT_ID> --env HATCHBOX_APP_ID=<HATCHBOX_APP_ID> --env HATCHBOX_DEPLOY_KEY=<HATCHBOX_DEPLOY_KEY> --env WEB_SERVER_IP_ADDRESS=<WEB_SERVER_IP_ADDRESS> --transport stdio hatchbox -- npx -y hatchbox-mcp-serverReplace <…> with your own values. 4 more environment variables are in the server README
Platform CLI
codex mcp add hatchbox --env HATCHBOX_API_KEY=<HATCHBOX_API_KEY> --env HATCHBOX_ACCOUNT_ID=<HATCHBOX_ACCOUNT_ID> --env HATCHBOX_APP_ID=<HATCHBOX_APP_ID> --env HATCHBOX_DEPLOY_KEY=<HATCHBOX_DEPLOY_KEY> --env WEB_SERVER_IP_ADDRESS=<WEB_SERVER_IP_ADDRESS> -- npx -y hatchbox-mcp-serverReplace <…> with your own values. 4 more environment variables are in the server README
Config file
{
"mcpServers": {
"hatchbox": {
"command": "npx",
"args": [
"-y",
"hatchbox-mcp-server"
],
"env": {
"HATCHBOX_API_KEY": "<HATCHBOX_API_KEY>",
"HATCHBOX_ACCOUNT_ID": "<HATCHBOX_ACCOUNT_ID>",
"HATCHBOX_APP_ID": "<HATCHBOX_APP_ID>",
"HATCHBOX_DEPLOY_KEY": "<HATCHBOX_DEPLOY_KEY>",
"WEB_SERVER_IP_ADDRESS": "<WEB_SERVER_IP_ADDRESS>"
}
}
}
}Replace <…> with your own values. 4 more environment variables are in the server README
Config file
{
"servers": {
"hatchbox": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"hatchbox-mcp-server"
],
"env": {
"HATCHBOX_API_KEY": "<HATCHBOX_API_KEY>",
"HATCHBOX_ACCOUNT_ID": "<HATCHBOX_ACCOUNT_ID>",
"HATCHBOX_APP_ID": "<HATCHBOX_APP_ID>",
"HATCHBOX_DEPLOY_KEY": "<HATCHBOX_DEPLOY_KEY>",
"WEB_SERVER_IP_ADDRESS": "<WEB_SERVER_IP_ADDRESS>"
}
}
}
}Replace <…> with your own values. 4 more environment variables are in the server README
Platform CLI
gemini mcp add -e HATCHBOX_API_KEY=<HATCHBOX_API_KEY> -e HATCHBOX_ACCOUNT_ID=<HATCHBOX_ACCOUNT_ID> -e HATCHBOX_APP_ID=<HATCHBOX_APP_ID> -e HATCHBOX_DEPLOY_KEY=<HATCHBOX_DEPLOY_KEY> -e WEB_SERVER_IP_ADDRESS=<WEB_SERVER_IP_ADDRESS> hatchbox npx -y hatchbox-mcp-serverReplace <…> with your own values. 4 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about hatchbox
How to install hatchbox in Claude Code?
Run `claude mcp add hatchbox -e HATCHBOX_API_KEY=<HATCHBOX_API_KEY> -e HATCHBOX_ACCOUNT_ID=<HATCHBOX_ACCOUNT_ID> -e HATCHBOX_APP_ID=<HATCHBOX_APP_ID> -e HATCHBOX_DEPLOY_KEY=<HATCHBOX_DEPLOY_KEY> -- npx -y hatchbox-mcp-server`. Replace placeholders with your values from Hatchbox settings.
What does the hatchbox MCP server do?
It provides tools to trigger deployments, monitor deployment activities, and view or modify environment variables for Rails apps hosted on Hatchbox.
Why does reading environment variables require SSH?
Hatchbox inspects running process environments directly on the host rather than through its REST API. You must configure WEB_SERVER_IP_ADDRESS and supply an SSH key for those read tools to work.
