MCP server for AI tools

The SutramX MCP server lets AI assistants and agents work with your SutramX workspace through the Model Context Protocol. Once connected, you can ask Claude, Cursor or any other MCP client things like "which monitors are down right now?", "why is checkout down?" or "acknowledge the checkout incident", and it uses SutramX tools to answer.

The server is the npm package @sutramx/mcp-server, listed in the MCP Registry as io.github.SutramX/mcp-server. The source is at github.com/SutramX/mcp-server.

How it works#

The server calls the public SutramX API with a workspace API key. It can do exactly what that key can do and nothing more: it can't see other workspaces, billing, team members or API keys. Plan limits apply exactly as in the dashboard.

There are two ways to run it:

1. Create an API key#

Open Account settings → API keys → Create API key. Keys start with sk_ and are shown only once. Whether you can create API keys depends on your plan: see Plans & limits.

Choose the access level for what you want the assistant to do. The level is fixed when the key is created.

A read-only key is the safest choice for assistants that only look things up (triage, reporting): even an assistant that is tricked by text it reads can't change anything. Use a Standard key only for an assistant that really needs to make changes.

2. Connect your client#

For a local (stdio) connection, MCP clients start the npm package @sutramx/mcp-server (Node.js 20 or newer) with npx, as in the examples below.

Claude Code#

claude mcp add sutramx \
  --env SUTRAMX_API_KEY=sk_your_key \
  -- npx -y @sutramx/mcp-server

Or share it with your team through a .mcp.json file in your project. Keep the key out of version control by reading it from the environment:

{
  "mcpServers": {
    "sutramx": {
      "command": "npx",
      "args": ["-y", "@sutramx/mcp-server"],
      "env": { "SUTRAMX_API_KEY": "${SUTRAMX_API_KEY}" }
    }
  }
}

Claude Desktop#

Edit claude_desktop_config.json:

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

{
  "mcpServers": {
    "sutramx": {
      "command": "npx",
      "args": ["-y", "@sutramx/mcp-server"],
      "env": { "SUTRAMX_API_KEY": "sk_your_key" }
    }
  }
}

Restart Claude Desktop. Then try: "Which SutramX monitors are down right now, and since when?"

Cursor#

Add the server to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "sutramx": {
      "command": "npx",
      "args": ["-y", "@sutramx/mcp-server"],
      "env": { "SUTRAMX_API_KEY": "sk_your_key" }
    }
  }
}

Other MCP clients#

Any client that can start a local (stdio) MCP server works. Configure:

• Command: npx
• Arguments: -y @sutramx/mcp-server
• Environment: SUTRAMX_API_KEY=sk_your_key

Connect over HTTP#

SutramX runs the server at https://api.sutramx.com/mcp. Send your key as a bearer token on every request:

POST /mcp HTTP/1.1
Host: api.sutramx.com
Authorization: Bearer sk_your_key
Content-Type: application/json
Accept: application/json, text/event-stream

For example, in Claude Code:

claude mcp add --transport http sutramx https://api.sutramx.com/mcp \
  --header "Authorization: Bearer sk_your_key"

The HTTP endpoint is stateless and answers with JSON. A request without credentials gets HTTP 401 with a sign-in challenge. Clients that support MCP sign-in (OAuth), such as a Claude.ai connector, can use it instead of an API key: you sign in to SutramX, choose the workspace and approve the app. Apps connected this way are listed under Account settings → Authorized apps, where you can revoke them. An app connected by a viewer, or without write access, gets only the read tools.

On the hosted endpoint, the destructive tools (the two delete tools and sutramx_set_status_page_monitors) are never offered, and publishing is off (see Tool modes). You can still narrow a client to the read tools with a request header:

claude mcp add --transport http sutramx https://api.sutramx.com/mcp \
  --header "Authorization: Bearer sk_your_key" \
  --header "X-SutramX-Read-Only: true"

Tool modes#

You, not the assistant, decide which tools the server offers. Tools that aren't offered are hidden from the assistant completely.

• The values true, 1, yes and on all switch a mode on.
• Read-only wins: with both set, the destructive tools stay hidden.
• Without destructive mode, the server also refuses actions that change what the public sees: sutramx_create_status_page creates pages that aren't public, sutramx_update_status_page can't change is_public or slug and can't edit a page that is already public, and sutramx_add_incident_note can't post a public update. Do those in the dashboard.
• On a server you run with --http, the environment variables apply to every request. A header can narrow a request to read-only, but can't turn off a read-only mode set in the server's environment.
• Read-only mode hides the write tools; a read-only API key makes SutramX refuse every change. Use both for an assistant that should only look.

For a local server, add the variable to the env block of your client config, next to SUTRAMX_API_KEY:

"env": { "SUTRAMX_API_KEY": "sk_your_key", "SUTRAMX_READ_ONLY": "true" }

Configuration#

These environment variables apply when you run the server yourself.

Running your own HTTP server:

PORT=3333 npx -y @sutramx/mcp-server --http

The endpoint is then POST http://127.0.0.1:3333/mcp, and GET /health returns the server version.

• While the server listens on loopback (the default), SUTRAMX_API_KEY is used for requests that send no Authorization header. A header that isn't a valid credential is rejected with 401, never replaced by the server's key.
• With NODE_ENV=production, the HTTP server won't start unless OAUTH_RESOURCE_PROXY_SECRET is set or MCP_OAUTH=off. For a self-hosted server that only takes API keys, set MCP_OAUTH=off.
• With any other HOST, the environment key is ignored and every request must send its own key. Put the server behind HTTPS, and set MCP_ALLOWED_HOSTS to keep DNS-rebinding protection when binding to 0.0.0.0.
• Browser requests are accepted only from a loopback origin or one listed in MCP_ALLOWED_ORIGINS. Requests without an Origin header are always allowed.

Tools#

The server has 26 tools. "Read" tools never change anything and are always offered; "Write" tools are hidden in read-only mode and refused for a read-only key; "Destructive" tools are offered only in destructive mode (see Tool modes).

Most read tools take an optional response_format: markdown (a readable summary, the default) or json (the full structured data).

Account and regions#

Monitors#

Parameter details:

• status on sutramx_list_monitors is one of up, down, degraded, paused, pending, maintenance. search matches the name or URL.
• type is http, api, ping, port, udp, cron, dns, multistep or mcp (an mcp monitor needs an https:// url). interval_seconds is 15–900 and not below your plan's minimum. tags are up to 20 lower-case labels of up to 32 characters. regions are location codes such as ["fra1", "usa-az-probe"].
• config holds type-specific settings, for example {"timeout": 10000, "expected_status_codes": [200], "keyword": "ok"} for HTTP, {"host": "db.example.com", "port": 5432} for a port check, or {"cron_expression": "*/5 * * * *"} for a heartbeat.
• Stored credentials in a monitor's config (secret headers, tokens, passwords) are shown to the assistant as [REDACTED]. When it sends [REDACTED] back in an update, the stored value is kept.
• On sutramx_update_monitor, config replaces the whole config object and regions replaces the locations. The assistant is told to read the monitor first and send the merged config. The type can't be changed.
• sutramx_create_monitor with a key behaves like monitors as code: the monitor is created once and updated on later calls. Without a key, every call creates a new monitor.
• sutramx_run_check is refused for paused monitors and is rate limited to 30 per 5 minutes.
• On sutramx_get_check_results, status is up, down, degraded or problem (every check that wasn't up). Page back with before set to the next_before value of the previous page.

Incidents#

sutramx_explain_incident answers questions like "why is checkout down?", "was that alert real?" or "is it us or Stripe?" from the same deterministic explanation as the dashboard's Why this alert panel, on every plan:

• For a monitor with an open incident it explains that incident. Without one, it explains the monitor's current state per region and, unless include_last_incident is false, its most recent incident.
• outcome is ongoing, resolved, healthy, failing_unconfirmed (failing checks, but too few regions agree for an incident), no_data, paused or ambiguous. in_maintenance is true while a maintenance window silences alerts, and incidents_total is 0 for a monitor that never had an incident.
• fault is yours, external (a vendor or third party), checker (our checker, not your site) or unknown. Regions whose checks were blocked by bot protection or were inconclusive on our side abstain and are not counted toward the quorum.
• Vendor signals say how many SutramX accounts saw the same vendor fail only as several or many, never an exact number or who they are.
• When several monitors match monitor, the tool lists up to 10 of them and the assistant asks which one you mean.

from and to are ISO-8601 times. A note with public: true is published as a public update instead of an internal team note; this needs destructive mode. Incidents also resolve automatically when checks recover, so manual resolution is only for when you know the issue is fixed.

Status pages#

hide_powered_by and favicon_url work only on plans with white-label status pages. logo_url and favicon_url must be https:// URLs. other_fields accepts the same settings nested in one object, for clients that send them that way; anything else is refused. Monitors left out of sutramx_set_status_page_monitors are removed from the page, not deleted, and an empty list is refused unless remove_all is true. Custom domains are managed in the dashboard.

Uptime reports and maintenance windows#

• In the uptime report, degraded (slow) checks count as up. SLO targets are set in the dashboard; without them the SLO part is empty. See Reliability insights.
• The maintenance status filter uses the window's live state, so a scheduled window whose start time has passed counts as ongoing. Alerts are silenced while a window is active. The assistant can only list windows: the workspace owner creates and changes them in the dashboard, see Maintenance windows.

Safety#

• Scope. The server can only do what the API key can do, in that key's workspace. It has no tools for alert channels, maintenance windows, billing, team members or API keys.
• Read-only keys. With a read-only key, SutramX itself refuses every change, whatever the assistant tries.
• Tool modes. Destructive tools and public-facing changes are off unless the server operator enables them, and read-only mode hides every write tool.
• Session limits. The server makes at most 20 changes a minute, 200 an hour and 10 monitor pauses an hour per session (per API key over HTTP). Beyond that it refuses with "session limit of this MCP server".
• Tool hints. Every tool is annotated as read-only or not, and the destructive tools are marked destructive. Clients that support these hints ask you before running a destructive tool, and the tool descriptions tell the assistant to confirm with you first.
• Untrusted text. Error messages, notes and names come from monitored websites or other people. The server tells the assistant to treat them as data, never as instructions.
• Revoking access. Delete the API key in Account settings → API keys, or revoke a signed-in app in Account settings → Authorized apps; the server's requests then fail.

Example prompts#

• "Give me a health summary of my SutramX workspace."
• "Which monitors are down or degraded, and since when?"
• "Why is the checkout API down? Is it us or a vendor?"
• "Was last night's alert on the homepage a real outage?"
• "Show the failed checks for the checkout API in the last hour, by region."
• "Give me a 90-day uptime report with incident counts and MTTR for every monitor."
• "Is a maintenance window active right now?"
• "Run a check on the homepage monitor now."
• "Create an HTTP monitor for https://example.com/health every minute from fra1 and usa-az-probe, tagged prod."
• "Pause every monitor tagged staging."
• "Acknowledge the ongoing incident on the payments API and add a note that we're rolling back."
• "Which status pages show the checkout API monitor?"

Troubleshooting#