# Visual Sentinel MCP Server

Model Context Protocol server for [Visual Sentinel](https://visualsentinel.com), the six-layer website monitoring platform: uptime, performance, SSL, DNS, visual regression, and content change detection.

Connect Claude Desktop, Claude Code, Cline, Continue, or any MCP-compatible client to your Visual Sentinel account so an AI assistant can list monitors, create them, fetch incident history, run free DNS / SSL / speed checks, and acknowledge alerts on your behalf.

* **npm:** `@visualsentinel/mcp-server`
* **OpenAPI spec:** https://github.com/VisualSentinel/openapi
* **Get an API key:** https://visualsentinel.com/settings/api-keys
* **Hosted API reference:** https://visualsentinel.com/docs

## What you get

16 tools spanning the public Visual Sentinel API:

**Public tools (no API key required)**

| Tool | Endpoint | Purpose |
|---|---|---|
| `vs_health` | `GET /api/health` | Service health probe |
| `vs_dns_check` | `GET /api/tools/dns-check` | Resolve A / AAAA / MX / NS / TXT / CNAME / SOA records |
| `vs_ssl_check` | `GET /api/tools/ssl-check` | Inspect TLS certificate (issuer, validity, SAN list, chain) |
| `vs_speed_test` | `GET /api/tools/speed-test` | One-shot performance check (TTFB, total load, transfer size) |
| `vs_website_check` | `GET /api/tools/website-check` | Quick HTTP health check |

**Authenticated tools (require `VS_API_KEY`)**

| Tool | Endpoint | Purpose |
|---|---|---|
| `vs_monitors_list` | `GET /api/monitors` | List monitors with optional status / type filters |
| `vs_monitors_get` | `GET /api/monitors/{id}` | Fetch a single monitor with current status |
| `vs_monitors_create` | `POST /api/monitors` | Create a new monitor |
| `vs_monitors_check_now` | `POST /api/monitors/{id}/check` | Trigger an immediate check |
| `vs_monitors_uptime` | `GET /api/monitors/{id}/uptime` | Uptime percentage over 24h / 7d / 30d / 90d / 365d |
| `vs_incidents_list` | `GET /api/incidents` | List incidents, filterable by status or monitor |
| `vs_incidents_get` | `GET /api/incidents/{id}` | Fetch an incident with full check history |
| `vs_alerts_list` | `GET /api/alerts` | List alerts by status |
| `vs_alerts_acknowledge` | `POST /api/alerts/{id}/acknowledge` | Acknowledge an alert |
| `vs_status_pages_list` | `GET /api/status-pages` | List your public status pages |
| `vs_servers_list` | `GET /api/servers` | List registered origin servers |

## Installation

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "visualsentinel": {
      "command": "npx",
      "args": ["-y", "@visualsentinel/mcp-server"],
      "env": {
        "VS_API_KEY": "vs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Restart Claude Desktop. The 16 tools appear under the tools menu.

### Claude Code (CLI)

```bash
claude mcp add visualsentinel \
  -- npx -y @visualsentinel/mcp-server
```

Then export `VS_API_KEY` in the shell where Claude Code runs.

### Cline (VS Code extension)

In Cline's MCP settings, add:

```json
{
  "visualsentinel": {
    "command": "npx",
    "args": ["-y", "@visualsentinel/mcp-server"],
    "env": { "VS_API_KEY": "vs_live_..." }
  }
}
```

### Continue

In `~/.continue/config.json`:

```json
{
  "mcpServers": [
    {
      "name": "visualsentinel",
      "command": "npx",
      "args": ["-y", "@visualsentinel/mcp-server"],
      "env": { "VS_API_KEY": "vs_live_..." }
    }
  ]
}
```

### Generic MCP client (stdio)

```bash
VS_API_KEY=vs_live_xxx npx -y @visualsentinel/mcp-server
```

The server speaks JSON-RPC over stdio per the MCP specification (`2025-06-18`).

## Configuration

Two environment variables, both optional except in the noted cases:

| Variable | Default | Purpose |
|---|---|---|
| `VS_API_KEY` | (none) | Required for the 11 authenticated tools. Public tools work without it. Generate at https://visualsentinel.com/settings/api-keys. |
| `VS_API_BASE` | `https://visualsentinel.com` | Override only for testing against a local development instance. |

If a tool that needs auth is called without `VS_API_KEY`, the server returns a clear error rather than silently failing.

`VISUALSENTINEL_API_KEY` is accepted as an alias for `VS_API_KEY` for clients that prefer the longer name.

## Usage examples

After installation, ask the AI assistant things like:

* "What's the SSL certificate situation on visualsentinel.com? When does it expire?"
* "List my Visual Sentinel monitors that are currently down."
* "Add a new HTTPS monitor for https://shop.example.com checking every minute."
* "Show me incidents from the last 24 hours and acknowledge the ones for monitor-id `clm123`."
* "What's the uptime percentage for my landing page over the last 30 days?"
* "Run a speed test on https://example.com/checkout."

The assistant chooses the appropriate tool, fills in arguments from the conversation, and shows the JSON response.

## Security notes

* Your API key never leaves the machine running this MCP server. Requests go directly to `https://visualsentinel.com` over HTTPS.
* Public tools (`vs_health`, `vs_dns_check`, `vs_ssl_check`, `vs_speed_test`, `vs_website_check`) work without an API key, but their results are visible to anyone who can read your conversation logs. Treat them like any other shell-out.
* Revoke a leaked API key immediately at https://visualsentinel.com/settings/api-keys. Revocation takes effect within seconds.
* Tools that mutate state (`vs_monitors_create`, `vs_monitors_check_now`, `vs_alerts_acknowledge`) inherit your API key's role-based permissions. A read-only key cannot create monitors.

## Development

```bash
git clone https://github.com/VisualSentinel/mcp-server.git
cd mcp-server
npm install
npm run build      # tsup, output to dist/
npm run lint       # tsc --noEmit
npm run dev        # tsup --watch
```

To smoke-test locally against the production API:

```bash
VS_API_KEY=vs_live_... node dist/index.js
```

The server speaks JSON-RPC on stdin / stdout. Pipe in a `tools/list` request to see the registered tools.

## Versioning

Semantic versioning. Breaking changes to tool names or required arguments get a major bump. Adding new tools or new optional arguments is a minor or patch.

The server's tool surface tracks the public Visual Sentinel API spec at https://github.com/VisualSentinel/openapi. When the upstream API gains a useful endpoint, this repository typically catches up within a release.

## License

MIT. See [`LICENSE`](./LICENSE).

The Visual Sentinel API service itself is governed by https://visualsentinel.com/terms.