For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

This uses MCP, the Model Context Protocol. CrossWatch offers a read-only MCP endpoint at /api/mcp.

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 tools

The 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

  1. Sign in with an administrator account.

  2. Open Settings → UI Settings → Security.

  3. Find AI help and the Use your own AI app panel.

  4. Choose your app.

  5. Click Create token. The token is filled into the text below.

  6. 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

Tool
What it reads

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-URL in 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?