SutramX

SutramX MCP server

A Model Context Protocol server that lets AI agents and assistants (Claude Code, Claude Desktop and other MCP clients) work with your SutramX workspace: list and change monitors, read check results, handle incidents and manage status pages.

It talks to the public SutramX API with a workspace API key, so it can do exactly what that key can do and nothing more.

Tools

Destructive tools are annotated with destructiveHint, so clients that support it ask before running them. Read tools carry readOnlyHint and openWorldHint: false (they only read your workspace); tools that make SutramX contact outside targets, publish, or notify people carry openWorldHint: true.

Access modes

Agents can be steered by text they read (prompt injection), so the user, not the agent, chooses which tools the server offers. Tools that are not allowed are not registered at all: the agent never sees them.

Destructive mode covers everything that deletes data or changes what the public sees:

• the delete tools and sutramx_set_status_page_monitors (it can take monitors off a page) are registered only in destructive mode;
• sutramx_update_status_page refuses slug and is_public changes (publishing, unpublishing or moving a page) and any change to a page that is public (title, logo, colours and the rest are visible to everyone), sutramx_create_status_page creates pages not public, and sutramx_add_incident_note refuses public: true (status page updates) outside destructive mode.

Notes:

• Both settings are off by default. true, 1, yes and on (any case) turn a setting on; anything else leaves it off. No tool argument can change them.
• Read-only wins: with read-only on, the destructive tools stay hidden even in destructive mode.
• HTTP mode: SUTRAMX_READ_ONLY=true on the server makes every request read-only whatever the headers say, and X-SutramX-Read-Only: true narrows one client. SUTRAMX_ALLOW_DESTRUCTIVE=true on the server enables destructive mode for every request that is not read-only. X-SutramX-Allow-Destructive: true is ignored unless the operator also set SUTRAMX_HTTP_ALLOW_DESTRUCTIVE_HEADER=true.
• There is no tool that sends test notifications, emails, SMS or calls to arbitrary recipients, reads local files, runs commands or fetches arbitrary URLs.

Safety limits

Tools that change data are rate limited per session (stdio: the process; HTTP: the API key): at most SUTRAMX_MAX_WRITES_PER_MINUTE (default 20) and SUTRAMX_MAX_WRITES_PER_HOUR (default 200) changes, and outside destructive mode at most SUTRAMX_MAX_PAUSES_PER_HOUR (default 10) monitor pauses. Over the limit the tool answers with an error telling the agent to involve the user; the API's own per-key limits apply on top.

• Use read-only mode for assistants that only need to look (triage, reporting), ideally together with a Read-only API key (below).

1. Create an API key

In SutramX, open Settings → API keys → Create API key. Keys start with sk_ and are shown once.

Recommended for agents: a Read-only key. It can call every "no" tool above, and the SutramX API itself refuses every change it attempts (403 READ_ONLY_ACCESS), so a leaked key or a prompt-injected agent cannot create, pause, acknowledge, resolve or delete anything. This holds even if the server's own read-only mode is off; combine both (SUTRAMX_READ_ONLY=true hides the write tools from the agent as well). Use a Standard key only for an agent that really needs to change things; it is enough for every tool above.

2. Build

cd mcp-server

npm install npm run build

Node.js 20 or newer is required.

3. Connect a client

Claude Code

claude mcp add sutramx \

--env SUTRAMX_API_KEY=sk_your_key \ -- node /absolute/path/to/mcp-server/dist/index.js

Or add it to .mcp.json in a project:

{

"mcpServers": { "sutramx": { "command": "node", "args": ["/absolute/path/to/mcp-server/dist/index.js"], "env": { "SUTRAMX_API_KEY": "sk_your_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": "node", "args": ["/absolute/path/to/mcp-server/dist/index.js"], "env": { "SUTRAMX_API_KEY": "sk_your_key" } } } }

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

Streamable HTTP (remote or shared)

PORT=3333 node dist/index.js --http

The endpoint is POST http://127.0.0.1:3333/mcp (stateless, JSON responses). Every request must send its own SutramX key:

Authorization: Bearer sk_your_key

so one server can serve several users and workspaces. Each key only ever reaches its own workspace. Connect Claude Code to it with:

claude mcp add --transport http sutramx http://127.0.0.1:3333/mcp \

--header "Authorization: Bearer sk_your_key"

When the server listens on loopback (the default, HOST=127.0.0.1), SUTRAMX_API_KEY is used for requests that send no Authorization header (a header that is not a SutramX key is rejected with 401). Browser requests (any request with an Origin header, localhost pages included) are refused unless that origin is listed in MCP_ALLOWED_ORIGINS, so a local dev server or other localhost web app cannot use your key. To use a browser-based client such as the MCP Inspector, list its origin, e.g. MCP_ALLOWED_ORIGINS=http://localhost:6274. The environment key is only lent to requests without an Origin or from an origin listed by name (a * entry admits browsers that send their own key, never the environment key). With any other HOST the environment key is ignored, and you should put the server behind HTTPS. Set MCP_ALLOWED_HOSTS (comma-separated host names) to keep DNS-rebinding protection when binding to 0.0.0.0. GET /health returns the server version.

Hosted server with OAuth (Claude.ai and other remote clients)

The hosted server at https://api.sutramx.com/mcp also accepts OAuth 2.1, so clients that cannot store an API key (for example a Claude.ai custom connector) only need the URL. On the first request without credentials the server answers 401 with WWW-Authenticate: Bearer resource_metadata="https://api.sutramx.com/.well-known/oauth-protected-resource/mcp"; the client registers itself (dynamic client registration), sends you to SutramX to approve, and gets an access token (PKCE S256, resource indicator https://api.sutramx.com/mcp).

On the consent page you pick the workspace and the permissions: monitors:read, incidents:read, status_pages:read (on by default) and monitors:write, incidents:write, status_pages:write (off unless you tick them; workspace viewers can only grant read). A token without a write scope gets only the read tools. Destructive tools (deletes, publishing, slug changes, replacing a status page's monitors) stay off on the hosted server; only the server operator can enable them (SUTRAMX_ALLOW_DESTRUCTIVE). OAuth tokens can never manage API keys, team members, billing, SSO or account settings. Access tokens last one hour and are refreshed automatically; revoke an app any time in SutramX → Settings → Authorized apps.

Self-hosting the HTTP server with OAuth: set MCP_RESOURCE_URL to the public URL of your /mcp endpoint and MCP_AUTHORIZATION_SERVER to your SutramX API, and serve /.well-known/oauth-protected-resource* from this server. Set OAUTH_RESOURCE_PROXY_SECRET (at least 16 characters, the value your API expects) so OAuth tokens reach the API with their resource proof. With NODE_ENV=production (the Docker image's default) the HTTP server refuses to start when that secret is missing or shorter than 16 characters, instead of silently sending tokens without it. A server that should accept API keys only sets MCP_OAUTH=off: no protected-resource metadata is served and OAuth access tokens are refused. stdio mode is not affected.

Configuration

| SUTRAMX_API_URL | https://api.sutramx.com | API base URL (self-hosted or staging); set by the operator only, never taken from a request or tool argu