Connecter un agent IA

Portal a un serveur MCP, le protocole qui relie un agent IA à des outils. Ton agent y lit tes projets, et si tu le permets, écrit pour toi : un message, du temps passé, une étape. Il agit avec tes droits, dans un espace à la fois.

Avant de commencer : être dans l’équipe de l’espace.

1. Ajoute le serveur à ton agent

   L’adresse du serveur est https://app.hgdc.ch/portal/mcp. Tu la retrouves dans Réglages, section Connecter un agent IA, avec des exemples prêts à copier.

2. Connecte-toi

   Un agent qui sait se connecter ouvre la page de connexion HGDC. Choisis l’espace et accepte les droits demandés. Sinon, crée une clé d’API.

3. Demande

   Par exemple « Quels sont mes projets en cours ? », « Résume les derniers messages du projet Boutique », « Note 1 h 30 hier sur le projet Site ».

Claude Code

claude mcp add --transport http portal https://app.hgdc.ch/portal/mcp

Puis tape /mcp dans Claude Code pour te connecter.

Claude Desktop

Ouvre Paramètres, puis Connecteurs, et ajoute un connecteur personnalisé avec l’adresse du serveur. Claude ouvre la connexion HGDC. Les connecteurs personnalisés demandent une offre payante de Claude.

VS Code

Dans .vscode/mcp.json :

{
  "servers": {
    "portal": {
      "type": "http",
      "url": "https://app.hgdc.ch/portal/mcp"
    }
  }
}

VS Code ouvre la connexion HGDC au premier appel.

Avec une clé d’API

Pour un agent qui ne sait pas se connecter, ou pour un script, crée une clé dans Réglages, section Clés d’API : choisis Lecture seule ou Lecture et écriture, et la durée. Copie-la : elle ne s’affiche qu’une fois. Elle part dans l’en-tête Authorization :

claude mcp add --transport http portal https://app.hgdc.ch/portal/mcp \
  --header "Authorization: Bearer hgdc_portal_..."

La même clé sert l’API REST. Les anciens jetons pmcp_ marchent encore, pour le serveur MCP seulement. Remplace-les par une clé ou par la connexion HGDC, puis révoque-les dans Réglages.

Les outils

Outil	Ce qu’il fait
list_projects, get_project	Lit tes projets, leurs étapes et leurs tâches
list_messages, list_documents	Lit les messages et les documents d’un projet
list_invoices, get_invoice	Lit les factures
list_signatures, list_actions, list_meetings	Lit les signatures, les actions demandées aux clients et les réunions
list_time_entries, my_todo, agenda	Lit le temps passé, ce qui t’attend et ton agenda
list_clients, get_client, list_prospects	Lit tes clients et tes prospects
send_message	Écrit dans le fil d’un projet. Le client le lit
log_time	Saisit du temps passé
create_prospect	Ajoute un prospect
add_phase, add_step	Ajoute une étape à un projet, ou une tâche à une étape
request_client_action	Demande quelque chose au client. Il est prévenu par e-mail

Les outils qui écrivent n’apparaissent qu’avec le droit d’écrire. Avant send_message, request_client_action, create_prospect, add_phase ou add_step, l’agent doit te demander ton accord. Ce sont les mêmes outils que l’assistant de Portal, qui, lui, attend toujours ton clic. L’agent ne peut ni signer, ni payer, ni émettre une facture, ni supprimer quoi que ce soit.

Où vont tes données

Ce que lit l’agent part chez le fournisseur de ton agent (Anthropic pour Claude, par exemple), selon ses propres conditions. Ce choix est le tien. L’assistant de Portal reste en Suisse et dans l’Union européenne.

Si ça ne marche pas

• 401 : la connexion a expiré, ou la clé est absente, mal copiée, expirée ou révoquée. Reconnecte-toi, ou crée une autre clé.
• 403 « Ton accès à cet espace n’est pas confirmé » : ouvre Portal une fois dans ton navigateur avec ce compte, puis réessaie.
• 403 insufficient_scope : la clé ou la connexion est valable, mais elle n’a pas la portée demandée (portal:read ou portal:write). L’en-tête WWW-Authenticate nomme la portée qui manque. Reconnecte l’agent en lecture et écriture, ou crée une clé avec l’accès voulu.
• Aucun outil qui écrit : la clé ou la connexion est en lecture seule.
• « Trop d’appels » : l’agent a dépassé 60 appels à la suite, puis 120 par minute. Attends quelques secondes.

Pour un développeur

• Outils et schémas : https://app.hgdc.ch/portal/.well-known/mcp/server-card.json
• Point d’accès décrit en OpenAPI 3.1 : https://app.hgdc.ch/portal/openapi.json
• Document de ressource protégée (RFC 9728) : https://app.hgdc.ch/.well-known/oauth-protected-resource/portal/mcp