Repository avatar
Other Tools
v0.1.1
active

12happy-mcp

io.github.12happyhq/12happy-mcp

Create uptime monitors, read incidents, uptime and response times, and silence alerts for deploys.

Documentation

12happy MCP server

Uptime monitoring you can talk to. This Model Context Protocol server connects 12happy to Claude, Cursor, VS Code and any other MCP client, so you can ask:

  • "Is anything down right now?"
  • "Watch https://api.example.com/health every minute and alert the #ops Slack channel."
  • "Why did the checkout monitor fail last night, and from which regions?"
  • "What was our uptime and p95 response time for the API last month?"
  • "Silence alerts for 20 minutes while I deploy."
  • "Tell me if the nightly backup stops running."

12happy checks from the US, Europe and Israel, and opens an incident only when a quorum of regions agrees that something is down, so one flaky probe doesn't page you.

What you need

  • A 12happy account on the Pro or Agency plan, which include API access. Start free, then upgrade from the console.
  • An API key: in the console, open API keys and choose Create key. Pick the scopes the assistant should have. A key with only the read scopes can't change anything.
  • Node.js 20 or later.

Install

Claude Code

claude mcp add 12happy -e TWELVEHAPPY_API_KEY=mon_live_... -- npx -y 12happy-mcp

Claude Desktop

Add this to claude_desktop_config.json (Settings → Developer → Edit Config), then restart Claude:

{
  "mcpServers": {
    "12happy": {
      "command": "npx",
      "args": ["-y", "12happy-mcp"],
      "env": { "TWELVEHAPPY_API_KEY": "mon_live_..." }
    }
  }
}

Cursor

Add the same block to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project.

VS Code

Add this to .vscode/mcp.json. VS Code asks for the key once and stores it securely:

{
  "inputs": [
    { "type": "promptString", "id": "twelvehappy-key", "description": "12happy API key", "password": true }
  ],
  "servers": {
    "12happy": {
      "command": "npx",
      "args": ["-y", "12happy-mcp"],
      "env": { "TWELVEHAPPY_API_KEY": "${input:twelvehappy-key}" }
    }
  }
}

Tools

ToolWhat it does
get_overviewMonitors up, down, slow and paused; open incidents; uptime over N days
list_monitorsAll monitors, filterable by status or text
get_monitorOne monitor's settings and latest results per region
get_uptime_reportUptime % and p50/p95/p99 response time for any period or region
list_incidentsOutages and slowdowns, with cause and confirming regions
list_alert_channelsEmail, Slack, webhook, SMS and other channels, and their health
list_regionsWhere checks can run from
create_monitorWatch a URL, keyword, hostname (ping, DNS, SSL certificate) or TCP port, or a cron job by heartbeat: it returns the URL the job calls when it finishes
update_monitorChange target, interval, regions, keyword, timeout or slow threshold
pause_monitorPause or resume, keeping history
check_nowRun a check immediately
delete_monitorDelete a monitor and its history (assistants are told to confirm first)
acknowledge_incidentTake ownership and stop escalation
start_maintenanceSilence alerts or pause checks for a deploy
set_monitor_alertsChoose which channels a monitor alerts, with escalation delays

Read-only tools are marked as such, and delete_monitor is marked destructive, so clients that ask before risky actions will ask.

Settings

Variable
TWELVEHAPPY_API_KEYRequired. A key from the console's API keys page.
TWELVEHAPPY_ORGOptional. Agencies and resellers: the client organization to act on by default. Every tool also takes an organization argument.
TWELVEHAPPY_API_URLOptional. Defaults to https://be.12hpy.com/v1.

Security

  • The key is sent only to the 12happy API, as a bearer token, and is never logged.
  • Scopes are enforced by the API: a key without monitors:write gets a clear "missing scope" error rather than a change.
  • Revoke a key at any time from the API keys page; it stops working immediately.

Develop

npm install
npm run build
npm run inspect          # opens the MCP Inspector
node --env-file=.env test/smoke.mjs <test-organization-id>

The API reference is at be.12hpy.com/docs/api.

License

MIT

NPM
12happy-mcp
Install Command
npm install 12happy-mcp