🇬🇧 English · 🇫🇷 Français

Applies to Hydranos 4.4.

This page is for you if you want an AI assistant or any other MCP client to look at your library and act on it through the Model Context Protocol. By the end you will know how to connect a client, which tools it gets, which ones can remove data and how to unlock them, and what the server refuses. Terms: Concepts and Glossary.

Every Hydranos instance serves an MCP server on the same listener as the web UI, port 8199, at POST /mcp. There is nothing to install or turn on, and there is no screen for it in the web UI.

• Transport: stateless "streamable HTTP". Each POST /mcp carries one JSON-RPC 2.0 message and gets one JSON answer. There is no session and no SSE stream: GET /mcp and DELETE /mcp answer 405 with Allow: POST.
• Protocol versions: 2025-06-18, 2025-03-26, 2024-11-05. If the client asks for another version, the server answers with 2025-06-18.
• Methods: initialize, ping, tools/list, tools/call. The server offers tools only: no resources, no prompts. serverInfo is {"name": "hydranos", "title": "Hydranos", "version": "4.x.y"} (the running version). The initialize answer also carries short instructions that tell the model to start with overview, page with find_torrents, and name torrents by info hash.
• Batches (a JSON array of messages) are refused. A message without an id is a notification: 202 with an empty body.
• While Hydranos starts, /mcp answers 503 with Retry-After: 5 like every API route, until the catalogue is loaded (REST API, While Hydranos starts).
• Writes use the REST API. Every write tool except add_torrent sends its request to the real /api route inside the process, so it gets the same checks and refusals as the web UI. add_torrent calls the same add function the add routes use, without going through a route. No write takes a filter: every write names its torrents by info hash.

sequenceDiagram
    participant C as MCP client
    participant M as Hydranos POST /mcp
    participant A as /api routes in-process
    C->>M: initialize with Authorization Bearer key
    M-->>C: protocolVersion, tools capability, serverInfo hydranos
    C->>M: notifications/initialized, no id
    M-->>C: 202, no body
    C->>M: tools/list
    M-->>C: 19 tools, or 21 with allow_destructive
    C->>M: tools/call find_torrents
    M->>M: build one page from the engine list
    M-->>C: result with content text and structuredContent
    C->>M: tools/call pause with info_hashes
    loop each engine holding some of the hashes
        M->>A: POST /api/engines/ENGINE/torrents/bulk
        A-->>M: status and answer
    end
    M-->>C: result, isError false, per-engine ok and status
    Note over C,M: isError true when the tool itself fails<br/>(bad arguments, disabled tool, unknown torrent,<br/>refused add, failed read). Per-torrent write<br/>failures stay isError false with ok false

You need two things: the URL http://<host>:8199/mcp and the instance's API key ([daemon] api_key, see Security and Access). The server accepts the key in any of these forms:

A missing or wrong key gets 401 with WWW-Authenticate: Bearer and {"error": "Invalid or missing API key"}. If api_key is empty, nobody is let in. The query-parameter form puts the key in URLs, which end up in proxy logs: use a header when your client can.

Most MCP clients read a JSON file with an mcpServers object. Add Hydranos as an HTTP server:

{
  "mcpServers": {
    "hydranos": {
      "type": "http",
      "url": "http://192.0.2.10:8199/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Some clients call the type streamable-http or streamableHttp instead of http; Hydranos does not care which, it only sees the POSTs. If your client only supports local (stdio) servers, put a stdio-to-HTTP bridge in between and give it the same URL and header.

With Claude Code, for example, the same thing is one command:

claude mcp add --transport http hydranos http://192.0.2.10:8199/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

# Handshake
curl -s http://192.0.2.10:8199/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

# List the tools
curl -s http://192.0.2.10:8199/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# Ten torrents of the hoard engine in error with their tracker
curl -s http://192.0.2.10:8199/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"find_torrents","arguments":{"engine":"hoard","error_class":"dead","limit":10}}}'

Because the server is stateless, you can send tools/call without initialize first; the handshake is only there for clients that expect it.

19 tools are listed by default. Each carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so the client can decide when to ask you before calling. engine arguments take an engine id as overview lists it; when omitted, reads use hoard (or the first engine if there is no hoard).

Every info_hashes list is checked before anything happens: each entry must be 40 hex characters, duplicates are dropped, and a list over the limit is refused as a whole. Per-torrent tools answer {"ok": n, "failed": n, "results": [...]} with one {info_hash, ok, status, answer} per torrent; pause/resume answer one entry per engine plus a not_found list.

delete_torrents and purge_race are not listed and not callable unless you enable them:

[mcp]
allow_destructive = true

The [mcp] section is not in the shipped default.toml, and the Config tab can only change keys that already exist, so add it by hand to the config file (see Configuration: Daemon, Auth and Global Sections) and restart Hydranos (see Operating Hydranos for a clean stop). Once the section exists, it shows up under Other in Advanced settings (default.toml); the switch is read on every request, so a change saved there applies to /mcp at once.

With the switch off, a client that calls one of them anyway (for example from a cached tool list) gets an isError result: `delete_torrents` is disabled on this node; set `allow_destructive = true` under `[mcp]` in the configuration to enable it. Both tools carry destructiveHint: true, so a well-behaved client asks you before each call.

• Pages, not the library. find_torrents returns at most 200 rows per call; follow next_offset. The other caps are in the tool tables above.
• The category must exist for add_torrent, set_category (unless empty) and move_to_category. An unknown name is refused with the list of valid ones. This is stricter than the REST API and the qBittorrent shim: their label routes store any name, and their add routes accept an unknown name as long as a save path is sent (the torrent then lands in race). Create categories first on the Categories tab.
• Never seed mode, never a subfolder. add_torrent always hash-checks data already on disk, for a magnet too, and does not apply create_subfolder / [daemon] create_torrent_folder. To add over complete data without a check, or with a folder of its own, use the REST API or the shim (see Adding Torrents and Existing Data).
• engine on a magnet is not checked. With torrent_path or torrent_url, an unknown engine is refused with the list of engines; with magnet, an unknown engine is ignored and the category decides where the torrent goes.
• What MCP does not cover in 4.4. There is no tool for RSS feeds and rules, download order (file priorities, sequential), speed or share limits, the queue, the network settings or nodes. Use the web UI or the REST API for those (RSS and Automatic Downloads, Queue, Share and Speed Limits).
• Reads show the same merged list as the web UI; writes act on this instance only. overview, find_torrents and tracker_errors include rows from other local engines with the same role and, if you have declared nodes, their rows too (the agent field, a legacy name, holds the row label local-<engine> or <node>-<engine>). torrent_detail and every write look only at this instance's engines: for a hash held only by a node, torrent_detail answers no torrent <hash> on this node, recheck, set_category, set_tags and move_to_category answer no such torrent on this node (status 404), reannounce and delete_torrents report the route's own 404, and pause/resume list it in not_found. To act on a node's torrents, point a client at that node's own /mcp. See Nodes and Multiple Machines.
• Copies in several local engines. reannounce, recheck, set_category and move_to_category act on the copy in the first engine that holds it. set_tags changes the tags of every copy. pause/resume write the stopped flag on every copy's row but stop or start only the copy in the first engine; the other copies keep running (or stay stopped) until the next restart, then follow the flag. delete_torrents without engine reaches every copy.
• No Origin check. The endpoint relies on the API key alone. Keep port 8199 on your LAN or behind a VPN or reverse proxy, as for the rest of the API.

There are two kinds of failure, and clients show them differently.

Tool errors are normal results flagged isError: true with a text message the model can read and act on, for example unknown category `tv`; this node has: movies, tv-hd, unknown engine `vpn2`; this node runs: race, hoard, info_hashes is empty, or give one of torrent_path, torrent_url or magnet. A successful call returns isError: false with the JSON both as content[0].text and as structuredContent.

Protocol errors are JSON-RPC errors:

• REST API: every route the write tools use, the stubs and the routes removed in 4.4.
• Security and Access: the API key, rotating it, exposing port 8199.
• Configuration: Daemon, Auth and Global Sections: the [mcp] key.
• Adding Torrents and Existing Data: add paths compared, seed mode.