pytheos-mcp

Serveur Model Context Protocol (MCP) pour Pytheos : il expose les données et actions métier de votre instance (actions, projets, notes, indicateurs, calendrier, rapports…) aux assistants IA compatibles MCP (Cursor, Claude Desktop, Mistral Le Chat, LibreChat, etc.).

Prérequis

• Node.js ≥ 20
• Une instance Pytheos accessible en HTTPS
• Un jeton API utilisateur généré depuis Pytheos (fiche utilisateur → administration)

Installation

# Exécution ponctuelle (recommandé pour Cursor / Claude Desktop)
npx pytheos-mcp@latest

# Installation globale
npm install -g pytheos-mcp
pytheos-mcp

Modes de fonctionnement

Mode stdio (poste de travail)

Le client IA lance le processus localement. Configurez l’URL Pytheos et le jeton via les variables d’environnement :

{
  "mcpServers": {
    "pytheos": {
      "command": "npx",
      "args": ["-y", "pytheos-mcp@latest"],
      "env": {
        "PYTHEOS_BASE_URL": "https://monentreprise.pytheos.com",
        "PYTHEOS_API_KEY": "votre-jeton-api"
      }
    }
  }
}

Alternative : appelez le tool connect au début de chaque session avec instance_url et api_key.

Mode HTTP / Streamable (serveur)

Pour les clients en ligne (Mistral, LibreChat, MCP Playground…) :

PORT=3000 HOST=127.0.0.1 pytheos-mcp --http

Exposez ensuite l’endpoint /mcp via un reverse proxy Apache/Nginx (ProxyPreserveHost On) vers http://127.0.0.1:3000/mcp.

Authentification HTTP — à l’initialisation de la session, fournissez le jeton API via :

• Authorization: Bearer <jeton>
• ou X-Api-Key: <jeton>

L’URL de l’instance Pytheos est déduite de l’en-tête Host (ou X-Forwarded-Host derrière un proxy).

Exemple client streamable-http :

mcpServers:
  pytheos:
    type: streamable-http
    url: https://monentreprise.pytheos.com/mcp
    # Bearer token ou header X-Api-Key selon le client

Variables d’environnement

| Variable | Mode | Description | |----------|------|-------------| | PYTHEOS_BASE_URL | stdio | URL de base de l’instance (https://…) | | PYTHEOS_API_KEY | stdio | Jeton API utilisateur | | PORT | HTTP | Port d’écoute (active le mode HTTP si défini) | | HOST | HTTP | Interface d’écoute (défaut : 127.0.0.1) | | MCP_ALLOWED_HOSTS | HTTP | Hôtes autorisés, séparés par des virgules | | MCP_BASE_PROTO | HTTP | Schéma forcé si le proxy ne envoie pas X-Forwarded-Proto |

Démarrage de session

1. stdio : variables d’env configurées ou tool connect
2. HTTP : Bearer / X-Api-Key à l’init ou tool connect
3. Vérifier la connexion : getuserinfo ou getboardinfos

Outils MCP

| Outil | Description | |-------|-------------| | connect | Connexion à une instance avec jeton API | | getboardinfos | Tableau de bord utilisateur | | getuserinfo | Profil et droits de l’utilisateur | | userlist | Liste des utilisateurs | | search | Recherche globale (≥ 3 caractères) | | actionlist / actiondetails / addupdaction / setprogress | Actions | | projectlist / projectdetails / addupdproject | Projets / événements | | notelist / notedetails / addupdnote | Notes | | indicatorlist / indicatordetails / addupdindicator / addupdgoal | Indicateurs | | axislist / setaxisfilter | Axes / filtres | | getcalendar / reminderlist / todolist / eventlist | Agenda | | getreftables | Référentiels (statuts, priorités, types…) | | gettranslations | Libellés traduits | | getreportlist / printreport | Rapports |

Ressources MCP

| URI | Contenu | |-----|---------| | pytheos://user/profile | Profil utilisateur courant | | pytheos://user/semantics | Sémantique métier Pytheos | | pytheos://referentiels/action-states | États d’action | | pytheos://referentiels/action-priorities | Priorités | | pytheos://referentiels/action-types | Types d’action | | pytheos://referentiels/project-statuses | Statuts projet | | pytheos://referentiels/project-types | Types d’événement projet |

Sécurité

• Le jeton API est personnel : il hérite des droits de l’utilisateur Pytheos qui l’a généré.
• Ne commitez jamais de jeton dans un dépôt ou une config partagée.
• En mode HTTP, chaque session MCP isole ses credentials en mémoire.

Déploiement serveur Pytheos

Sur une instance Pytheos auto-hébergée, les scripts d’installation systemd et Apache se trouvent dans le dépôt applicatif (pymcp/install-mcp.sh, pymcp/configure-apache-mcp.sh). Le paquet npm ne contient que le binaire Node.

Support

• Documentation Pytheos : connecteur MCP dans l’administration Pytheos
• Site : pytheos.com
• Support : [email protected]

Licence

Propriétaire — usage réservé aux clients Pytheos (UNLICENSED).