🇬🇧 English · 🇫🇷 Français

S'applique à Hydranos 4.4.

Cette page est pour vous si vous voulez qu'un assistant IA, ou tout autre client MCP, consulte votre bibliothèque et agisse dessus via le Model Context Protocol. À la fin, vous saurez connecter un client, quels outils il obtient, lesquels peuvent supprimer des données et comment les déverrouiller, et ce que le serveur refuse. Vocabulaire : Concepts & glossaire.

Chaque instance Hydranos sert un serveur MCP sur la même écoute que l'interface web, port 8199, à POST /mcp. Il n'y a rien à installer ni à activer, et aucun écran ne lui est consacré dans l'interface web.

• Transport : « streamable HTTP » sans état. Chaque POST /mcp transporte un message JSON-RPC 2.0 et reçoit une réponse JSON. Il n'y a ni session ni flux SSE : GET /mcp et DELETE /mcp répondent 405 avec Allow: POST.
• Versions du protocole : 2025-06-18, 2025-03-26, 2024-11-05. Si le client demande une autre version, le serveur répond avec 2025-06-18.
• Méthodes : initialize, ping, tools/list, tools/call. Le serveur propose uniquement des outils : ni ressources, ni prompts. serverInfo vaut {"name": "hydranos", "title": "Hydranos", "version": "4.x.y"} (la version en cours d'exécution). La réponse à initialize contient aussi de courtes instructions qui disent au modèle de commencer par overview, de paginer avec find_torrents et de désigner les torrents par leur info hash.
• Pendant le démarrage d'Hydranos, /mcp répond 503 avec Retry-After: 5, comme toutes les routes de l'API, jusqu'à ce que le catalogue soit chargé (API REST, Pendant le démarrage d'Hydranos).
• Les lots (un tableau JSON de messages) sont refusés. Un message sans id est une notification : 202 avec un corps vide.
• Les écritures passent par l'API REST. Chaque outil d'écriture, sauf add_torrent, envoie sa requête à la vraie route /api à l'intérieur du processus, et subit donc les mêmes contrôles et refus que l'interface web. add_torrent appelle la même fonction d'ajout que les routes d'ajout, sans passer par une route. Aucune écriture ne prend de filtre : chaque écriture désigne ses torrents par info hash.

sequenceDiagram
    participant C as Client MCP
    participant M as Hydranos POST /mcp
    participant A as Routes /api dans le processus
    C->>M: initialize avec la clé en Authorization Bearer
    M-->>C: protocolVersion, capacité tools, serverInfo hydranos
    C->>M: notifications/initialized, sans id
    M-->>C: 202, sans corps
    C->>M: tools/list
    M-->>C: 19 outils, ou 21 avec allow_destructive
    C->>M: tools/call find_torrents
    M->>M: construit une page à partir de la liste du moteur
    M-->>C: résultat avec content text et structuredContent
    C->>M: tools/call pause avec info_hashes
    loop chaque moteur qui détient une partie des hashes
        M->>A: POST /api/engines/ENGINE/torrents/bulk
        A-->>M: statut et réponse
    end
    M-->>C: résultat, isError false, ok et statut par moteur
    Note over C,M: isError true quand l'outil lui-même échoue<br/>(arguments invalides, outil désactivé, torrent inconnu,<br/>ajout refusé, lecture en échec). Les échecs d'écriture<br/>par torrent restent isError false avec ok false

Il vous faut deux choses : l'URL http://<host>:8199/mcp et la clé API de l'instance ([daemon] api_key, voir Sécurité & accès). Le serveur accepte la clé sous l'une de ces formes :

Une clé absente ou erronée reçoit 401 avec WWW-Authenticate: Bearer et {"error": "Invalid or missing API key"}. Si api_key est vide, personne n'entre. La forme en paramètre de requête met la clé dans les URL, qui finissent dans les journaux du proxy : utilisez un en-tête quand votre client le permet.

La plupart des clients MCP lisent un fichier JSON avec un objet mcpServers. Ajoutez Hydranos comme serveur HTTP :

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

Certains clients appellent ce type streamable-http ou streamableHttp au lieu de http ; Hydranos ne s'en soucie pas, il ne voit que les POST. Si votre client ne prend en charge que les serveurs locaux (stdio), intercalez un pont stdio vers HTTP et donnez-lui la même URL et le même en-tête.

Avec Claude Code, par exemple, la même chose tient en une commande :

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}}}'

Comme le serveur est sans état, vous pouvez envoyer tools/call sans initialize préalable ; la poignée de main n'existe que pour les clients qui l'attendent.

19 outils sont listés par défaut. Chacun porte des annotations MCP (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) pour que le client puisse décider quand vous demander confirmation avant l'appel. Les arguments engine prennent un identifiant de moteur tel que overview le liste ; s'il est omis, les lectures utilisent hoard (ou le premier moteur s'il n'y a pas de hoard).

Chaque liste info_hashes est vérifiée avant toute action : chaque entrée doit faire 40 caractères hexadécimaux, les doublons sont retirés, et une liste qui dépasse la limite est refusée en bloc. Les outils par torrent répondent {"ok": n, "failed": n, "results": [...]} avec un {info_hash, ok, status, answer} par torrent ; pause/resume répondent une entrée par moteur plus une liste not_found.

delete_torrents et purge_race ne sont ni listés ni appelables tant que vous ne les activez pas :

[mcp]
allow_destructive = true

La section [mcp] ne figure pas dans le default.toml livré, et l'onglet Config ne peut modifier que des clés qui existent déjà : ajoutez-la donc à la main dans le fichier de configuration (voir Config : démon, auth & global) et redémarrez Hydranos (voir Exploiter Hydranos pour un arrêt propre). Une fois la section présente, elle apparaît sous Other dans Paramètres avancés (default.toml) (Advanced settings (default.toml)) ; l'interrupteur est relu à chaque requête, donc une modification enregistrée là s'applique immédiatement à /mcp.

Interrupteur désactivé, un client qui appelle malgré tout l'un de ces outils (par exemple depuis une liste d'outils en cache) reçoit un résultat isError : `delete_torrents` is disabled on this node; set `allow_destructive = true` under `[mcp]` in the configuration to enable it. Les deux outils portent destructiveHint: true, donc un client bien élevé vous demande confirmation avant chaque appel.

• Des pages, pas toute la bibliothèque. find_torrents renvoie au plus 200 lignes par appel ; suivez next_offset. Les autres plafonds figurent dans les tableaux d'outils ci-dessus.
• La catégorie doit exister pour add_torrent, set_category (sauf si vide) et move_to_category. Un nom inconnu est refusé avec la liste des noms valides. C'est plus strict que l'API REST et le shim qBittorrent : leurs routes d'étiquetage enregistrent n'importe quel nom, et leurs routes d'ajout acceptent un nom inconnu tant qu'un chemin de sauvegarde est envoyé (le torrent atterrit alors dans race). Créez d'abord les catégories dans l'onglet Catégories (Categories).
• Jamais de mode seed, jamais de sous-dossier. add_torrent vérifie toujours par hash les données déjà sur disque, pour un magnet aussi, et n'applique pas create_subfolder / [daemon] create_torrent_folder. Pour ajouter par-dessus des données complètes sans vérification, ou avec un dossier à lui, utilisez l'API REST ou le shim (voir Ajouter des torrents & données existantes).
• engine n'est pas vérifié pour un magnet. Avec torrent_path ou torrent_url, un engine inconnu est refusé avec la liste des moteurs ; avec magnet, un engine inconnu est ignoré et la catégorie décide où va le torrent.
• Ce que MCP ne couvre pas en 4.4. Il n'existe aucun outil pour les flux et règles RSS, l'ordre de téléchargement (priorités de fichiers, séquentiel), les limites de débit ou de partage, la file, les réglages réseau ni les nœuds. Utilisez pour cela l'interface web ou l[[API REST|REST-API-FR]] (RSS et téléchargements automatiques, File d'attente, limites de partage et de débit).
• Les lectures montrent la même liste fusionnée que l'interface web ; les écritures n'agissent que sur cette instance. overview, find_torrents et tracker_errors incluent les lignes des autres moteurs locaux de même rôle et, si vous avez déclaré des nœuds, leurs lignes aussi (le champ agent, un nom historique, contient l'étiquette de ligne local-<engine> ou <node>-<engine>). torrent_detail et toutes les écritures ne regardent que les moteurs de cette instance : pour un hash détenu uniquement par un nœud, torrent_detail répond no torrent <hash> on this node, recheck, set_category, set_tags et move_to_category répondent no such torrent on this node (statut 404), reannounce et delete_torrents rapportent le 404 de la route elle-même, et pause/resume le listent dans not_found. Pour agir sur les torrents d'un nœud, faites pointer un client vers le /mcp de ce nœud. Voir Nœuds & plusieurs machines.
• Copies dans plusieurs moteurs locaux. reannounce, recheck, set_category et move_to_category agissent sur la copie du premier moteur qui la détient. set_tags change les tags de chaque copie. pause/resume écrivent l'indicateur d'arrêt sur la ligne de chaque copie mais n'arrêtent ou ne démarrent que la copie du premier moteur ; les autres copies continuent de tourner (ou restent arrêtées) jusqu'au prochain redémarrage, puis suivent l'indicateur. delete_torrents sans engine atteint toutes les copies.
• Pas de contrôle de l'Origin. L'endpoint ne repose que sur la clé API. Gardez le port 8199 sur votre LAN ou derrière un VPN ou un reverse proxy, comme pour le reste de l'API.

Il existe deux sortes d'échecs, et les clients les affichent différemment.

Les erreurs d'outil sont des résultats normaux marqués isError: true avec un message texte que le modèle peut lire et exploiter, par exemple unknown category `tv`; this node has: movies, tv-hd, unknown engine `vpn2`; this node runs: race, hoard, info_hashes is empty, ou give one of torrent_path, torrent_url or magnet. Un appel réussi renvoie isError: false avec le JSON à la fois dans content[0].text et dans structuredContent.

Les erreurs de protocole sont des erreurs JSON-RPC :

• API REST : toutes les routes qu'utilisent les outils d'écriture, les bouchons et les routes supprimées en 4.4.
• Sécurité & accès : la clé API, son renouvellement, l'exposition du port 8199.
• Config : démon, auth & global : la clé [mcp].
• Ajouter des torrents & données existantes : les chemins d'ajout comparés, le mode seed.