@ionhour/mcp-server

Connect AI assistants to your Ionhour uptime monitoring workspace using the Model Context Protocol.

Quick Start

# Option 1: Interactive login (recommended)
npx @ionhour/mcp-server login

# Option 2: Set your API key manually
export IONHOUR_API_KEY=ionh_your_key_here

# Run the MCP server
npx @ionhour/mcp-server

Setup with AI Assistants

Smithery

npx -y @smithery/cli install @ionhour/mcp-server --client claude

Claude Code

claude mcp add ionhour -- npx @ionhour/mcp-server

Claude Desktop

Add to your `claude_desktop_config.json`:

{
  "mcpServers": {
    "ionhour": {
      "command": "npx",
      "args": ["@ionhour/mcp-server"],
      "env": {
        "IONHOUR_API_KEY": "ionh_your_key_here"
      }
    }
  }
}

Cursor

Add to your `.cursor/mcp.json`:

{
  "mcpServers": {
    "ionhour": {
      "command": "npx",
      "args": ["@ionhour/mcp-server"],
      "env": {
        "IONHOUR_API_KEY": "ionh_your_key_here"
      }
    }
  }
}

VS Code (Copilot)

Add to your `.vscode/mcp.json`:

{
  "servers": {
    "ionhour": {
      "command": "npx",
      "args": ["@ionhour/mcp-server"],
      "env": {
        "IONHOUR_API_KEY": "ionh_your_key_here"
      }
    }
  }
}

Windsurf

Add to your `~/.codeium/windsurf/mcp_config.json`:

{
  "mcpServers": {
    "ionhour": {
      "command": "npx",
      "args": ["@ionhour/mcp-server"],
      "env": {
        "IONHOUR_API_KEY": "ionh_your_key_here"
      }
    }
  }
}

Getting an API Key

1. Go to your Ionhour workspace Settings > API Keys

2. Create a new key with Read & Write or Read Only permission

3. Copy the key (starts with `ionh_`)

Available Tools (49)

Workspace

• `get_workspace` - Get workspace details
• `whoami` - Get API key info (workspace, user, permission level)
• `get_workspace_summary` - Overview of projects, checks by status, and active incidents
• `get_workspace_reliability` - Uptime, incident count, and MTTR over N days
• `list_team_members` - List workspace members and roles
• `send_invitation` - Invite users to the workspace

Projects

• `list_projects` / `create_project` / `update_project`

Checks (Outbound HTTP Probes)

Ionhour probes a URL you own on a schedule and alerts on failure.

• `create_check` - Create an outbound check (accepts human-readable intervals like "every 5 minutes" or "hourly")
• `list_checks` / `list_checks_by_status` / `find_check_by_name`
• `get_check_status` - Detailed status with recent probe results
• `get_check_uptime` - Uptime percentage with daily buckets
• `run_check_probe` - Probe the check on demand
• `pause_check` / `resume_check`
• `delete_check` - Permanently delete a check and its data

> `register_check` is a deprecated tombstone: it creates nothing. Use `register_job` for a heartbeat monitor or `create_check` for an outbound probe.

Jobs (Inbound Heartbeat Monitors)

Your cron/worker pings Ionhour; Ionhour alerts if a ping is late or missing.

• `register_job` - Create a Job and get its heartbeat token (accepts human-readable intervals)
• `list_jobs` / `find_job_by_name`
• `get_job_status` - Detailed status with recent heartbeats
• `get_job_uptime` - Uptime percentage with daily buckets
• `pause_job` / `resume_job`
• `delete_job` - Delete a job and its data

Signals (Heartbeat Pings)

• `send_heartbeat` - Send a success signal
• `send_failure_signal` - Report a failure
• `list_signals` - View signal history

Incidents

• `list_incidents` / `search_incidents` / `get_incident`
• `get_incident_timeline` - Incident history for a check or job
• `create_incident` / `acknowledge_incident` / `resolve_incident`
• `add_incident_note`

Deployments

• `create_deployment` - Start a deployment window (auto-pauses checks)
• `end_deployment` - End deployment and resume checks
• `list_deployments`

Dependencies

• `list_dependencies` / `get_dependency` / `create_dependency`
• `update_dependency_status`
• `delete_dependency` - Delete a dependency

Status Pages

• `list_status_pages` / `create_status_page` / `update_status_page`
• `create_announcement` - Post a status update

Alert Channels

• `list_alert_channels` / `create_alert_channel` / `update_alert_channel`
• `delete_alert_channel` - Delete a notification channel

Escalation Rules

• `list_escalation_rules` / `create_escalation_rule` / `update_escalation_rule`
• `delete_escalation_rule` - Delete an escalation rule

Resources

The server exposes reference data that AI assistants can browse without calling tools:

Prompts

Pre-built workflow templates that guide AI assistants through multi-step operations:

CLI Commands

npx @ionhour/mcp-server [command] [options]

Commands:
  (default)     Start the MCP server (stdio proxy mode)
  setup         Interactive wizard — install MCP server into your editors
  login         Authenticate via browser and store API key
  logout        Remove stored credentials
  whoami        Show current authentication status

Options:
  --api-key KEY     Ionhour API key (or set IONHOUR_API_KEY env var)
  --base-url URL    MCP base URL (default: https://mcp.ionhour.com)
  --version, -v     Show version
  --help, -h        Show help

Environment Variables:
  IONHOUR_API_KEY   API key for authentication
  IONHOUR_BASE_URL  Base URL override
  IONHOUR_AUTH_URL  Keycloak auth server URL (for login)
  IONHOUR_REALM     Keycloak realm name (for login)

`setup`

Interactive wizard that detects installed editors (Cursor, Claude Desktop, VS Code, Claude Code, Windsurf) and writes the Ionhour MCP server configuration into each one. Prompts for login if no credentials are stored:

npx @ionhour/mcp-server setup

`login`

Opens your browser to authenticate with Ionhour, then automatically creates and stores an API key:

npx @ionhour/mcp-server login

Credentials are stored at `~/.config/ionhour/credentials.json` (file permissions: 600).

After login, you can run the MCP server without setting `IONHOUR_API_KEY`.

`logout`

Removes stored credentials from `~/.config/ionhour/credentials.json`:

npx @ionhour/mcp-server logout

`whoami`

Shows the current authentication status — the workspace, user, and permission level associated with the stored API key:

npx @ionhour/mcp-server whoami

How It Works

This package runs a local MCP server over stdio that proxies requests to the Ionhour API. Your AI assistant communicates with this local server, which forwards tool calls to your Ionhour workspace.

AI Assistant  @ionhour/mcp-server  Ionhour API

Documentation

• MCP Integration Guide — Full setup, architecture, and complete tool reference with parameters
• MCP Prompts & Workflows — Prompt documentation, project rules, and best practices

Requirements

• Node.js >= 18
• An Ionhour account with an API key

License

MIT