Skip to content
Truto
Truto Blog
Back
AI & Agents

Connect Freshstatus to Claude: Control Maintenance and Status Pages

Learn how to connect Freshstatus to claude using Truto. Step-by-step guide to tool calling, API quirks, and autonomous workflows.

Yuvraj Muley Yuvraj Muley · · 9 min read
Connect Freshstatus to Claude: Control Maintenance and Status Pages

If your IT operations or DevOps team needs to connect Freshstatus to Claude to automate incident logging, update service health, or schedule maintenance windows, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and the Freshstatus REST API. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT, check out our guide on connecting Freshstatus to ChatGPT or explore our broader architectural overview on connecting Freshstatus to AI Agents.

Giving a Large Language Model (LLM) read and write access to your public-facing status page is an engineering challenge with high stakes. You have to handle API authentication, map complex JSON schemas to MCP tool definitions, and deal with Freshstatus-specific data constraints. Every time Freshstatus updates an endpoint or changes a required payload structure, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Freshstatus, connect it natively to Claude Desktop, and execute complex incident management workflows using natural language.

The Engineering Reality of the Freshstatus API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools over JSON-RPC, the reality of implementing it against the Freshstatus API requires careful domain mapping.

If you decide to build a custom MCP server for Freshstatus, here are the specific integration challenges you will face:

Hierarchical Service Mapping Incidents and maintenance windows in Freshstatus do not exist in a vacuum; they must be mapped to specific affected_components. An LLM cannot simply say "The database is down." It needs to query the list_all_freshstatus_services endpoint, extract the UUID of the specific database component, and inject that array of IDs into the incident creation payload. Your MCP server must expose discovery tools alongside write tools to ensure the LLM can resolve these relational dependencies.

Stateful Lifecycle Transitions and Strict Datetimes Freshstatus enforces strict state transitions. You cannot simply use a generic PATCH endpoint to move an incident to "resolved" or a maintenance to "completed." Instead, the API requires specific operational endpoints (e.g., freshstatus_incidents_resolve or freshstatus_maintenance_start). Furthermore, the API enforces rigid UTC timestamp requirements for fields like start_time and end_time (e.g., YYYY-MM-DDThh:mm:ssZ). If your MCP tool schemas do not explicitly instruct the LLM on this format, the API will reject the payloads.

Visibility and Notification Blast Radii When creating an incident update, the is_private and notification_options fields determine whether an update is an internal note or an email blasted to your entire customer base. Hardcoding these flags in a custom integration is dangerous. A well-designed MCP server exposes these parameters explicitly in the JSON Schema with descriptive text, forcing the LLM to make a conscious decision about the blast radius of its communications.

Rate Limit Exposure During a major outage, automated systems and panicked engineers often spam the status page API. Freshstatus enforces rate limits. It is a critical architectural decision that Truto does not retry, throttle, or apply backoff on rate limit errors natively. When the Freshstatus API returns an HTTP 429, Truto passes that error directly to the caller, normalizing the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The LLM agent is responsible for reading these headers and executing its own retry/backoff logic. Absorbing 429s at the integration layer leads to silent failures and timeout mismatches; passing them through gives the agent deterministic control.

Generating a Freshstatus MCP Server with Truto

Truto dynamically generates MCP tools from an integration's underlying resource definitions and API documentation. Rather than hand-coding a custom Node.js or Python server, you can generate a secure endpoint in seconds.

There are two ways to spin up an MCP server for Freshstatus via Truto.

Method 1: Via the Truto UI

This is the fastest path for IT admins setting up local AI assistants.

  1. Log into Truto and connect a Freshstatus account (providing your Freshstatus API credentials).
  2. Navigate to the Integrated Accounts page for that connection.
  3. Click the MCP Servers tab.
  4. Click Create MCP Server.
  5. Select your desired configuration (e.g., give it a name like "Freshstatus Ops", filter allowed methods, or set an expiration date).
  6. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto API

For platform engineers dynamically provisioning AI workspaces for on-call engineers, you can generate MCP servers programmatically.

Make an authenticated POST request to the /integrated-account/:id/mcp endpoint:

curl -X POST https://api.truto.one/integrated-account/YOUR_INTEGRATED_ACCOUNT_ID/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "On-Call Freshstatus Access",
    "config": {
      "methods": ["read", "write", "custom"]
    },
    "expires_at": "2025-12-31T23:59:59Z"
  }'

The API will return a JSON object containing the secure url. This URL encodes the specific integrated account and configuration, meaning it is self-contained. The client needs no additional configuration.

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, connecting it to Claude requires configuring the client to use the SSE (Server-Sent Events) transport.

Method A: Via the Claude Desktop UI

If you are using an AI client with a UI for tool management (similar to ChatGPT's custom connectors):

  1. Open your Claude Desktop settings.
  2. Navigate to Integrations or MCP Servers -> Add MCP Server.
  3. Paste the Truto MCP URL.
  4. Click Add. Claude will immediately send an initialize JSON-RPC request to discover the Freshstatus tools.

Method B: Via Manual Configuration File (Claude Desktop)

Claude Desktop primarily relies on a configuration file to instantiate MCP servers. You will use the official @modelcontextprotocol/server-sse package to connect to Truto's remote URL.

Locate your Claude configuration file:

  • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Freshstatus server to the mcpServers object:

{
  "mcpServers": {
    "freshstatus-ops": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_SECURE_TOKEN"
      ]
    }
  }
}

Restart Claude Desktop. The app will spawn the SSE proxy, connect to Truto, and pull in the Freshstatus tool schemas.

Freshstatus Hero Tools for AI Agents

Truto exposes the full surface area of the Freshstatus API, but certain tools are critical for high-leverage IT operations. Here are the 6 "hero tools" your agent will use most often.

list_all_freshstatus_services

Before logging an incident, the LLM must know what services exist and what their unique id values are. This tool returns the building blocks of your status page.

Contextual usage: Claude should call this first to map human-readable system names (e.g., "Billing API") to Freshstatus service IDs.

"List all the services on our status page so I can find the IDs for the US-East Database and the Checkout Gateway."

create_a_freshstatus_incident

Logs a new downtime event. This tool requires the title, start_time, and end_time (even if estimated). The LLM can also set is_private and attach the affected_components discovered previously.

Contextual usage: Used immediately upon confirming an outage. Ensure Claude knows to format times in strict UTC ISO format.

"Create a public incident titled 'Elevated API Latency'. Set the start time to right now, attach the Checkout Gateway service ID, and note that we are currently investigating the root cause."

create_a_freshstatus_incident_update

Adds a timeline update to an ongoing incident. This is vital for keeping stakeholders informed as the DevOps team works the problem.

Contextual usage: Claude will need the incident_id to post the update. It can also adjust notification_options to send emails to subscribers.

"Post an update to the 'Elevated API Latency' incident. The message is: 'We have identified a database locking issue and are rolling back the recent deployment.' Do not send an email notification for this update."

freshstatus_incidents_resolve

Closes out an active incident. This is a custom method mapped specifically to the Freshstatus resolution endpoint, separate from generic update tools.

Contextual usage: Called when the systems return to nominal operations.

"Resolve the 'Elevated API Latency' incident. Add a message stating 'All systems have recovered and latency has returned to baseline levels.'"

create_a_freshstatus_maintenance

Schedules a planned downtime window. Like incidents, this requires title and timestamps, but includes flags like is_auto_start and is_auto_end.

Contextual usage: Used during sprint planning or pre-deployment checklists to warn customers of impending maintenance.

"Schedule a maintenance window for this Saturday from 02:00 UTC to 04:00 UTC. Title it 'Q3 Database Upgrades'. Affect the US-East Database service and set it to auto-start."

freshstatus_maintenance_start

Manually kicks off a scheduled maintenance window, changing its status on the public page.

Contextual usage: If is_auto_start was not used, an engineer can instruct Claude to start the maintenance when they actually begin the database work.

"Start the 'Q3 Database Upgrades' maintenance window right now. Add an update message saying 'Maintenance has begun.'"

To view the complete inventory of available Freshstatus tools, including schemas for Service Groups and Incident Statuses, visit the Freshstatus integration page.

Workflows in Action

MCP tools are powerful individually, but their real value emerges when Claude chains them together to handle complex operational scenarios.

Scenario 1: The 3 AM Sev-1 Outage Escalation

An on-call engineer gets paged for a database failure. Instead of navigating the Freshstatus UI while trying to read Datadog logs, they ask Claude to handle the external communications.

"We have a Sev-1 on the main database. Look up the ID for 'Production Database', create a public incident saying we are investigating an outage, and make sure it doesn't auto-resolve."

How the agent executes this:

  1. Calls list_all_freshstatus_services to retrieve the list of services.
  2. Filters the JSON response to find the id for the service named "Production Database".
  3. Calls create_a_freshstatus_incident with the current UTC timestamp for start_time, injects the service ID into affected_components, and sets the status to investigating.

Result: The status page is updated in seconds, alerting customers while the engineer keeps their focus entirely on the terminal to fix the database.

Scenario 2: Scheduled Maintenance Execution

A DevOps team is preparing for a scheduled zero-downtime cluster rotation. They use Claude to manage the communication lifecycle of the maintenance.

sequenceDiagram
    participant User as DevOps Engineer
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant API as Freshstatus API

    User->>Claude: "Schedule maintenance for the API Gateway tomorrow at 10 PM UTC."
    Claude->>MCP: Call list_all_freshstatus_services
    MCP->>API: GET /services
    API-->>MCP: [ { "id": "api-gw-123", "name": "API Gateway" } ]
    MCP-->>Claude: Return service list
    Claude->>MCP: Call create_a_freshstatus_maintenance
    MCP->>API: POST /maintenance { "title": "API Gateway Rotation" ... }
    API-->>MCP: 201 Created (ID: maint-999)
    MCP-->>Claude: Return maintenance ID
    Claude-->>User: "Maintenance scheduled successfully."

"Start the API Gateway rotation maintenance now, and add an update saying traffic is being rerouted."

How the agent executes this:

  1. Claude recalls the maintenance_id from the previous context window.
  2. Calls freshstatus_maintenance_start using the ID and includes the update text in the payload.
  3. The Freshstatus public page updates to show the maintenance is actively underway.

Result: Operations are synchronized perfectly with public communications without requiring a human to context-switch into the Freshstatus dashboard.

Security and Access Control

Giving an LLM the ability to post public incidents requires strict governance. Truto provides several mechanisms to lock down your Freshstatus MCP server:

  • Method Filtering: Configure the MCP token with methods: ["read"] to allow Claude to query current incident statuses and service IDs, but block it from creating or resolving incidents.
  • Tag Filtering: Limit the server to specific operational subsets by specifying tags. For example, you can expose only maintenance tools while hiding incident tools.
  • Require API Token Auth: By setting require_api_token_auth: true, possession of the MCP URL is no longer enough. The client must also pass a valid Truto API token or session cookie in the Authorization header, enforcing identity-bound access to the status page.
  • Expiration Timers: Use expires_at to create temporary MCP servers. If a contractor is helping with a weekend infrastructure migration, you can generate a server that automatically revokes itself on Monday morning, preventing lingering access to your status communications.

Stop Context Switching During Outages

When systems go down, every second counts. Forcing engineers to tab away from their monitoring tools to write status page updates in a web UI prolongs the outage. By connecting Freshstatus to Claude via a managed MCP server, you turn your AI assistant into a dedicated incident communications manager.

The LLM handles the exact timestamp formatting, resolves service dependencies, and formats the updates perfectly, allowing your human engineers to focus on restoring service.

More from our Blog