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 :

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).

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 :

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) ; 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.