MCP Server

Connect AI assistants to your ScryWatch project over the Model Context Protocol.

/mcp exposes your project’s logs, alerts, sessions, patterns, issues, deploys, and checks as MCP tools, so an MCP-aware AI client (Claude, an IDE assistant, etc.) can query them directly. It speaks JSON-RPC 2.0 over both current MCP HTTP transports.

Auth

This endpoint does not use requireApiKey. It uses a dedicated requireMcpBearer middleware that accepts two token forms on the same Authorization: Bearer <token> header:

An OAuth access token, prefixed at_..., issued via the /oauth authorization-code flow.
A legacy project API key (the same key type used elsewhere in the API) — any token that doesn’t start with at_ is tried against the API key table.

Both forms resolve to the same userId/orgId/projectId scoping used by the tool handlers.

401 responses — body shape is { "error": "<reason>" } (not "Missing API key"), and every 401 carries WWW-Authenticate: Bearer error="invalid_token", resource_metadata="https://api.scrywatch.com/.well-known/oauth-protected-resource" for OAuth discovery, plus Cache-Control: no-store:

reason	when
`Missing token`	No `Authorization: Bearer ...` header
`Invalid token`	Token starts with `at_` but doesn’t match any access token
`Token revoked`	Matched an access token that has been revoked
`Token expired`	Matched an access token past its `expires_at`
`Invalid API key`	Token doesn’t start with `at_` and doesn’t match any API key

The common 401/402/429 shapes documented on the Authentication page do not apply here — this endpoint has its own error shapes (above) and no usage-limit or rate-limit enforcement.

Transports

POST /mcp — Streamable HTTP (current)

Send a JSON-RPC 2.0 request body. If the request’s Accept header includes text/event-stream, the response is wrapped as a single SSE message (event: message\ndata: <json>\n\n, Content-Type: text/event-stream); otherwise the response is plain application/json. A malformed body returns 400 with a JSON-RPC parse error ({"jsonrpc":"2.0","id":null,"error":{"code":-32700,"message":"Parse error"}}).

initialize additionally returns an Mcp-Session-Id response header (server-generated ULID). notifications/initialized is a one-way notification — the server replies with an empty 204, not a JSON-RPC body.

GET /mcp — legacy SSE (2024-11-05)

Opens an SSE stream and immediately emits an endpoint event whose data is the absolute URL to POST JSON-RPC messages to (https://api.scrywatch.com/mcp). The client then sends its JSON-RPC requests as separate POST /mcp calls. The stream sends a : keepalive comment every 15 seconds and stays open until the client disconnects.

JSON-RPC methods

method	behavior
`initialize`	Returns `{ protocolVersion: "2025-03-26", capabilities: { tools: {} }, serverInfo: { name: "scrywatch", version: "1.0.0" } }`
`tools/list`	Returns `{ tools: [...] }` — the 14 tool definitions below, each with a JSON Schema `inputSchema`
`tools/call`	Runs a tool: `params.name` (required) and `params.arguments`. Errors: `-32602` missing tool name, `-32601` unknown tool, `-32603` internal error
`notifications/initialized`	One-way; no response body (`204`)
anything else	`-32601 Method not found: <method>`

Tool results are { content: [{ type: "text", text: "<JSON or formatted string>" }], isError?: true } — a text-oriented shape per the MCP spec, not raw JSON objects.

Available tools

Each tool operates on the single project resolved from your bearer token — there’s no cross-project or org-level tool.

tool	maps to
`search_logs`	`GET /api/logs` filters (`level`, `type`, `q`, `from`, `to`, `limit`, `offset`, `service`, `environment`, `device_type`)
`get_log`	`GET /api/logs/:id`
`get_log_stats`	`GET /api/stats` (`from`/`to` default to the last 24h)
`get_log_facets`	`GET /api/facets`
`list_alerts`	`GET /api/alerts` — all configured rules
`get_alert_history`	Recent alert firings, `limit` (default 20)
`list_sessions`	`GET /api/sessions` (`environment`, `limit` default 50, `offset`)
`get_log_patterns`	Recurring message patterns in a time range, `limit`
`list_issues`	Same filters as `GET /api/orgs/:orgSlug/projects/:projectSlug/issues` (`status`, `type`, `service`, `environment`, `sort`, `limit` default 25, `offset`)
`get_issue`	One issue with stats, deploy correlation, and recent occurrences (`occurrence_limit` default 10)
`list_deploys`	Recent deploy markers (`service`, `environment`, `limit` default 20)
`diff_deploy`	Before/after behavior diff for a deploy; omit `deploy_id` to diff the latest matching `service`/`environment`. Never includes an AI `summary_text` (deterministic only over MCP)
`list_checks`	Synthetic checks with current status
`get_check`	One check’s 24h uptime/latency summary plus deploy/issue correlation

See Logs & Search, Alerts, Sessions, Issues, Deploys, and Patterns for the underlying field semantics.