MCP introduction

WatchLLM ships a local MCP route at /mcp so assistants can inspect API-key validation, project context, monitors, prompts, citations, crawler analytics, visitor analytics, and related product data. Existing /api/mcp clients continue to work as a compatibility alias.

The MCP surface is intentionally backed by the same local app and database as the workspace. This keeps assistant workflows aligned with the REST v2 handlers and persisted WatchLLM state.

Authenticated MCP initialize, tools/list, and successful tools/call responses with project context share the same hourly organization quota as REST v2 and return X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Invalid bearer requests and organization-scoped tool calls without project context return before consuming organization quota.

Local check

curl http://localhost:3003/mcp

The route should return 200 when the app is running.

External smoke

Run the external smoke against a local seeded database:

MCP_BASE_URL=http://localhost:3003/mcp \
npm run smoke:mcp

When WATCHLLM_API_KEY is omitted, the smoke creates and cleans up a temporary organization-scoped key, then passes projectId through MCP tool arguments. To test a specific organization-scoped key, set WATCHLLM_API_KEY=<wllm_api_key> and WATCHLLM_PROJECT_ID=<project_id>. The smoke script verifies invalid bearer handling, rate-limit headers on initialize, tools/list, and representative tools/call requests, concrete input schemas, and representative output schemas for high-traffic tools through the same HTTP JSON-RPC route used by external MCP clients.

Claude Code install smoke

To verify the actual Claude Code CLI install path without changing your real Claude configuration, run:

WATCHLLM_BASE_URL=http://localhost:3003 \
npm run smoke:mcp-claude

The smoke creates a temporary local Claude config, runs claude mcp add, checks claude mcp get reports the WatchLLM server as connected, and deletes the temporary config and smoke API key afterward.