0.1.19 • Published 4d agoCLI

@ionhour/mcp-server

Licence

MIT

Version

0.1.19

Deps

Size

65 kB

Vulns

Weekly

Summary Dependency Versions

@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

Go to your IonHour workspace Settings > API Keys
Create a new key with Read & Write or Read Only permission
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 (Monitors)

register_check - Create a monitoring 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 signals
get_check_uptime - Uptime percentage with daily buckets
pause_check / resume_check
delete_check - Permanently delete a check and its data

Signals (Heartbeats)

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
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:

URI	Description
`ionhour://enums`	All IonHour enums (check statuses, incident states, severities, etc.)
`ionhour://checks/schema`	Check creation schema with field constraints and status lifecycle
`ionhour://help/ping-formats`	Heartbeat integration examples (curl, Node, Python, cron, CI/CD)
`ionhour://tools/catalog`	Catalog of all tools organized by domain with descriptions
`ionhour://guides/workflows`	Common workflow patterns and best practices

Prompts

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

Prompt	Args	Description
`diagnose_incident`	`incidentId`	Step-by-step incident investigation
`setup_monitoring`	`serviceName`	Guided new-service monitoring setup
`deployment_checklist`	`projectId`	Pre/during/post-deploy workflow
`weekly_reliability_report`	`daysBack?`	Generate a reliability summary
`triage_all_incidents`	—	List and triage all active incidents
`status_page_incident`	`incidentId`	Communicate an incident through status pages
`dependency_health_audit`	—	Audit all dependencies and assess health impact

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)

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

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 <--stdio--> @ionhour/mcp-server <--HTTPS--> 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

Keywords

mcp model-context-protocol ionhour monitoring uptime