---
title: MCP server
description: Connect Claude, Cursor and other MCP clients to Pulseguard. Check websites, read monitor status for free, and add monitors with MPP payments from inside the agent.
---

# MCP server

UpHeron runs a [Model Context Protocol](https://modelcontextprotocol.io) server, so an AI agent can check websites, read your monitors and add new ones as tools, without writing API calls.

- **Endpoint:** `https://upheron.com/mcp` (Streamable HTTP)
- **Authentication:** your API token in the `X-API-Key` header, or `Authorization: Bearer <token>`. Create one in **Settings → API tokens**; a `read` token is enough for status, `write` lets the agent create monitors and pay. An agent can also get an access token itself with [auth.md](/docs/auth-md); it works here the same way.
- **No token?** `check_website` works without one, and `create_monitor` works by paying alone (see [below](#without-a-token)).

## Connect

### Claude Code

```bash
claude mcp add --transport http upheron https://upheron.com/mcp \
  --header "X-API-Key: $UPTIME_MONITOR_API_KEY"
```

### Claude Desktop, Cursor, VS Code and other clients

Most clients take a JSON entry like this (the file and key names vary by client):

```json
{
  "mcpServers": {
    "upheron": {
      "type": "http",
      "url": "https://upheron.com/mcp",
      "headers": { "X-API-Key": "pgk_…" }
    }
  }
}
```

Clients that only support local (stdio) servers can bridge with `npx mcp-remote https://upheron.com/mcp --header "X-API-Key: pgk_…"`.

## Tools

| Tool | What it does | Cost |
|---|---|---|
| `check_website` | Checks whether a public website responds right now | Free, no token needed |
| `get_account` | Plan, free monitor slots, credit and prices | Free |
| `list_locations` | Location codes for monitors | Free |
| `list_monitors` | Every monitor and its current status | Free |
| `get_monitor` | Uptime (24 h, 7 d, 30 d), latest results, incidents | Free |
| `get_monitor_results` | Up to 500 recent results | Free |
| `get_uptime_history` | Daily uptime for any range, back to the first check | Free |
| `list_incidents` | Outages, newest first | Free |
| `quote_monitor` | What a monitor would cost, without creating it | Free |
| `create_monitor` | Creates a monitor | Free in a plan slot; otherwise paid |
| `update_monitor` | Changes a monitor | Paid only for extra locations on a paid monitor |
| `pause_monitor`, `resume_monitor`, `delete_monitor` | Manage monitors | Free |
| `renew_monitor` | Adds 30 days to a monthly paid monitor | Paid from credit |
| `top_up_credit` | Buys prepaid credit | Paid |
| `list_payments` | Payments and their VAT | Free |
| `add_notification_contact`, `list_notification_contacts` | Email or webhook alerts | Free |
| `get_vulnerabilities` | Vulnerabilities and unsupported releases found in a website monitor's software, with fixes (Pro plans) | Free |
| `import_software` | Tells a monitor what its website runs: a lockfile, Dockerfile or a "name version" list | Free |
| `add_software`, `remove_software` | Adds or removes one piece of software | Free |
| `mark_vulnerability_fixed` | Records that a finding's software was upgraded, by default to the first version that fixes it | Free |
| `scan_website_software` | Scans the website for its software and checks it now | Free |

An agent that can see a server is the best source for what it runs: ask it to read `/etc/os-release`, `nginx -v`, `php -v` or the project's lockfile and send the result with `import_software`, after turning on `vulnerability_alerts` with `update_monitor`. [Software lists](/docs/software) describes the list format and the files it reads.

Tools carry MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`), so clients can ask before running anything that changes or costs something. The documentation is also available as MCP resources (`upheron://docs/…`).

## Paying from MCP

Paid tools follow the [MPP transport binding for MCP](https://paymentauth.org/draft-payment-transport-mcp-00):

1. When credit does not cover a paid tool, the call fails with JSON-RPC error **-32042** (payment required). Its `data.challenges` holds the MPP challenge: what to pay, how, and how much.
2. The agent's MPP client pays it and repeats the tool call with the credential in `params._meta["org.paymentauth/credential"]`. Your API key stays in the connection header.
3. The result carries the receipt in `_meta["org.paymentauth/receipt"]`.

A card pays at least $0.50 (Stripe's minimum), and everything above the price stays as credit: at the default prices $0.50 covers 50 location-months or 5 lifetime locations, used automatically by later calls. See [Payments](/docs/payments) for prices, credit and VAT.

Clients without MPP support can still use every free tool, and create monitors while the plan has free slots or the workspace has credit. Top up credit from the [HTTP API](/docs/payments#prepaid-credit) or with an MPP-capable tool such as Stripe's Link CLI.

## Without a token

Without an API key, `create_monitor` is always paid. After payment it creates a pay-as-you-go workspace that owns the monitor and returns its `api_key` once. Configure that key as the server's `X-API-Key` header to manage the monitor, renew it and add more.

## Good instructions for your agent

```text
Use the upheron MCP tools to monitor websites.
- Reading is free. Before create_monitor, call quote_monitor; if amount_due_cents > 0, tell me the price and ask first unless I approved a budget.
- Always pass idempotency_key to create_monitor.
- Monthly is the default; use billing_period "lifetime" only when I ask for it.
```