> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/ui-settings/ai-help/mcp-connect-ai.md). # 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. {% hint style="info" %} This uses MCP, the Model Context Protocol. CrossWatch offers a read-only MCP endpoint at `/api/mcp`. {% endhint %} ### 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](/crosswatch/settings/ui-settings/ai-help/assistant.md). ### 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. {% hint style="warning" %} Cloud chat apps, such as the ChatGPT or Claude website, connect from the vendor's servers. They cannot reach a CrossWatch on your home network. Use an app on your own computer instead. {% endhint %} ### 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. {% hint style="warning" %} The token is shown only once. Copy the text before you leave the page. Lost it? Create a new token and revoke the old one. {% endhint %} 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: ``` docker exec -it crosswatch cw auth token create --name ai --access monitor ``` Check that the endpoint answers with that token: ``` docker exec -it crosswatch cw --token cwt_... mcp check ``` `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: ``` claude mcp add --transport http crosswatch http://YOUR-CROSSWATCH-URL/api/mcp --header "Authorization: Bearer cwt_YOUR_TOKEN" ``` **Codex CLI** — add to `~/.codex/config.toml`: ```toml [mcp_servers.crosswatch] url = "http://YOUR-CROSSWATCH-URL/api/mcp" http_headers = { "Authorization" = "Bearer cwt_YOUR_TOKEN" } ``` **Cursor** — add to `.cursor/mcp.json`: ```json { "mcpServers": { "crosswatch": { "url": "http://YOUR-CROSSWATCH-URL/api/mcp", "headers": { "Authorization": "Bearer cwt_YOUR_TOKEN" } } } } ``` **Gemini CLI** — run once in a terminal: ``` gemini mcp add --transport http --header "Authorization: Bearer cwt_YOUR_TOKEN" crosswatch http://YOUR-CROSSWATCH-URL/api/mcp ``` **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`: ```json { "servers": { "crosswatch": { "type": "http", "url": "http://YOUR-CROSSWATCH-URL/api/mcp", "headers": { "Authorization": "Bearer cwt_YOUR_TOKEN" } } } } ``` ### 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](https://nodejs.org) on the computer that runs Claude Desktop. Add to `claude_desktop_config.json`: ```json { "mcpServers": { "crosswatch": { "command": "npx", "args": ["-y", "mcp-remote", "http://YOUR-CROSSWATCH-URL/api/mcp", "--header", "Authorization:${AUTH_HEADER}", "--allow-http"], "env": { "AUTH_HEADER": "Bearer cwt_YOUR_TOKEN" } } } } ``` 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. ```json { "mcpServers": { "crosswatch": { "command": "docker", "args": ["exec", "-i", "-e", "CW_TOKEN=cwt_YOUR_TOKEN", "crosswatch", "cw", "mcp", "serve"] } } } ``` 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://wiki.crosswatch.app/crosswatch/settings/ui-settings/ai-help/mcp-connect-ai.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.