Skip to main content
Glama
README.md
# monity-mcp

MCP (Model Context Protocol) server for [monity.ai](https://monity.ai) — query your website monitors, change-detection results, and extracted data directly from Claude Code, Claude Desktop, Cursor, or any MCP client.

Ask things like:

- *"What's the current price on my competitor-pricing monitor?"*
- *"Summarise everything that changed across my monitors this week."*
- *"Monitor this page, but only alert me if the Pro plan price changes."*
- *"Set up a monitor that dismisses the cookie banner and clicks 'show more' before checking."*
- *"Show me the page as it looks right now."* — the assistant sees the actual screenshot
- *"Show me the check history for the stock-availability task."*

## Two ways to connect

- **Hosted, no install, no key:** add `https://api.monity.ai/plugins/mcp` as a remote MCP server (in Claude: Customize → Connectors → Add custom connector). You sign in to monity.ai and choose which workspaces the assistant may see. It carries the core monitoring tools.
- **This package (local, with an API key):** every tool below, including Monity Network and the repair tools, and an API origin you can point at a staging server. The rest of this page is about this package.

You need a monity.ai account (the free plan works: [monity.ai](https://monity.ai)) and Node.js 18 or later.

## Setup

### 1. Get an API key

In the monity.ai app, open **Integrations → MCP clients → Create a key** (the same keys are under Integrations → Developers → REST API). Give the key the **write** scope if the assistant should create or change monitors.

The raw key (`mk_live_…`) is shown once, so store it safely.

### 2. Add the server to your client

**Claude Code:**

```bash
claude mcp add monity --env MONITY_API_KEY=mk_live_... -- npx -y monity-mcp
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "monity": {
      "command": "npx",
      "args": ["-y", "monity-mcp"],
      "env": { "MONITY_API_KEY": "mk_live_..." }
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "monity": {
      "command": "npx",
      "args": ["-y", "monity-mcp"],
      "env": { "MONITY_API_KEY": "mk_live_..." }
    }
  }
}
```

## Tools

Read tools work with any API key; write tools need a key created with the
**write** scope (dashboard → Account → Integrations).

| Tool | What it does |
|---|---|
| `list_monitors` | List monitors: name, URL, type, active, labels, workspace, last/next check. Start here to find a monitor's `uuid`. |
| `get_account` | Who is connected and what the plan allows: monitors used and slots left per workspace, credits left, the credit refresh date and the allowed check frequencies. |
| `list_workspaces` | The account's workspaces. Business accounts hold several; use this to filter `list_monitors` or to target `create_monitor`. |
| `get_monitor` | One monitor's configuration, including its pre-check actions. |
| `get_latest_result` | Most recent completed check: status, extracted output (current + previous value), AI summary, structured items, artifact URLs. |
| `get_recent_changes` | **Account-wide** feed of checks, each already carrying its monitor, the AI summary of the change and the extracted output. One call answers "what changed this week?" — no looping over monitors. |
| `get_check_history` | One monitor's past checks, with status and date filters. |
| `get_check` | Full detail of one specific check. |
| `view_check_screenshot` | **Returns the screenshot image itself**, so the client can look at the page — current, previous, or the diff composite with changes highlighted. |
| `create_monitor` | Create a monitor with the full intent in one call: URL, frequency, a natural-language alert condition (`notifyWhen: "price drops below $500"`) **or** deterministic `notifyConditions` with `outputExtractor`/`jsonPath` extraction, keywords for TEXT monitors, pre-check `actions`, a target `workspaceId`, alert routing, and `skills` with their alert rules (`skillAlerts`). |
| `update_monitor` | Change name, frequency, active state, alert conditions, extraction, actions, alert routing or skills. Omitted fields stay unchanged; `null` clears. |
| `list_skills` | The skills a monitor can carry (speed and Core Web Vitals, SEO, accessibility, broken links, security signals, page problems, third-party scripts, cookies and trackers, SSL certificate and domain expiry), each with its alert rules, units and defaults, and whether your plan includes it. |
| `pause_monitor` / `resume_monitor` | Toggle scheduled checks (resume is plan-gated). |
| `run_monitor` | Check an active monitor now instead of waiting for its schedule. |
| `delete_monitor` | Permanently delete a monitor with its checks (confirm with the user first). |
| `hide_change` / `unhide_change` | Hide one change from your history and recent changes, or show it again; nothing is deleted. `includeHidden` on the history and feed tools shows hidden ones. |

### Skills and alert rules

A monitor can carry skills: extra checks run on every check, each alerting on
its own rules rather than on any change. *"Monitor our pricing page and alert
me if it gets slow"* is one call:

```
create_monitor(websiteUrl: "https://example.com/pricing", skills: ["perf"], skillAlerts: { perf: { lcp: 3 } })
```

A number sets a rule's threshold (seconds for timings, MB for page weight,
days for expiry, 0–100 for scores); `true`/`false` turns a rule on or off.
`list_skills` lists the rule ids. Needs API version 2026-10 or later
(`GET /api/v1/skills`); older servers answer with a tool error.

### Reporting

`get_recent_changes` is the tool for any "what happened?" question. It returns
the account's checks newest-first, each row already carrying its monitor's name
and URL, the AI summary of what changed, and the extracted value — so a weekly
digest is one call, not one call per monitor plus one per check.

```
get_recent_changes(from: "2026-08-27", alertedOnly: true)
```

It defaults to alerts only. Pass `alertedOnly: false` to get every completed
check as a data feed, and `label` or `monitorUuid` to narrow it.

### Monity Network

Monity Network is the public side of monity.ai: people publish trackers on
pages they track (prices, restocks, pricing pages, status pages, policies)
and every change they catch comes with evidence. A tracker has one source (a
page Monity checks) or several. Any API key can read it.

| Tool | What it does |
|---|---|
| `ask_network` | A question in plain words, answered only from Network's change records with numbered citations; says so when there is no coverage. |
| `summarize_network_changes` | A few sentences on what changed on a tracker or a site, each citing its changes. |
| `search_network` | Search trackers and the people who run them, by words or a page address. |
| `get_tracker` | Any tracker by its slug or id: with one source (the page it tracks, whether it is live, who runs it) or several (each source with its health). |
| `get_network_watch` | A tracker with one source: the page it tracks, whether it is live, who runs it, and its latest changes. |
| `get_network_changes` | What changed, newest first, on a whole site or on one tracker, optionally `since` a date. |
| `get_network_update` | One change with its evidence (before/after screenshots, visual diff). |
| `list_starter_packs` | Trackers picked to start from. |
| `get_network_product` | One product at every store that tracks it ("available at 2 of 3 stores", the cheapest), by a change record's `thing.id` or the slug of any of its trackers. |
| `query_network_records` | Structured change records for a page (any form of its address, or its page id), a site or a tracker, filterable by date, kind and origin. |
| `find_existing_network_watch` | Before `create_monitor`: a public tracker that already checks the page the same way, to follow instead. |
| `follow_tracker` / `unfollow_tracker` | Follow or unfollow any tracker by its slug or id as you (write scope); Monity works out whether it has one source or several. Optionally a personal condition on a tracker with one source. |
| `follow_network` / `unfollow_network` / `list_network_follows` | Follow a tracker or a person as you (write scope), optionally with a personal condition on a tracker with one source; list what you follow. |
| `set_network_condition` | Which of a one-source tracker's changes alert you: below/above an amount, goes down/up, mentions some words, back in stock, or plain words. |

```
get_network_changes(domain: "nike.com", since: "2026-09-22")
```

Every change carries a `url` to its public page, so an agent can cite it.

To be told instead of asking, subscribe a webhook (write-scope key):

| Tool | What it does |
|---|---|
| `subscribe_network_webhook` | POST every new change on a tracker, a person's trackers or a whole site to an https URL, signed. |
| `list_network_subscriptions` | Your subscriptions, and whether each is active or stopped (with the reason). |
| `test_network_webhook` | Send the latest matching change now, marked `"test": true`. |
| `unsubscribe_network_webhook` | Remove one. |

Deliveries are `{"type":"network.change","id":…,"change":{…}}`. Verify
`X-Monity-Signature` = `sha256=` + hex HMAC-SHA256 of
`<X-Monity-Timestamp>.<raw body>` with your account webhook secret (returned
when you subscribe; also under Account → Integrations). Failed deliveries are
retried with backoff; answering `410 Gone` unsubscribes.

To publish one of your monitors as a public tracker, use a key with the
**network:publish** scope (Account → Integrations → "Allow publishing to
Monity Network"). Publishing is two steps, like in the app:
`preview_network_watch` shows exactly what becomes public and returns a
`revisionId`; `publish_network_watch` publishes that revision. At most 5 a day
per key, and you are told in your Network notifications each time.

"Track this page and let people follow it" is `create_public_tracker` (a key
with **write** and **network:publish**): it creates the monitor and returns the
same preview and `revisionId`, with nothing public yet; `publish_tracker`
publishes that revision, on its own or onto one of your trackers.
`request_verification` asks Monity to open the page an update from one of
your connected agents names and mark it "Verified by Monity" (one check on
your plan).

### Seeing the page

`view_check_screenshot` returns real image bytes as an MCP image block, so an
assistant that supports vision can *look* at the monitored page rather than
reason about a diff percentage:

```
view_check_screenshot(uuid: "…", checkId: "latest")            # how it looks now
view_check_screenshot(uuid: "…", checkId: "…", view: "diff")   # what changed
view_check_screenshot(uuid: "…", checkId: "…", view: "previous")
```

`checkId` accepts `"latest"`, so *"show me that page"* needs no prior lookup.

This is also the fastest way to get selectors right: ask the assistant to look
at the page, then have it set an `outputExtractor` or a `CLICK` action based on
what it actually sees.

Images are scaled server-side before being sent (default: fit inside
1200x3000, PNG, falling back to JPEG when the PNG would be large). Full-page
captures can be 20,000px tall, and MCP carries images inline as base64 — so an
unscaled one would flood the context. The result says whether it was
downscaled, so soft small text is not mistaken for the page's own rendering.

Not every check has every view: a first check has no `previous`, and a text
monitor may have no `diff`. The error names the views that do exist.

### Pre-check actions

Some pages only show what you care about after an interaction. `create_monitor`
and `update_monitor` take an ordered `actions` list that runs before every
comparison:

```json
[
  { "type": "CLICK", "selector": "#accept-cookies" },
  { "type": "WAIT",  "value": 1500 },
  { "type": "CLICK", "selector": ".load-more" }
]
```

Supported: `CLICK`, `TYPE`, `SELECT`, `MOUSEOVER`, `SCROLL`, `WAIT`, `REFRESH`,
`BLOCK` (remove an element before comparing). Up to 20 steps.

`selector` is a **Playwright selector**, used verbatim: CSS by default, XPath
when the string starts with `/`, and engine prefixes like `text=Show more`.
For controls identified by their label rather than a stable id, `text=` and
`button:has-text("Show more")` survive redeploys that hashed class names do
not.

Script and JS/CSS injection steps are **not** available here — they execute
caller-supplied code in the browser that renders the page, so they stay in the
dashboard where a human authors them. `update_monitor` replaces the whole list,
so read the monitor first if you want to keep existing steps.

Typed credentials configured in the dashboard are never returned: those steps
come back with `value: null` and `valueIsSecret: true`.

### Templates

When the server offers Monity Network templates (monitor setups people share), three more tools appear: `list_network_templates`, `get_network_template` and `create_monitor_from_template` (creates a monitor on your own page with a template's setup; write scope). Servers without templates don't list them.

### Repair tools

For agents that repair your monitors when a page changes and a check starts failing. They work on your own tasks only, and the write operations need a write-scope key.

| Tool | What it does |
|---|---|
| `list_supervisor_queue` | Tasks that need repair. |
| `get_supervisor_task` | A task's repair policy, its saved actions and the evidence of the failure. Page content is untrusted data. |
| `configure_supervisor_task` | Turn on supervision for a task (opt-in; it starts no paid API calls). |
| `report_supervisor_task` | Queue a problem you noticed, such as a page that did not load fully. |
| `claim_supervisor_task` | Claim a repair for 15 minutes; returns a private lease token. |
| `test_supervisor_task` / `preview_supervisor_task` | Try a candidate fix in a browser preview (no AI model), then read the result. |
| `apply_supervisor_task` | Activate a fix whose preview passed; the next full check confirms recovery. |
| `release_supervisor_task` / `dismiss_supervisor_task` | Give the claim back, or close an incident a person decided needs no repair. |
| `device_start_supervisor_task` / `device_status_supervisor_task` / `device_command_supervisor_task` | An isolated recovery browser for one incident, when the task's policy allows it (for example to sign in again); commands click by screenshot coordinates. |
| `device_screenshot_supervisor_task` | The recovery browser's current screenshot. |

### Business accounts

A monitor lives in one workspace. By default `create_monitor` puts it in the
key owner's **personal** workspace, which the rest of the team cannot see — on
a business account, call `list_workspaces` and pass `workspaceId` so the
monitor lands somewhere shared.

## Configuration

| Env var | Required | Default | Description |
|---|---|---|---|
| `MONITY_API_KEY` | ✅ | — | Account API key (`mk_live_…`) |
| `MONITY_API_URL` | — | `https://api.monity.ai` | API origin override (staging/self-hosted) |
| `MONITY_APP_URL` | — | `https://app.monity.ai` | App origin used for the Network page links in results |

## Development

```bash
npm install
npm test        # builds + runs unit tests
npm run build   # tsc → dist/
node dist/index.js   # run locally (stdio)
```

## Rate limits

The public API allows 120 requests/minute per key; the server surfaces 429s with a clear retry message.

Prefer `get_recent_changes` over looping `get_check_history` across monitors —
it is one request instead of one per monitor, which is the difference between
comfortably inside the limit and repeatedly hitting it on a large account.

`view_check_screenshot` transfers an image per call, so pull screenshots for
the checks that matter rather than for a whole listing.

## Hosted alternative

Two hosted endpoints need no local install. `https://api.monity.ai/plugins/mcp`
signs you in with OAuth (no key) and carries the core monitoring tools; it is
the one the ChatGPT app and the Claude connector use. `https://api.monity.ai/mcp`
takes an API key and has the same tools as this package:

```bash
claude mcp add monity https://api.monity.ai/mcp \
  --header "Authorization: Bearer mk_live_..."
```

Use this package when you want the server running locally, or need
`MONITY_API_URL` pointed at a staging environment.

The hosted endpoint also speaks MCP protocol `2026-07-28` and offers **MCP
Events** to keys with the `read` scope: an MCP client connected with an API key
subscribes to `tracker.change` (filtered by a tracker, a site, or both) with its own callback
URL and `whsec_` secret, answers a signed verification challenge, and then gets
each new public change that meets the tracker's "tells you when" rule (every
change when it has none, or with `changes: "all"`) POSTed to it, signed with Standard Webhooks
(`webhook-id`, `webhook-timestamp`, `webhook-signature`, `X-MCP-Subscription-Id`).
This package runs over stdio and has no callback, so events need the hosted
endpoint. The ChatGPT app (OAuth) does not offer events yet.

TDQS

B3.1/5.0

Scored across 58 tools

Disambiguation2/5

Several tools have overlapping or unclear boundaries, especially in the Network surface: follow_network vs follow_tracker, publish_network_watch vs publish_tracker, get_network_changes vs query_network_records, and ask_network vs summarize_network_changes. The supervisor recovery tools also form a dense cluster where tools like test_supervisor_task, preview_supervisor_task, and the device_* tools require close reading to select correctly.

Naming Consistency4/5

Most tools follow a snake_case verb_noun pattern (list_monitors, create_monitor, get_check_history). There are minor deviations in object/suffix naming, such as device_screenshot_supervisor_task, list_supervisor_queue, and the mixed network/tracker/publish naming, but the convention is mostly predictable.

Tool Count2/5

58 tools is very heavy for a single server, even one spanning monitoring, Network publishing, supervisor repair, and device recovery. Many tools are granular and some could be consolidated, increasing cognitive load and misselection risk.

Completeness3/5

Core monitor lifecycle and most Network/supervisor workflows are covered, but there are notable gaps such as no tool to withdraw or unpublish a public tracker, no list of the user's own published trackers, and no update operation for webhook subscriptions. These create dead ends or force workarounds in the stated lifecycle.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues