MCP Integration
Connect AI assistants to IonHour using the Model Context Protocol.
IonHour implements an MCP (Model Context Protocol) server that lets AI assistants like Claude, Cursor, and other MCP-compatible tools interact with your monitoring infrastructure through natural language.
Quick Setup
Connect IonHour to Claude Code:
claude mcp add ionhour -- npx @ionhour/mcp-serverOr connect directly to the HTTP endpoint:
claude mcp add --transport http ionhour https://app.failsignal.com/mcp \
--header "Authorization: Bearer ionh_your_api_key"Authentication
The MCP endpoint uses API keys for authentication (not OAuth tokens). Create an API key in Settings > API Keys, then pass it as a Bearer token.
The MCP server is workspace-scoped — all operations are limited to the workspace the API key belongs to.
Available Tools
The MCP server exposes these tools that AI assistants can call:
get_workspace
Returns details about the current workspace.
Parameters: None
Returns: Workspace ID, name, plan, and creation date.
list_projects
Lists all projects in the workspace.
Parameters: None
Returns: Array of projects with ID, name, environment, and creation date.
create_project
Creates a new project in the workspace.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Project name |
environment | string | No | prod or staging |
register_check
Creates a new inbound (heartbeat) check.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Check name |
projectId | number | Yes | Project to associate with |
intervalSeconds | number | Yes | Ping interval (300–3,600 seconds) |
graceSeconds | number | No | Grace period (5–60 seconds, default: 20) |
Returns: Check ID, name, token, schedule, status, and the full ping URL.
list_checks
Lists checks in the workspace, optionally filtered by project.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
projectId | number | No | Filter by project |
Returns: Array of checks with ID, name, token, status, display status, schedule, last ping time, and next due time.
get_check_status
Returns detailed status for a single check, including recent signals.
Parameters: Provide one of:
| Name | Type | Description |
|---|---|---|
checkId | number | Check ID |
token | string | Check token |
Returns: Full check details plus the 10 most recent signals.
pause_check
Pauses a check so it stops alerting on missed signals.
Parameters: Provide one of:
| Name | Type | Description |
|---|---|---|
checkId | number | Check ID |
token | string | Check token |
resume_check
Resumes a paused check.
Parameters: Provide one of:
| Name | Type | Description |
|---|---|---|
checkId | number | Check ID |
token | string | Check token |
send_heartbeat
Sends a heartbeat signal for a check. This triggers the full monitoring pipeline — status updates, incident resolution, dependency evaluation, and real-time broadcasts.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
token | string | Yes | Check token |
payload | object | No | Arbitrary JSON metadata |
source | string | No | Signal source identifier (default: mcp-agent) |
list_signals
Returns signal history for a check.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
token | string | Yes | Check token |
page | number | No | Page number (default: 1) |
limit | number | No | Items per page (default: 20) |
list_incidents
Lists incidents in the workspace.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
state | string | No | Filter by ACTIVE or RESOLVED |
Example Conversations
Check on your monitoring
You: Are all my production checks healthy?
AI: Let me check. [calls list_checks] You have 12 checks across 3 projects. 11 are OK. "payment-processor" in the Billing project has been DOWN since 14:23 UTC — there's an active critical incident.
Create a new check
You: I need to monitor a new backup script that runs every 6 hours.
AI: [calls list_projects] Which project should I add it to? You have "API", "Workers", and "Infrastructure".
You: Infrastructure.
AI: [calls register_check] Done. Created "Backup Script" check with a 6-hour interval. Here's your ping URL:
https://app.failsignal.com/api/signals/ping/abc123...— add a curl to this URL at the end of your backup script.
Investigate an incident
You: What's going on with the payment processor check?
AI: [calls get_check_status] The "payment-processor" check has been DOWN since 14:23 UTC. The last successful signal was at 14:18 UTC. Looking at the recent signals, I can see 3 consecutive FAIL signals after that. The check runs every 5 minutes with a 30-second grace period. This looks like it went down about 40 minutes ago.
Technical Details
Transport
The MCP server uses stateless HTTP transport (JSON-RPC 2.0 over HTTP POST). Each request is self-contained with no server-side session state.
Endpoint: POST /mcp
Rate Limits
The MCP endpoint follows the default API rate limit: 100 requests per 60 seconds per client IP.
Error Handling
When a tool encounters an error, it returns a structured error response that the AI assistant can interpret and communicate to you:
- 401 Unauthorized — Invalid or missing API key
- 403 Forbidden — API key doesn't have access to the requested workspace
- 404 Not Found — Resource doesn't exist
- Validation errors — Invalid parameters (e.g., interval out of range)