Comment un connecteur personnalisé Claude trouve-t-il le serveur OAuth d'osFoundry, et pourquoi l'accès est-il vérifié à chaque appel ?

BBT — Fri, 06 Nov 2026 10:39:16 +0000

Voici ce que reçoit un client MCP distant quand il appelle un outil d'osFoundry sans jeton. La requête a été envoyée avec curl depuis un Mac à Tokyo le 2026-11-06 :

$ curl -s -D - -X POST https://api.osfoundry.io/api/v1/external-mcp \
    -H 'content-type: application/json' \
    -H 'accept: application/json, text/event-stream' \
    -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
         "params":{"name":"list_project_resources","arguments":{}}}'

HTTP/2 401
www-authenticate: Bearer resource_metadata="https://api.osfoundry.io/.well-known/oauth-protected-resource/api/v1/external-mcp", error="invalid_token", error_description="Connect osFoundry to continue"

{"jsonrpc":"2.0","id":3,"result":{"isError":true,
  "content":[{"type":"text","text":"Authentication required"}],
  "_meta":{"mcp/www_authenticate":["Bearer resource_metadata=\"https://api.osfoundry.io/.well-known/oauth-protected-resource/api/v1/external-mcp\", ..."]}}}

Cet unique en-tête suffit au connecteur personnalisé de Claude, ou à la connexion MCP du mode développeur de ChatGPT, pour trouver la page de connexion. L'utilisateur ne fait que coller l'URL. Tout ce qui suit vient de requêtes non authentifiées vers l'endpoint en production, plus une petite reconstruction en Python, exécutée en local, qui mesure ce qu'un curl ne peut pas montrer : ce qui arrive à l'accès après la connexion.

Que voit le client avant d'avoir un jeton ?

Trois appels, trois réponses différentes :

Requête	Statut	Ce qui revient
`initialize`	200	protocole `2025-06-18`, serveur `osfoundry 0.1.0`, plus des instructions
`tools/list`	200	59 outils, 45,368 octets
`tools/call`	401	`WWW-Authenticate` qui pointe vers les métadonnées de la ressource
`GET` sur l'endpoint	405	pas de flux SSE en GET

Le handshake et le catalogue d'outils sont publics. Seul l'appel d'un outil exige un jeton. Le host peut donc montrer à l'utilisateur quels outils existent avant que quiconque se connecte. Rien dans le catalogue n'est une donnée utilisateur, et la chaîne instructions de initialize est générique :

Use list_granted_resources first. Every Note edit must use the exact tab ID.
Local-only data is unavailable to cloud clients.

Chaque outil de tools/list déclare le scope OAuth dont il a besoin et s'il fait seulement de la lecture :

{"name": "edit_record_item",
 "annotations": {"readOnlyHint": false, "destructiveHint": true, "openWorldHint": false},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}

Sur les 59 outils : 30 demandent osfoundry:read et sont marqués readOnlyHint: true, 26 demandent osfoundry:write, et 3 demandent osfoundry:run (request_session_run, run_graph_session, cancel_graph_run). Un host peut s'appuyer sur readOnlyHint pour décider quels appels nécessitent une demande de confirmation.

Où le 401 l'envoie-t-il ?

resource_metadata suit la RFC 9728 (OAuth Protected Resource Metadata). Le suffixe well-known se place juste après l'hôte, suivi du chemin de la ressource. Il ne s'ajoute pas à la fin de l'URL de la ressource :

GET /.well-known/oauth-protected-resource/api/v1/external-mcp   200
GET /.well-known/oauth-protected-resource                       200 (same document)
GET /api/v1/external-mcp/.well-known/oauth-protected-resource   404

{"resource": "https://api.osfoundry.io/api/v1/external-mcp",
 "authorization_servers": ["https://api.osfoundry.io"],
 "scopes_supported": ["osfoundry:read", "osfoundry:write", "osfoundry:run", "osfoundry:models"]}

Si vous écrivez un client à la main, ce 404 sera votre première erreur. Lisez l'URL dans l'en-tête au lieu de la construire vous-même.

Que dit le serveur d'autorisation de lui-même ?

/.well-known/oauth-authorization-server (RFC 8414) :

{"issuer": "https://api.osfoundry.io",
 "authorization_endpoint": "https://api.osfoundry.io/api/v1/external-oauth/authorize",
 "token_endpoint": "https://api.osfoundry.io/api/v1/external-oauth/token",
 "registration_endpoint": "https://api.osfoundry.io/api/v1/external-oauth/register",
 "grant_types_supported": ["authorization_code", "refresh_token"],
 "token_endpoint_auth_methods_supported": ["none"],
 "code_challenge_methods_supported": ["S256"],
 "authorization_response_iss_parameter_supported": true}

Lisez-le comme une chaîne de décisions. Il y a un registration_endpoint, donc le host peut s'enregistrer tout seul (enregistrement dynamique de client) et l'utilisateur ne manipule jamais de client ID. L'authentification au token endpoint est none, donc le host est un client public sans client secret, et c'est PKCE en S256 qui lie le code au client qui l'a demandé. iss dans la réponse d'autorisation évite les confusions quand un host parle à plusieurs serveurs d'autorisation.

L'étape authorize envoie le navigateur sur la page de consentement d'osFoundry, https://osfoundry.io/external-assistant-authorize. L'utilisateur y choisit exactement un workspace et coche "I approve connecting this assistant to …" (j'autorise la connexion de cet assistant à …). L'approbation désigne un workspace et rien d'autre. Une nouvelle connexion n'a aucun projet. Le propriétaire les ajoute ensuite dans l'app (key icon → Connected → Add to project).

Pourquoi le scope ne suffit-il pas ?

Un scope est figé au moment où le jeton est émis. osfoundry:write dit que la connexion peut effectuer des actions d'écriture. Il ne dit pas quelle Note, et il ne peut pas savoir que la Note a été déplacée dans un autre projet il y a dix minutes. Les notes de conception d'osFoundry listent ce qui est relu à chaque appel : statut de la connexion, workspace, appartenance au projet, projet actuel et ACL de la ressource, appartenance au canal ou rôle dans la session, l'outil et le scope OAuth. La personne qui a approuvé la connexion doit aussi avoir encore les droits d'édition sur l'élément. Un retrait ou une réaffectation "prend effet immédiatement".

L'alternative consiste à mettre la liste des projets dans le jeton, ou dans un cache indexé par le jeton, et à lui faire confiance jusqu'à expiration. C'est moins coûteux à écrire. La reconstruction ci-dessous implémente les deux pour pouvoir mesurer la différence de comportement.

La reconstruction

Aucun binaire Claude n'intervient. client.py joue le host et server.py joue le serveur MCP. Les deux n'utilisent que la bibliothèque standard, environ 280 lignes à eux deux, et ont tourné sous Python 3.9.6 sur un Apple M1. Le serveur implémente initialize, tools/list et tools/call en JSON-RPC sur HTTP simple, les deux documents well-known, /authorize (la page de consentement est approuvée automatiquement pour un workspace) et /token avec PKCE S256. Quelques routes /admin/* remplacent les clics du propriétaire dans l'onglet Connected.

La vérification exécutée avant chaque outil :

def access(token_info, tool, note_id):
    if TOOL_SCOPE[tool] not in token_info["scopes"]:
        return "insufficient_scope"
    if CHECK == "token_only":                     # design B: trust issue-time state
        ok = note_id is None or NOTES[note_id]["project"] in token_info["projects_at_issue"]
        return None if ok else "not_in_project"
    conn = CONNECTIONS.get(token_info["connection"])
    if not conn or conn["status"] != "active":
        return "connection_revoked"
    if note_id is None:
        return None
    note = NOTES.get(note_id)
    if not note or note["workspace"] != conn["workspace"]:
        return "not_found"
    if (token_info["connection"], note["project"]) not in PROJECT_MEMBERS:
        return "not_in_project"
    return None

Le client démarre sans jeton. Il appelle un outil, reçoit le 401, extrait resource_metadata de WWW-Authenticate, récupère les deux documents de métadonnées, enchaîne authorize et token avec un nouveau verifier PKCE, puis déroule le scénario :

$ CHECK=per_call python3 server.py &  python3 client.py 8767
discovery: first call -> 401, metadata /.well-known/oauth-protected-resource/mcp, 5 round trips, 11.3 ms
1 fresh connection, no project yet           200 OK   []
2 after owner adds project A                 200 OK   ["note-a1"]
3 read note in A                             200 OK   "Q3 launch checklist"
4 read note in B (never added)               200 DENY not_in_project
5 write with a read-only token               403 DENY insufficient_scope
6 write with read+write token                200 OK   "saved"
7 same read after note moved to B            200 DENY not_in_project
8 same read after owner removes project A    200 DENY not_in_project
9 same read after revoke                     200 DENY connection_revoked

Le même client face à CHECK=token_only. Ici, le jeton porte la liste des projets de son dernier refresh :

7 same read after note moved to B            200 DENY not_in_project
8 same read after owner removes project A    200 OK   "Q3 launch checklist v2"
9 same read after revoke                     200 OK   "Q3 launch checklist v2"

Les étapes 1–7 sont identiques. L'étape 7 reste refusée dans la conception « jeton seul », parce que le projet de la note est consulté en direct. La conception « jeton seul » ne devient périmée que sur les faits stockés dans le jeton. Les étapes 8 et 9 sont celles qui comptent pour le propriétaire : il a retiré le projet, puis révoqué la connexion, et le chat a continué à lire. Dans la conception « jeton seul », cela dure jusqu'à l'expiration du jeton, soit expires_in: 3600 dans cette reconstruction.

Les refus se répartissent sur deux couches. Un scope manquant est un échec au niveau du protocole : 403 avec error="insufficient_scope" et le scope requis dans WWW-Authenticate, pour qu'un host puisse en demander davantage. Tout ce qui dépend de l'élément concerné est un résultat d'outil normal avec isError: true. Une nouvelle autorisation n'y changerait rien, donc inutile de dire au host de réessayer.

Combien coûte la vérification à chaque appel ?

Mesuré avec time.perf_counter_ns() autour de access() dans le serveur, 1,000 appels par exécution (500 autorisés, 500 refusés), sur un Mac qui faisait aussi tourner d'autres tâches :

	access() médiane	access() p99	appel d'outil en loopback, médiane
vérification à chaque appel, 6 exécutions	1.3–1.6 µs	6.1–7.0 µs	0.43–0.78 ms
jeton seul, 3 exécutions	0.7–1.6 µs	3.5–7.7 µs	0.35–1.36 ms (2 exécutions)

En mémoire, la revérification se noie dans le bruit d'un appel HTTP en loopback. Un vrai serveur fait des requêtes en base de données au lieu de tests d'appartenance à un ensemble, donc son coût est plus élevé. Cette reconstruction ne peut pas le mesurer, donc aucun chiffre n'est donné. Pour l'ordre de grandeur, le trajet réseau vers l'endpoint en production depuis Tokyo est d'environ 500 ms à 800 ms par requête avec urllib et une nouvelle connexion TLS à chaque fois (n=10 pour chacun : initialize médiane 790 ms, tools/list 816 ms, le tools/call en 401 565 ms, chaque document de métadonnées environ 520–530 ms). Ce n'est pas dans la vérification d'accès qu'un connecteur passe son temps.

La découverte elle-même représentait 5 allers-retours HTTP en local : 401, métadonnées de la ressource, métadonnées du serveur, authorize, token. Cela a pris 7.5–13.4 ms sur sept exécutions, et 34 ms une fois avec le Mac chargé. Face au serveur en production, les trois trajets GET/POST faisables sans identifiants totalisent environ 1.6 s à froid. L'étape authorize attend de toute façon un humain.

Pourquoi Claude peut-il appeler osFoundry, alors qu'osFoundry ne peut pas ouvrir vos chats Claude ?

Dans ce montage, c'est le host qui appelle. Il ouvre la connexion, liste les outils et décide quand en appeler un. Le serveur répond. Rien dans ce montage ne donne au serveur une prise sur les conversations du host. Le plan d'osFoundry l'indique dans son tableau des capacités : ouvrir ou énumérer des chats personnels ChatGPT/Claude arbitraires, c'est "No", avec "No general host API is provided for this".

Cela façonne les outils. Avec link_current_chat, c'est le chat lui-même qui crée un lien depuis l'intérieur. Son libellé est déclaré par le chat, et osFoundry s'en sert pour le routage, pas comme identité. Le travail assigné à un chat Claude lié attend que l'utilisateur ouvre ce chat et lui demande de vérifier. ChatGPT dispose de MCP Events pour les chats abonnés, et le plan d'osFoundry traite cela comme propre à ce host.

Le côté serveur détient toutes les décisions sur les données, parce que c'est le seul à connaître l'état actuel d'un projet. Le côté host détient toutes les décisions sur le moment d'agir et sur l'opportunité de demander à l'utilisateur. La vérification à chaque appel est ce qui permet au serveur de rester correct quand les deux côtés se désynchronisent.

Si vous câblez cela vous-même

Mettez resource_metadata dans le WWW-Authenticate du 401 et servez la RFC 9728 à /.well-known/oauth-protected-resource/<resource path>. Un client qui construit l'URL à la main peut se tromper. L'en-tête évite ça à tous les clients.
Décidez de ce qui est public avant la connexion. osFoundry expose initialize et tools/list et protège tools/call. Si les descriptions de vos outils laissent fuiter quoi que ce soit sur les tenants, protégez aussi tools/list.
Déclarez un scope et readOnlyHint par outil. Les hosts peuvent en tirer leurs demandes de confirmation, et un 403 insufficient_scope donne au host quelque chose de concret à redemander.
Gardez le jeton petit : qui, quelle connexion, quels scopes. Relisez à chaque appel le workspace, l'appartenance au projet, le projet de la ressource et le rôle actuel de la personne qui a approuvé, pour que la révocation et « déplacer vers un autre projet » s'appliquent dès l'appel suivant.
Renvoyez les refus liés aux ressources comme résultats d'outil, pas en 401/403. Un autre jeton ne réglera pas « cette Note est dans le projet B ».
Faites porter aux écritures un expected_version et une clé d'idempotence. Les hosts réessaient, et les modèles relancent des appels.

Le côté MCP de la spécification se trouve sur la page d'autorisation MCP. La définition courte d'osFoundry se trouve dans son entrée de glossaire sur MCP.

DEV Community: BBT Français