MCP server

The Monitorable MCP server lets an AI assistant work with your monitoring through the Model Context Protocol. Ask Claude Code which servers are offline, have it read last night’s CPU and memory, acknowledge an incident, mute a server’s alerts for a maintenance window, or add and remove servers.

You connect in one of two ways. Sign in with your Monitorable account from Claude or ChatGPT: you pick Monitorable from Claude’s connector directory or add the server’s URL, approve access once, and the assistant acts as you, with your role. Or give the assistant an organization API key, the same kind the REST API uses, which suits automation and clients without sign-in support; what it can see and change is then decided by that key’s scopes. Every plan includes it with the API.


Endpoint	`https://mcp.monitorable.io/mcp`
Transport	Streamable HTTP, stateless, plain JSON responses
Authentication	Sign in with your Monitorable account (OAuth 2.1), or `Authorization: Bearer <your-api-key>` — an organization API key
Tools	19 — see the tool reference

Connect by signing in

Signing in needs no key. Add Monitorable to the assistant, from Claude’s connector directory or by the server’s URL, sign in to Monitorable when it asks, choose an organization and approve. The assistant then acts as you, in that organization, and you can disconnect it at any time under Account → Connected apps.

Claude (web, Desktop and mobile)

Monitorable is listed in Claude’s connector directory:

Signed in to Claude, open Monitorable in Claude’s connector directory and choose Connect.
Sign in with your Monitorable account, pick the organization, and choose Allow.

The connector then also appears in Claude Desktop and the mobile apps (Settings → Connectors), signed in the same way.

To add it by URL instead, open Settings → Customize → Connectors in Claude on the web or Desktop, choose Add custom connector, enter a Name (for example Monitorable) and the MCP server URL https://mcp.monitorable.io/mcp, finish the dialog, then connect and sign in as above. Monitorable needs no other settings.

Removing the connector in Claude does not end its access on Monitorable’s side. To end it, also choose Disconnect under Account → Connected apps; otherwise the connection lapses after 30 days without use.

claude mcp add --transport http monitorable https://mcp.monitorable.io/mcp

Then run /mcp inside Claude Code and choose Monitorable to sign in. Your browser opens the Monitorable sign-in. For scripts and CI keep using the API-key form below, which needs no browser.

If Claude Code runs on another machine (over SSH or in a remote VS Code window), the last step of the sign-in, a http://localhost:…/callback address, points at that machine, and the browser on your computer shows a connection error. Sign in from a terminal on that machine instead:

claude mcp login monitorable --no-browser

Open the address it prints in your browser, sign in and approve, then copy the full address from the browser’s address bar (the page that failed to load) and paste it at the prompt. Over SSH, connect with ssh -t so the prompt can read it.

ChatGPT

Open ChatGPT’s plugins page, choose +, then Add custom MCP server.
Enter a Name, for example Monitorable. Under Connection keep Server URL and enter https://mcp.monitorable.io/mcp. Leave Authentication on OAuth: ChatGPT discovers the rest, so the advanced OAuth settings need no changes.
Tick I understand and want to continue, then choose Create as a plugin.
Choose Connect, sign in with your Monitorable account, pick the organization, and choose Allow.

Removing the plugin in ChatGPT also ends its access: it disappears from Account → Connected apps. Until Monitorable is listed in ChatGPT’s plugin directory, add it this way.

What you approve

The first time a client connects, it sends you to Monitorable to sign in with your normal dashboard account. The approval page shows:

The app. It is named by the host of its client ID URL, for example claude.ai, and shows where Monitorable will send you back to. A warning appears when the app runs on your own computer, as Claude Code does.
The organization. Choose one. A sign-in covers one organization; connect again to give the assistant another.
The access it asks for. Everything the assistant can do: read servers, metrics, incidents and alert settings, and your account’s plan and usage (servers:read, metrics:read, alerts:read, account:read), and change servers and alerts (servers:write, alerts:write).

Organization members only ever get read access through sign-in: the write scopes are shown disabled with “Not available for your role in <organization>”. Owners and admins approve them with the rest. For an assistant that can only read, connect from an organization where you are a member, or use an API key with read scopes only.

	Sign in	API key
Who acts	You, in the organization you chose	The key, named in the audit log
Role	Your role in that organization	The role the key was created with
Scopes	What your role allows, approved at sign-in	Fixed when the key is created
Revoke	Account → Connected apps, Disconnect	Team → API keys
Best for	Assistants you chat with	Automation, CI, Cursor (Monitorable does not offer sign-in for it yet)

Connect with an API key

Get a key

Organization owners and admins create keys in the dashboard under Team → API keys; API keys and scopes explains presets, roles and expiry. For the MCP server:

Read-only is the right preset for an assistant that should look but not touch: it lists servers, reads metrics and incidents, and can search these docs.
Automation is for an agent that may change things: it can create and remove servers and acknowledge or mute alerts. It holds no metrics:read or alerts:read, so add those scopes to the key if the agent also needs to read metrics and incidents.
Full gives an agent everything.

A key is shown once. Keep it in an environment variable or your client’s secret store, never in a repository, and revoke it from Team → API keys if it was exposed.

Add the key to your client

Use a key for automation and for clients that cannot sign in yet, such as Cursor. Replace <your-api-key> with your key. Every client below sends it as the Authorization: Bearer header.

Claude Code

claude mcp add --transport http monitorable https://mcp.monitorable.io/mcp \
  --header "Authorization: Bearer <your-api-key>"

This stores the server for the current project. Add --scope user to make it available in every project. Run /mcp inside Claude Code to check the connection: a failed key shows up there as an HTTP 401.

To share the connection with your team without sharing the key, commit a .mcp.json that reads the key from an environment variable each person sets:

{
  "mcpServers": {
    "monitorable": {
      "type": "http",
      "url": "https://mcp.monitorable.io/mcp",
      "headers": {
        "Authorization": "Bearer ${MONITORABLE_API_KEY}"
      }
    }
  }
}

Cursor

Cursor does not support signing in to Monitorable yet, so it uses an API key. Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Cursor reads the key from an environment variable, so set MONITORABLE_API_KEY in your shell profile and keep the literal key out of the file:

{
  "mcpServers": {
    "monitorable": {
      "url": "https://mcp.monitorable.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MONITORABLE_API_KEY}"
      }
    }
  }
}

VS Code

Create .vscode/mcp.json in your workspace (or the MCP configuration of your user profile). VS Code asks for the key the first time the server starts and stores it for you, so it never sits in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "monitorable-key",
      "description": "Monitorable API key",
      "password": true
    }
  ],
  "servers": {
    "monitorable": {
      "type": "http",
      "url": "https://mcp.monitorable.io/mcp",
      "headers": {
        "Authorization": "Bearer ${input:monitorable-key}"
      }
    }
  }
}

Codex

Add this to ~/.codex/config.toml, the Codex configuration shared by the CLI and the IDE extension, and export MONITORABLE_API_KEY in the shell that starts Codex:

[mcp_servers.monitorable]
url = "https://mcp.monitorable.io/mcp"
bearer_token_env_var = "MONITORABLE_API_KEY"

Clients that only run local (stdio) servers

mcp-remote is a small proxy that lets a client that starts local commands talk to a remote server. It needs Node 18 or newer. Claude Desktop can sign in directly, so you only need this for a client without sign-in support. Claude Desktop reads it from its claude_desktop_config.json (on macOS ~/Library/Application Support/Claude/claude_desktop_config.json, on Windows %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "monitorable": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.monitorable.io/mcp",
        "--transport",
        "http-only",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your-api-key>"
      }
    }
  }
}

The header is written without a space and its value lives in env because some clients do not escape spaces inside args.

Check the connection

Ask the assistant “Which Monitorable organization am I connected to?” It calls whoami, which returns who is acting, the role, scopes and expiry, the organization and the plan. The auth field says how the connection signed in: oauth for a sign-in, api_key for a key. The actor field reads <your email> via <app host> for a sign-in and is the key’s name for a key. If a tool you expect is missing, a key lacks its scope or the connection’s role is member; see the next section.

What the assistant can do

Each tool needs the scope shown. What a connection sees depends on how it signed in:

An API key sees a tool only when it holds every scope the tool needs, and tools that change data only when the key’s role is admin.
A sign-in sees every tool its role allows: organization members see the read tools, owners and admins see all of them. A missing scope never hides a tool. If a sign-in lacks a tool’s scope, some clients ask you to approve it on the spot; otherwise disconnect under Account → Connected apps and connect again.

API keys and scopes explains the scopes; the tool reference lists every parameter.

Scope	Tools
`servers:read`	`list_servers`, `get_server`, `list_server_services`, `list_server_containers`, `list_server_disks`, `list_server_ports`
`servers:write`	`create_server`, `remove_server` (also needs `servers:read`)
`metrics:read`	`get_server_current`, `get_server_metrics`
`alerts:read`	`list_incidents`, `get_incident`, `list_alert_templates`, `list_notification_channels`
`alerts:write`	`acknowledge_incident`, `mute_server_alerts`, `unmute_server_alerts`
`account:read`	no tool of its own: it adds the plan’s limits and the organization’s usage to the answer of `whoami`
`servers:enroll`	none: enrollment keys are for host enrollment, not for assistants
any key	`whoami`, `search_docs` (answers how-to questions from these docs)

The server also offers two prompts that clients with prompt support list by name. Both only read:

triage_fleet walks the open incidents and the offline and stale servers, and proposes one next step per server.
explain_server takes a server_id and describes that server’s health now, its last 24 hours of CPU, memory and disk, its incidents and its failed services.

Safety

Reading and writing are separate tools. A read-only key never sees a write tool, and calling one by name is refused naming the missing scope. A sign-in gets only what your role allows. Clients also get each tool’s hints (read-only, changes data, destructive), so many ask you before running a write. remove_server and mute_server_alerts (it silences every alert of the server) are marked destructive.
remove_server needs confirm. It deletes the server and its whole history, and it only proceeds when confirm equals the server’s exact name, character for character. Otherwise nothing is deleted and the answer is: invalid_argument: confirm must equal the server's exact name "<name>" (server_id <id>); if that is not the server you meant, the server_id is wrong — check it with list_servers before retrying.
The agent key is shown once. create_server returns the new server’s agent key and install command in its answer, and nowhere else. Treat the conversation as holding a secret until the agent is installed.
Channel secrets never appear. list_notification_channels reports each channel’s name, type, whether it is enabled and its latest delivery outcome, never the webhook URL, token or address behind it.
Same limits as the API. A key’s calls count against its rate limit and a tool that makes two API calls counts twice: get_server and remove_server always do, and whoami does when the key has account:read. Each sign-in connection has its own limit too.
Every write is audited. Creating or removing a server, acknowledging an incident and muting alerts appear in the API audit log under Team → API keys, with the key that made them, or for a sign-in with the app and the person, shown as claude.ai (you@example.com).
Sign-in is short-lived and revocable. An access token lasts one hour, and the connection stays alive for 30 days of use: each use renews it, and 30 days without one ends it. Disconnect under Account → Connected apps takes effect at once: the assistant’s next tool call fails and it asks you to sign in again. The list shows each connection’s app, the organization, its access, when it connected and when it was last used. Removing you from the organization, or the organization losing API access, also ends the connection.
The assistant reads your data. Server names, hostnames and container names go into the model’s context; treat them as text a person typed.

To give one connection fewer tools, send the header X-Monitorable-Tools-Only (a comma list of the tool names to keep) or X-Monitorable-Tools-Except (a list to drop) with the others. A tool removed that way answers as an unknown tool.

Limits

list_servers and list_incidents return 25 rows by default and at most 100 (limit); a next_cursor in the answer, empty when there is no more, continues the list.
list_server_services, list_server_containers, list_server_disks and list_server_ports do not page: each returns at most 100 rows, with total (how many the server reported) and shown (how many are in the answer).
get_server_metrics returns one shared list of at most 120 timestamps, and each series carries a values list aligned to it, with null where that series has no point. It asks for cpu, memory and disk unless you name other series; ask for network, connections or ports explicitly. disk and ports return one series per device or port, so pass series to narrow them. Longer windows are thinned to fit, and the summary (current, average, max, p95) is taken from all points before thinning.
A metrics window older than your plan’s history is refused with range_not_in_plan; see pricing.
search_docs returns at most 10 pages with a short excerpt each.
Clients may cache the tool list for five minutes, so a new scope shows up in the assistant after that, or after you reconnect.

When a call fails

Failed calls that reach a tool return a tool error of the form <code>: <detail>, with the same codes as the REST errors; a rate_limited error says how many seconds to wait. A key or sign-in that is missing, revoked, expired or disconnected is refused with HTTP 401 before any tool runs, which clients show as a failed connection; for a sign-in the response is invalid_token and the client asks you to sign in again. A sign-in that lacks the access a tool needs is refused with HTTP 403 insufficient_scope naming the scope; clients that support it ask you to approve it, otherwise connect again. A tool a key may not use answers insufficient scope or insufficient role, naming what is missing.