# 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](#avec-une-cl%C3%A9-dapi).

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

```bash
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` :

```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` :

```bash
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](/portal/docs/reference/api/). 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](/portal/docs/guides/assistant/), 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](/portal/docs/guides/assistant/) 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`