# Brancher Claude Code

PalmaPlan sert son serveur MCP par HTTP, avec OAuth 2.1 complet — Claude Code s'y branche
en une commande, sans jeton préparé à l'avance :

```bash
claude mcp add --transport http palmaplan <adresse>/mcp
```

Remplacez `<adresse>` par celle de votre instance (par exemple `http://127.0.0.1:4785` en
local, ou l'adresse publique d'une instance auto-hébergée).

Ce qui suit est décrit **pas à pas depuis un essai réel** : Claude Code réel, contre un
serveur PalmaPlan réel, le 21/09/2026 (journal du sprint 14, lot L0a). Ce n'est pas une
description théorique du protocole — c'est ce qui s'est passé, avec les deux réserves
trouvées à cette occasion.

## Ce qui se passe, dans l'ordre

1. **Claude Code s'enregistre tout seul.** Sans jeton fourni, le client détecte qu'il lui
   en faut un et s'enregistre auprès du serveur d'autorisation (`POST /oauth/register`,
   RFC 7591) — c'est l'**enregistrement dynamique** : rien à créer à la main côté
   PalmaPlan, chaque client (Claude Code, Claude Desktop, un autre agent) obtient son
   propre `client_id`.
2. **Votre navigateur s'ouvre** sur `GET /oauth/authorize`, avec PKCE (S256, obligatoire)
   et la ressource visée (`<adresse>/mcp`). Si vous n'avez pas de session ouverte dans ce
   navigateur, PalmaPlan vous mène d'abord à la page de connexion (`/login?next=…`) —
   connectez-vous, ou prenez possession de l'instance si c'est sa toute première fois
   (`/setup`) ; l'autorisation reprend ensuite exactement où elle en était.
3. **La page « Autoriser ? »** — le consentement. Elle nomme le client (« Claude Code »),
   qui vous êtes, et les portées demandées (lecture, écriture, ou les deux). **Refuser**
   renvoie Claude Code avec `access_denied` : rien n'est créé, aucun jeton n'existe.
   **Autoriser** émet un code à usage unique (dix minutes), que le navigateur redirige
   vers le port local que Claude Code écoute.
4. **Claude Code échange ce code contre un jeton** (`POST /oauth/token`, PKCE vérifié).
   Le jeton reçu est un **jeton nommé comme un autre** — « MCP · Claude Code » —, de
   trente jours, qui se rafraîchit tout seul pendant quatre-vingt-dix (un rafraîchissement
   à usage unique, à chaque fois une paire neuve). Il apparaît aussitôt dans
   *Réglages › Connexions et agents › Applications connectées*, révocable là exactement comme un jeton créé à la main ; ce que
   ce client écrit est attribué à *Claude (vous)*.
5. **Claude Code confirme** : « Authentication successful. Connected to
   `<nom-du-client>`. » — la session `/mcp` est vivante, la conversation peut appeler les
   98 tools du modèle (Claude Code n'affiche pas les vues MCP Apps : les trois tools
   réservés à la vue ne lui sont pas listés — voir [La vue embarquée](vue-embarquee.md)).

## Avec un jeton déjà créé

Si un jeton nommé existe déjà (créé depuis *Réglages › Connexions et agents › Accès avancés*, ou par une autre
session), Claude Code peut le prendre directement plutôt que de rejouer l'OAuth :

```bash
claude mcp add --transport http --header "Authorization: Bearer pp_…" palmaplan <adresse>/mcp
```

C'est le chemin que le stdio emploie par nécessité ([Claude Desktop](claude-desktop.md)) ;
en HTTP il reste facultatif, un raccourci pour qui préfère créer le jeton à la main plutôt
que d'ouvrir un navigateur.

## Quand ça coince

- **Le serveur répond 401 sans jamais ouvrir de navigateur** : `POST /mcp` sans Bearer
  répond `401` avec `WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource"`
  — c'est attendu, c'est ce qui déclenche la découverte OAuth. Si le navigateur ne s'ouvre
  toujours pas, vérifiez que Claude Code tourne dans un environnement qui peut lancer un
  navigateur (pas une session purement distante sans affichage).
- **`redirect_uri` refusée** : PalmaPlan n'accepte que `https`, ou `http` vers la boucle
  locale (`localhost`, `127.0.0.1`, `[::1]`) — exactement ce que Claude Code utilise pour
  son port de rappel. Si l'erreur apparaît quand même, l'adresse annoncée dans `<adresse>`
  ne correspond probablement pas à `PALMAPLAN_PUBLIC_URL` telle que le serveur la connaît.
- **Le jeton ne fonctionne plus** : un jeton révoqué depuis *Réglages › Connexions et agents › Applications connectées* ferme sa
  session `/mcp` sur-le-champ (pas seulement au prochain appel) ; `claude mcp remove
  palmaplan` puis un nouvel `add` recrée la relation depuis le début.
- **Deux entrées apparaissent dans les clients enregistrés** : l'enregistrement dynamique
  est ouvert, et un aller-retour de plus (une reprise, un essai annulé) peut créer un
  second `client_id` — sans conséquence, la purge horaire s'en charge ; ce n'est pas un
  jeton en double.

## Ce que l'essai réel a trouvé (et qui a changé depuis)

Deux réserves notées le 21/09/2026 :

1. **Le modèle qui appelle les tools par cette session précise** n'a pas été rejoué à
   cette occasion (la machine de l'essai n'avait pas de session Claude ouverte) — la
   mécanique OAuth et la session `/mcp` elle-même, si. Ce point-là est couvert par ailleurs
   par la recette du sprint 13 (un vrai appel du SDK).
2. **Deux sondes RFC 8414 supplémentaires** — `/.well-known/oauth-authorization-server/mcp`
   et `/.well-known/openid-configuration/mcp`, les variantes « à suffixe de chemin » que
   Claude Code interroge avant de se replier sur la racine — recevaient un `404` lors de
   cet essai. **C'est corrigé depuis** : le serveur sert aujourd'hui le même document sur
   les trois adresses (racine et les deux variantes suffixées), deux 404 de moins dans le
   parcours réel.

La troisième observation de l'essai (deux lignes créées dans les clients enregistrés) n'est
pas un défaut : c'est le bruit normal d'un enregistrement dynamique ouvert, purgé toutes
les heures.