# MCP server

Hole Monitor serves a [Model Context Protocol](https://modelcontextprotocol.io/) server at:

```text
https://api.holemonitor.live/mcp
```

Transport is Streamable HTTP, stateless. A `read` key is offered the read tools only.

## Sign-in

Add the server URL to your client and connect. The server follows the [MCP authorization spec](https://modelcontextprotocol.io/specification/latest/basic/authorization): your client registers itself, opens a browser at Hole Monitor, and you approve it on the same [Connect an agent](/activate/) page coding agents use, choosing read or write. The client receives its own API key, which is listed under API keys in the dashboard. Connecting the same client again replaces its previous key.

Clients without OAuth can send a key from the dashboard as a bearer token: `Authorization: Bearer hm_...`.

Each tool wraps one REST route and returns that route's response body, so it adds nothing the [API](/docs/api/) lacks.

| Tool | Route | Scope |
| --- | --- | --- |
| `get_account` | `GET /v1/account` | read |
| `list_endpoints` | `GET /v1/endpoints` | read |
| `get_endpoint` | `GET /v1/endpoints/{id}` | read |
| `list_filters` | `GET /v1/endpoints/{id}/filters` | read |
| `preview_filter` | `POST /v1/filters/preview` | read |
| `list_deliveries` | `GET /v1/deliveries` | read |
| `get_advisory` | `GET /v1/advisories/{id}` | read |
| `search_advisories` | `GET /v1/advisories`, Starter plan and above | read |
| `create_endpoint` | `POST /v1/endpoints` | write |
| `update_endpoint` | `PATCH /v1/endpoints/{id}` | write |
| `verify_endpoint` | `POST /v1/endpoints/{id}/verify` | write |
| `send_test` | `POST /v1/endpoints/{id}/test` | write |
| `create_filter` | `POST /v1/endpoints/{id}/filters` | write |
| `replace_filters` | `PUT /v1/endpoints/{id}/filters` | write |
| `update_filter` | `PATCH /v1/filters/{id}` | write |
| `delete_filter` | `DELETE /v1/filters/{id}` | write |
| `redeliver` | `POST /v1/deliveries/{id}/redeliver` | write |

Not exposed: API keys, billing, account and endpoint deletion, secret rotation and administration.

`create_endpoint` returns the endpoint's signing secret once, into the agent's context. The agent has to put it in the receiver's secret store. A secret that passes through a model's transcript may be logged by the model's host; rotate it from the dashboard if that matters to you.

`search_advisories` returns structured content only.

`get_advisory` returns structured content by default. With `content: "full"`, the third-party prose (`summary`, `details`) arrives as a separate content item marked as untrusted text.

The MCP server does not push advisories. Webhooks are the only notification channel.

## Client configuration

Claude Code:

```bash
claude mcp add --transport http hole-monitor https://api.holemonitor.live/mcp
```

Then run `/mcp` in Claude Code and choose to authenticate.

Other clients:

```json
{
  "mcpServers": {
    "hole-monitor": { "url": "https://api.holemonitor.live/mcp" }
  }
}
```

With a dashboard key instead of sign-in, add `"headers": { "Authorization": "Bearer hm_..." }`.

Discovery documents: [protected resource metadata](https://api.holemonitor.live/.well-known/oauth-protected-resource/mcp) (RFC 9728) and [authorization server metadata](https://api.holemonitor.live/.well-known/oauth-authorization-server) (RFC 8414). Clients register with RFC 7591 dynamic registration and sign in with the authorization code grant and PKCE (S256).
