Déploiement Passerelle MCP NyoraNotes (Multi-Agent, Séparation Stricte par Scope)

Date : 26 août 2026
Auteur : Gemini AntiGravity (sur brief Claude v2)
Tags : nyora-notes-mcp, mcp, streamable-http, scoping, dsh, tailscale, runbook
Statut : Validé et testé en direct de bout en bout sur NAS DS920+ et VPS Contabo

1. Contexte & Problématique

NyoraNotes est une application FastAPI purement REST, sans endpoint MCP natif (/mcp renvoyait 404). Les tentatives directes de connexion MCP depuis DSH étaient vouées à l'échec. De plus, la séparation d'accès entre agents nécessitait un contrôle strict par sous-dossier de vault (vault/dsh/), sans altérer le fonctionnement des 5 instances Hermes en production.

2. Architecture & Topologie

Service : nyora-notes-mcp (conteneur Python 3.11 / FastAPI / Starlette / MCP SDK 1.29.1).
Emplacement : /volume1/docker/nyora-notes-mcp sur le NAS DS920+.
Port : 3098 (mappé 0.0.0.0:3098 -> 8000/tcp).
Réseau : n8n (communique directement avec http://nyora-notes:8787 par nom de conteneur).
Transport MCP : streamable-http (point de montage /mcp/), compatible avec dsh-mcp-client et la spec MCP 2025-03-26.
Backend Auth : La passerelle utilise un credential backend unique (NYORA_BACKEND_TOKEN) pour relayer les requêtes vers NyoraNotes.
Scoping par agent : La couche applicative de la passerelle valide chaque requête MCP selon le token de l'agent appelant :
- mcp-dsh-89f4b32a10e74c5d98bc7211e405a8f2 → agent_id: dsh, préfixe autorisé : dsh/.

3. Outils MCP Exposés

Outil	Description	Contrôle de Sécurité / Scoping
`notes_create`	Crée une note Markdown	Chemin forcé ou validé sous `dsh/` ; tag `dsh` injecté en tête
`notes_get`	Récupère une note par son UUID	Vérifie que le `file_path` appartient au scope de l'agent (sinon 403)
`notes_list`	Liste les notes paginées	Filtre les résultats pour ne retourner que les notes du scope de l'agent
`notes_search`	Recherche FTS plein texte	Filtre les résultats pour exclure tout document hors scope de l'agent

4. Matrice de Validation & Preuves Brutes

Test	Commande / Méthode	Résultat constaté	Statut
Healthcheck	`GET http://192.168.100.33:3098/health`	`HTTP 200 OK`, service `nyora-notes-mcp`	✅ Validé
MCP Initialize	`POST /mcp/` avec token DSH	`HTTP 200 OK`, `serverInfo: nyora-notes-mcp`	✅ Validé
Test Scoping (Écriture autorisée)	`notes_create` sur `dsh/...`	`HTTP 201 Created`, note écrite dans `vault/dsh/`	✅ Validé
Test Scoping (Violation hermes-tt)	`notes_create` sur `hermes-tt/...`	`403 Forbidden` ("hors du scope autorise")	✅ Validé
Test Scoping (Path traversal)	`notes_create` sur `../hermes-tt/...`	`403 Forbidden` ("hors du scope autorise")	✅ Validé
Auth Invalide	`POST /mcp/` avec token erroné	`HTTP 401 Unauthorized`	✅ Validé
Exécution Native DSH	`dsh --profile headless` (sans curl)	Appel natif `notes_create` + `notes_list` + `notes_get`	✅ Validé
Preuve Physique NAS	`cat /volume1/docker/nyora-notes/vault/dsh/validation-finale-mcp-dsh.md`	Fichier présent sur disque NAS (257 octets)	✅ Validé

5. Procédure pour Ajouter un Nouvel Agent

Pour ajouter un futur agent MCP sans toucher à NyoraNotes :

Ouvrir /volume1/docker/nyora-notes-mcp/app/config.py.

Ajouter une entrée dans AGENT_SCOPES :

"mcp-nouvel-agent-secret-key": AgentScope(
    agent_id="nouvel-agent",
    allowed_prefixes=["nouvel-agent/"],
    description="Nouvel agent scopé à son dossier"
)

Redémarrer le conteneur : cd /volume1/docker/nyora-notes-mcp && docker compose restart nyora-notes-mcp.

3.9 KiB Raw Blame History