MCP Connect AI
Connect an AI app on your computer to CrossWatch through MCP, with a read-only token.
Connect an AI app on your computer to CrossWatch through MCP.
The app can inspect your installation and help diagnose problems.
How it works
Your AI app connects to CrossWatch with a read-only token.
It calls CrossWatch tools to read health, logs, events and settings, then answers you.
AI app on your computer
↓
Read-only token
↓
CrossWatch /api/mcp
↓
Read-only toolsThe AI app can only read. It cannot change settings, start a sync or delete anything.
Prefer to ask inside CrossWatch? See Assistant.
Before you begin
You need:
Sign-in turned on in CrossWatch. The MCP endpoint only answers to an API token.
An AI app that supports MCP and runs on a computer that can reach CrossWatch.
Configure an AI app
Sign in with an administrator account.
Open Settings → UI Settings → Security.
Find AI help and the Use your own AI app panel.
Choose your app.
Click Create token. The token is filled into the text below.
Click Copy and paste the text into your app.
Each token appears in the list with when it was created and last used.
Click Revoke to cut that app off.
Create a token with the CLI
Create a read-only token from the CrossWatch container:
Check that the endpoint answers with that token:
mcp check shows the server and lists the tools.
App setup
Replace YOUR-CROSSWATCH-URL with the address you use to open CrossWatch, and cwt_YOUR_TOKEN with your token.
The AI help panel fills both in for you.
Claude Code — run once in a terminal:
Codex CLI — add to ~/.codex/config.toml:
Cursor — add to .cursor/mcp.json:
Gemini CLI — run once in a terminal:
LM Studio — open Program → Install → Edit mcp.json and add the same block as for Cursor.
VS Code (GitHub Copilot) — add to .vscode/mcp.json:
Claude Desktop
Claude Desktop can only start a local command. It needs a small bridge.
CrossWatch on a NAS or another computer
The bridge is mcp-remote. It needs Node.js on the computer that runs Claude Desktop.
Add to claude_desktop_config.json:
Leave out --allow-http when CrossWatch uses https.
CrossWatch in Docker on the same computer
The CrossWatch CLI is the bridge. Nothing else has to be installed.
Change crosswatch if your container has another name.
Available tools
get_health
Provider connections, watcher, scheduler, last sync and version
get_last_sync
The last sync run and the items it could not resolve
list_pairs
Sync pairs with their features
get_config
The configuration with secrets, hosts and account names removed
list_log_sessions
Saved sync, watcher and debug logs
read_logs
Lines from one log, filtered by level, provider or text
read_log_context
The lines around one log line
search_events
Sync and scrobble events, newest first
get_item_events
Everything recorded for one movie, show or episode
get_watcher_status
Watcher routes and what is playing right now
get_analyzer_problems
Items that differ between the two sides of a pair
get_anime_mapping_status
Anime mapping state and last update
list_captures
Saved captures
Your app lists its available tools after it connects. Ask in plain language, such as “Why did my last sync fail?”
Tokens
A token from Create token or --access monitor is read-only.
It belongs to the administrator, but can only read. It cannot create or revoke tokens.
A token of a managed user with the Monitor access level works the same way.
An administrator token also works, but gives the app full access. Use a read-only token instead.
Troubleshooting
401 Unauthorized — the token is missing, wrong or revoked. Create a new one.
403 MCP needs an admin or monitor API token — sign-in is off, or the token belongs to a regular managed user.
403 Origin mismatch — the app runs in a web browser. MCP only accepts apps on your computer.
400 Unsupported protocol version — update your AI app.
Claude Desktop: npx not found — install Node.js, or use the Docker bridge when CrossWatch runs on the same computer.
Cannot connect at all — open
http://YOUR-CROSSWATCH-URLin a browser on the same computer. The app needs the same address.Not sure if the token works — run
cw --token cwt_... mcp check.
Security
The MCP endpoint is read-only and only answers to an administrator or read-only API token.
Secrets never leave CrossWatch. Tokens, passwords, API keys, webhook addresses and the sign-in settings are removed from everything the tools return.
Log lines are scrubbed again when they are read, including logs saved before an update.
Audit events are not available through MCP.
CrossWatch rejects requests from web pages on other sites, and checks the MCP protocol version.
Last updated
Was this helpful?