# MCP server

Connect an AI assistant to your AyeWatch monitors using your existing API key.

Source: https://ayewatch.ai/documentation/mcp

## Connect your assistant

The MCP endpoint is `https://ayewatch.ai/api/mcp`. It uses Streamable HTTP and accepts your existing AyeWatch API key in the `Authorization: Bearer aw_live_...` header on every request.

Generate a key in [API access settings](https://ayewatch.ai/settings/api). API and MCP access are available on every paid plan.

For [Cursor](https://cursor.com/docs/context/mcp), add this entry to your MCP configuration. Other clients need the same URL, Streamable HTTP transport, and Authorization header. Replace the placeholder with your key and keep the configuration private.

```json
{
  "mcpServers": {
    "ayewatch": {
      "url": "https://ayewatch.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer aw_live_YOUR_API_KEY"
      }
    }
  }
}
```

This server uses API-key authentication. It does not provide OAuth sign-in. Clients that require OAuth or cannot send a custom Authorization header cannot connect directly.

## Available tools

- `list_topics`: list monitors with optional `page`, `page_size`, `is_active`, `interval`, `created_after`, and `created_before` filters. Page numbers and sizes are integers. The default page size is 20, with a maximum of 100. Responses include `pagination.has_more`.
- `get_topic`: get a monitor by numeric `topic_id`.
- `create_topic`: create a monitor using the same fields as the REST API. Supply a name, web-page URLs, or a template, plus an interval for custom monitoring or `monitoring_mode: "auto"`.
- `update_topic`: supply `topic_id` and a `changes` object with only the fields you want to update. Set `changes.is_active` to `false` to pause or `true` to resume.
- `delete_topic`: permanently delete a monitor and its schedule by `topic_id`.

See [Topics API](https://ayewatch.ai/documentation/topics) for monitor fields and supported intervals.

Example `create_topic` arguments:

```json
{
  "name": "https://example.com/releases",
  "description": "Alert me when a new version is released.",
  "monitoring_mode": "auto",
  "is_active": false
}
```

This example creates a paused monitor. Review it, then call `update_topic` with its returned ID and `changes: {"is_active": true}` to start monitoring.

## Access and limits

MCP manages the same monitors as the website, mobile app, and REST API. Existing plan limits, monitoring credits, ownership checks, and API-key revocation apply. Active monitors consume credits as checks run.

MCP and REST share the API key's rate limit, 120 requests per minute by default. Each MCP POST, including initialization and tool discovery, counts once. Send one MCP message per POST; batches are rejected. Responses include `X-Request-Id` and `RateLimit-*` headers. A 429 response includes `Retry-After`.

Authentication failures return HTTP 401 or 403. Tool failures return an MCP result with `isError: true`; monitor-service failures include an error message and HTTP-equivalent status. Tool results include both text and structured JSON.

The endpoint is stateless. It returns JSON over Streamable HTTP and requires no session ID. GET and DELETE return 405 because it does not offer a persistent event stream or sessions to delete. Browser requests must use the same origin as the endpoint.

Updates continue to arrive through your configured notifications and [webhooks](https://ayewatch.ai/documentation/webhooks). These tools manage monitors; they do not provide an alert-history feed.