DEV Community: BBT

Claude 自訂連接器如何找到 osFoundry 的 OAuth 伺服器，又為什麼每次呼叫都要檢查存取權限？

BBT — Fri, 06 Nov 2026 10:58:52 +0000

遠端 MCP client 在沒有 token 的情況下呼叫 osFoundry 的工具時，會拿到下面這個回應。這個請求是 2026-11-06 在東京用一台 Mac 透過 curl 送出的：

$ 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\", ..."]}}}

光靠這一個 header，Claude 的自訂連接器（custom connector），或 ChatGPT 開發者模式的 MCP 連線，就能找到登入頁面。使用者只需要貼上網址。以下內容全部來自對正式環境 endpoint 的未驗證請求，再加上一個在本機執行的小型 Python 重建版本，用來量測 curl 看不到的部分：登入之後，存取權限會發生什麼事。

拿到 token 之前，client 看得到什麼？

三個呼叫，三種不同的回應：

請求	狀態碼	回傳內容
`initialize`	200	協定 `2025-06-18`、伺服器 `osfoundry 0.1.0`，外加 instructions
`tools/list`	200	59 個工具，45,368 bytes
`tools/call`	401	`WWW-Authenticate` 指向 resource metadata
對 endpoint 發 `GET`	405	GET 不提供 SSE stream

握手和工具目錄是公開的，只有呼叫工具需要 token。這樣 host 可以在任何人登入之前，就先讓使用者看到有哪些工具。目錄裡沒有任何使用者資料，initialize 裡的 instructions 字串也是通用的：

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

tools/list 裡的每個工具都會宣告自己需要的 OAuth scope，以及是否只做讀取：

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

59 個工具中：30 個需要 osfoundry:read 並標記為 readOnlyHint: true，26 個需要 osfoundry:write，3 個需要 osfoundry:run（request_session_run、run_graph_session、cancel_graph_run）。host 可以根據 readOnlyHint 決定哪些呼叫要跳出確認提示。

401 把它導向哪裡？

resource_metadata 遵循 RFC 9728（OAuth Protected Resource Metadata）。well-known 後綴緊接在 host 後面，再把 resource 路徑接在後綴之後，而不是接在 resource URL 的尾端：

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"]}

如果你自己手刻 client，最先踩到的坑就是這個 404。直接從 header 讀 URL，不要自己組。

授權伺服器怎麼描述自己？

/.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}

把它當成一連串的設計決策來讀。有 registration_endpoint，所以 host 可以自行註冊（動態 client 註冊），使用者完全不用碰 client ID。token 驗證方式是 none，所以 host 是沒有 client secret 的 public client，負責把授權碼綁定到發出請求的 client 的，是 S256 的 PKCE。授權回應裡的 iss，則是在 host 同時對接多個授權伺服器時防止搞混。

authorize 步驟會把瀏覽器導到 osFoundry 的同意頁面 https://osfoundry.io/external-assistant-authorize。使用者在那裡只能選一個 workspace，並勾選 "I approve connecting this assistant to …"（我同意將此助理連接到 …）。這個核准只指定一個 workspace，除此之外什麼都沒有。新建立的連線沒有任何專案，owner 之後再到 app 裡加入（key icon → Connected → Add to project）。

為什麼光有 scope 不夠？

scope 在 token 簽發的那一刻就固定了。osfoundry:write 表示這個連線可以執行寫入類的操作，但它沒有說是哪一則 Note，也不可能知道那則 Note 十分鐘前被移到了別的專案。osFoundry 的設計筆記列出了每次呼叫都會重新讀取的項目：連線狀態、workspace、專案成員資格、resource 目前所屬的專案與 ACL、頻道成員資格或 session 角色、工具本身，以及 OAuth scope。核准連線的那個人，也必須仍然對該項目擁有編輯權限。移除或重新指派會「立即生效」。

另一種做法是把專案清單放進 token，或放進以 token 為 key 的快取，在到期前一律信任它。這樣寫起來比較省事。下面的重建版本兩種都實作了，好量測行為上的差異。

重建版本

整個過程沒有用到 Claude 的執行檔。client.py 扮演 host，server.py 扮演 MCP 伺服器。兩者都只用標準函式庫，加起來大約 280 行，在 Apple M1 上以 Python 3.9.6 執行。伺服器在純 HTTP 的 JSON-RPC 上實作了 initialize、tools/list 和 tools/call，加上兩份 well-known 文件、/authorize（同意頁面對單一 workspace 自動核准），以及支援 S256 PKCE 的 /token。另外用幾個 /admin/* 路由代替 owner 在 Connected 分頁裡的點擊操作。

每個工具執行前都會跑的檢查：

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

client 一開始沒有 token。它呼叫工具、收到 401、從 WWW-Authenticate 解析出 resource_metadata、抓取兩份 metadata 文件、用新的 PKCE verifier 跑完 authorize 和 token，接著依序執行情境：

$ 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

同一個 client 改對 CHECK=token_only 執行。這時 token 裡帶的是上次 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"

步驟 1–7 完全相同。在只看 token 的設計下，步驟 7 依然被拒絕，因為 note 所屬的專案是即時查詢的。只看 token 的設計，只有在存放於 token 裡的資訊上才會過時。步驟 8 和 9 才是 owner 在意的：他們移除了專案，接著撤銷了連線，聊天卻還是讀得到。在只看 token 的設計下，這種狀態會一直持續到 token 過期，在這個重建版本中是 expires_in: 3600。

拒絕分成兩層。缺少 scope 屬於協定層級的失敗：回 403，帶上 error="insufficient_scope"，並在 WWW-Authenticate 裡附上所需的 scope，讓 host 可以要求更多權限。凡是跟「涉及哪個項目」有關的，都是一般的工具結果，帶 isError: true。重新授權也解決不了，所以沒必要叫 host 去重試。

每次呼叫都檢查，成本是多少？

在伺服器內用 time.perf_counter_ns() 包住 access() 量測，每輪 1,000 次呼叫（500 次允許、500 次拒絕），量測時這台 Mac 同時也在跑其他工作：

	access() 中位數	access() p99	loopback 工具呼叫中位數
每次呼叫檢查，6 輪	1.3–1.6 µs	6.1–7.0 µs	0.43–0.78 ms
只看 token，3 輪	0.7–1.6 µs	3.5–7.7 µs	0.35–1.36 ms（2 輪）

在記憶體裡，重新檢查的成本完全淹沒在 loopback HTTP 呼叫的雜訊中。真正的伺服器做的是資料庫查詢，而不是 set 成員判斷，成本會更高。這個重建版本量不到那部分，所以不提供數字。拿來對照的話，從東京到正式環境 endpoint 的網路來回，用 urllib 且每次都建立新的 TLS 連線，每個請求大約 500 ms 到 800 ms（各 n=10：initialize 中位數 790 ms、tools/list 816 ms、回 401 的 tools/call 565 ms、每份 metadata 文件約 520–530 ms）。連接器的時間不是花在存取檢查上。

探索流程本身在本機是 5 次 HTTP 來回：401、resource metadata、server metadata、authorize、token。七輪花了 7.5–13.4 ms，Mac 忙碌時有一次是 34 ms。對正式伺服器而言，不需要憑證就能打的三段 GET/POST，從冷啟動算起合計大約 1.6 s。authorize 那段反正本來就要等人操作。

為什麼 Claude 能呼叫 osFoundry，osFoundry 卻打不開你的 Claude 聊天？

在這個架構裡，發起呼叫的是 host。它建立連線、列出工具，並決定什麼時候呼叫哪個工具。伺服器只負責回應。這個架構裡沒有任何東西讓伺服器能碰到 host 的對話。osFoundry 的規劃在能力表中寫得很清楚：開啟或列舉任意個人 ChatGPT/Claude 聊天是 "No"，並註明 "No general host API is provided for this"。

這決定了工具的設計。link_current_chat 是由聊天本身從內部建立連結。它的標籤由聊天自行回報，osFoundry 只拿來做路由，不當成身分。指派給已連結 Claude 聊天的工作，會一直等到使用者打開那個聊天、請它去確認為止。ChatGPT 對已訂閱的聊天提供 MCP Events，osFoundry 的規劃把這視為 host 專屬的功能。

所有跟資料有關的決定都在伺服器端，因為只有它知道專案目前的狀態。所有關於何時行動、要不要詢問使用者的決定，都在 host 端。每次呼叫都檢查，正是讓伺服器在兩邊狀態不同步時仍能保持正確的關鍵。

如果你要自己串接

在 401 的 WWW-Authenticate 裡放 resource_metadata，並在 /.well-known/oauth-protected-resource/<resource path> 提供 RFC 9728 文件。自己手動組 URL 的 client 可能會組錯，有這個 header，每個 client 都不用冒這個險。
先決定登入前哪些東西公開。osFoundry 公開 initialize 和 tools/list，保護 tools/call。如果你的工具說明會洩漏任何跟 tenant 有關的資訊，tools/list 也要保護起來。
每個工具都宣告 scope 和 readOnlyHint。host 可以據此做出確認提示，而 403 insufficient_scope 則讓 host 有明確的東西可以重新要求。
token 保持精簡：誰、哪個連線、哪些 scope。workspace、專案成員資格、resource 所屬專案，以及核准者目前的角色，每次呼叫都重新讀取，這樣撤銷和「移到其他專案」在下一次呼叫就會生效。
resource 層級的拒絕要用工具結果回傳，不要用 401/403。換一個 token 也解決不了「這則 Note 在專案 B」。
寫入操作要帶 expected_version 和 idempotency key。host 會重試，模型也會重送呼叫。

規格中 MCP 的部分在 MCP 授權頁面。osFoundry 自己的簡短定義在它的 MCP 詞彙條目。

Claude 커스텀 커넥터는 osFoundry의 OAuth를 어떻게 찾고, 왜 권한을 매번 확인할까

BBT — Fri, 06 Nov 2026 10:52:54 +0000

토큰 없이 osFoundry의 원격 MCP 서버에 tool을 호출하면 이런 응답이 온다. 2026-11-06에 도쿄에 있는 Mac에서 curl로 직접 찔러 본 결과다.

$ 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\", ..."]}}}

Claude 커스텀 커넥터든 ChatGPT 개발자 모드의 MCP 연결이든, 로그인 화면까지 가는 단서는 이 헤더 한 줄이다. 사용자가 붙여 넣는 건 URL 하나뿐이다. 앞부분은 실서버에 인증 없이 보낸 요청만으로 정리했다. 뒷부분에서는 curl로는 안 보이는 부분, 즉 로그인한 뒤 권한이 어떻게 다뤄지는지를 Python으로 작게 다시 만들어서 측정했다.

토큰이 없을 때 클라이언트에 보이는 것

메서드마다 응답이 다르다.

요청	상태	내용
`initialize`	200	프로토콜 `2025-06-18`, 서버 `osfoundry 0.1.0`, instructions
`tools/list`	200	tool 59개, 45,368바이트
`tools/call`	401	리소스 메타데이터를 가리키는 `WWW-Authenticate`
엔드포인트에 `GET`	405	GET으로 여는 SSE 스트림은 없다

핸드셰이크와 tool 목록은 공개돼 있다. 토큰이 필요한 건 tool 실행뿐이다. 덕분에 호스트는 로그인 전에도 어떤 tool이 있는지 사용자에게 보여 줄 수 있다. 목록에 사용자 데이터는 없고, initialize의 instructions도 일반적인 안내문이다.

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

tools/list에 나오는 tool마다 필요한 OAuth scope와 읽기 전용 여부를 스스로 선언한다.

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

59개를 세 보면 osfoundry:read 30개(전부 readOnlyHint: true), osfoundry:write 26개, osfoundry:run 3개(request_session_run, run_graph_session, cancel_graph_run)다. 호스트는 readOnlyHint를 보고 어떤 호출에서 승인을 받을지 정할 수 있다.

401은 어디를 가리키나

resource_metadata는 RFC 9728(OAuth Protected Resource Metadata) 형식이다. well-known은 호스트 바로 아래에 두고, 그 뒤에 리소스 경로를 이어 붙인다. 리소스 URL 끝에 붙이는 게 아니다.

GET /.well-known/oauth-protected-resource/api/v1/external-mcp   200
GET /.well-known/oauth-protected-resource                       200 (같은 문서)
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"]}

클라이언트를 직접 짜면 제일 먼저 이 404에서 삽질하게 된다. URL은 조립하지 말고 헤더에 적힌 걸 그대로 쓰면 된다.

인가 서버 메타데이터

/.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}

필드 하나하나가 설계 결정이다.

registration_endpoint가 있다. 호스트가 동적 클라이언트 등록(DCR)으로 스스로 등록하니까 사용자가 client ID를 만질 일이 없다.
토큰 엔드포인트 인증이 none이다. 호스트는 시크릿이 없는 public client고, 인가 코드를 요청한 쪽과 묶어 주는 건 PKCE(S256)다.
iss 파라미터를 지원한다. 인가 서버 여러 개와 붙는 호스트에서 서로 헷갈리지 않게 막아 준다.

authorize 단계에서 브라우저는 osFoundry 동의 화면 https://osfoundry.io/external-assistant-authorize로 넘어간다. 여기서 사용자는 워크스페이스를 딱 하나 고르고 "I approve connecting this assistant to …"에 체크한다. 이 승인으로 정해지는 건 워크스페이스뿐이다. 새 연결에는 프로젝트가 하나도 없다. 프로젝트는 나중에 앱(열쇠 아이콘 → Connected → Add to project)에서 소유자가 붙인다.

scope만으로는 부족한 이유

scope는 토큰을 발급할 때 정해진다. osfoundry:write는 쓰기 계열 동작을 해도 된다는 뜻일 뿐이다. 어느 노트인지는 모르고, 그 노트가 10분 전에 다른 프로젝트로 옮겨졌다는 것도 모른다. osFoundry 설계 문서에는 호출할 때마다 다시 읽는 항목이 정해져 있다. 연결 상태, 워크스페이스, 프로젝트 소속, 리소스가 지금 속한 프로젝트와 ACL, 채널 소속이나 세션 역할, tool, OAuth scope다. 연결을 승인한 사람이 지금도 그 항목의 편집 권한을 갖고 있어야 한다는 조건도 붙는다. 빼거나 옮긴 변경은 즉시 반영된다고 적혀 있다.

반대 방식도 있다. 프로젝트 목록을 토큰(또는 토큰을 키로 쓰는 캐시)에 넣어 두고 만료될 때까지 믿는 방식이다. 구현은 이쪽이 편하다. 동작이 얼마나 달라지는지 보려고 둘 다 만들어 봤다.

최소 구성으로 다시 만들기

Claude 바이너리는 쓰지 않았다. client.py가 호스트를, server.py가 MCP 서버를 흉내 낸다. 둘 다 표준 라이브러리만 썼고 합쳐서 약 280줄이다. Apple M1, Python 3.9.6에서 돌렸다. 서버가 구현한 건 다음과 같다.

일반 HTTP JSON-RPC 위의 initialize, tools/list, tools/call
well-known 메타데이터 두 개
동의 화면 대신 워크스페이스 하나로 자동 승인하는 /authorize
PKCE S256을 검증하는 /token

Connected 탭에서 소유자가 누르는 동작은 /admin/*로 대신했다.

tool 실행 전에 매번 거치는 체크는 이게 전부다.

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

클라이언트는 토큰 없이 출발한다. 먼저 tool을 호출해 401을 받고, WWW-Authenticate에서 resource_metadata를 꺼낸다. 메타데이터 두 개를 가져온 뒤 새 PKCE verifier로 authorize와 token을 통과하고, 시나리오를 차례로 돌린다.

$ 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

같은 클라이언트를 CHECK=token_only 서버에 붙이면 이렇게 나온다. 이쪽 토큰은 마지막으로 갱신할 때의 프로젝트 목록을 들고 있다.

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"

1~7은 똑같다. token_only에서도 7이 막히는 건 노트의 소속 프로젝트만은 그때그때 조회하기 때문이다. 낡는 건 토큰에 박아 둔 사실뿐이다. 차이는 8과 9에서 났고, 둘 다 소유자에게 중요한 동작이다. 프로젝트에서 빼고 연결까지 취소했는데 채팅은 계속 읽는다. 이 상태는 토큰이 만료될 때까지 이어지고, 이번 재구현에서는 expires_in: 3600이었다.

거부는 두 층으로 나눠서 돌려준다. scope가 모자라면 프로토콜 문제로 보고 403과 error="insufficient_scope"에 필요한 scope를 붙여 보낸다. 그러면 호스트가 권한을 더 요청할 수 있다. 어느 항목이냐에 걸린 거부는 isError: true가 붙은 평범한 tool 결과로 보낸다. 이건 재인가해도 해결되지 않으니 호스트에게 다시 해 보라고 할 이유가 없다.

매번 체크하는 비용

서버 안에서 access() 앞뒤를 time.perf_counter_ns()로 감싸 실행마다 1,000번(허용 500, 거부 500) 쟀다. 측정하는 동안 Mac에서는 다른 작업도 돌고 있었다.

	access() 중앙값	access() p99	루프백 tool 호출 중앙값
매번 체크 (6회 실행)	1.3–1.6 µs	6.1–7.0 µs	0.43–0.78 ms
token_only (3회 실행)	0.7–1.6 µs	3.5–7.7 µs	0.35–1.36 ms (2회분)

메모리 안에서 끝나는 구성에서는 매번 하는 재확인이 루프백 HTTP의 편차에 묻혔다. 실제 서버는 집합 조회 대신 DB를 보니까 더 무겁다. 다만 그 수치는 이 재구현으로는 잴 수 없어서 적지 않는다. 비교용으로 실서버를 보면, 도쿄에서 왕복 한 번에 약 500~800ms가 걸렸다. urllib으로 매번 TLS를 새로 맺고 각 10회 잰 값이고, 중앙값은 initialize 790ms, tools/list 816ms, 401이 나는 tools/call 565ms, 메타데이터 각 520~530ms였다. 커넥터의 시간을 잡아먹는 건 권한 체크가 아니다.

디스커버리는 로컬에서 5번 왕복했다(401, 리소스 메타데이터, 인가 서버 메타데이터, authorize, token). 7번은 7.5~13.4ms 안에 끝났고, Mac이 바빴던 한 번만 34ms였다. 실서버에 인증 없이 보낼 수 있는 세 구간을 더하면 콜드 스타트에서 약 1.6초다. authorize는 어차피 사람의 클릭을 기다리니까 여기서는 문제가 안 된다.

Claude는 호출하는데 osFoundry는 채팅을 못 여는 이유

이 구성에서 호출하는 쪽은 호스트다. 연결을 열고, tool 목록을 받고, 언제 호출할지 정하는 건 호스트고, 서버는 답만 한다. 서버가 호스트의 대화를 붙잡을 방법은 없다. osFoundry 계획 문서의 기능 표에도 개인 ChatGPT/Claude 채팅을 열거나 목록으로 보는 칸은 "No"이고, 이유는 "No general host API is provided for this"라고 적혀 있다.

tool 설계도 여기에 맞춰져 있다. link_current_chat은 채팅 안에서 그 채팅이 스스로 링크를 만들게 하는 tool이다. 라벨은 자기 신고고, osFoundry는 이걸 신원 확인이 아니라 라우팅용 메모로 쓴다. 링크된 Claude 채팅에 배정한 작업은 사용자가 그 채팅을 열고 확인해 달라고 할 때까지 기다린다. 구독한 채팅에 전달되는 MCP Events는 ChatGPT 쪽 기능이고, 계획 문서에서도 호스트별 기능으로 다룬다.

데이터에 관한 판단은 전부 서버가 한다. 프로젝트의 지금 상태를 아는 쪽이 서버뿐이기 때문이다. 언제 움직이고 사용자에게 물어볼지는 호스트가 정한다. 두 쪽의 인식이 어긋나도 매번 체크하면 서버의 판단은 계속 맞는 상태로 남는다.

직접 붙인다면 정해 둘 것

401의 WWW-Authenticate에 resource_metadata를 넣고, RFC 9728 메타데이터를 /.well-known/oauth-protected-resource/<리소스 경로>에서 내준다. URL을 직접 조립하는 클라이언트는 틀리기 쉬운데, 헤더가 있으면 어떤 클라이언트도 헤매지 않는다.
로그인 전에 뭘 공개할지 정한다. osFoundry는 initialize와 tools/list를 열어 두고 tools/call만 막았다. tool 설명에서 테넌트 정보가 새어 나간다면 tools/list도 막는다.
tool마다 scope와 readOnlyHint를 선언한다. 호스트는 이걸 보고 승인 절차를 넣을 수 있고, 403 insufficient_scope를 받으면 무엇을 더 요청해야 할지 안다.
토큰에는 누구인지, 어느 연결인지, 어떤 scope인지만 넣는다. 워크스페이스, 프로젝트 소속, 리소스의 소속 프로젝트, 승인한 사람의 현재 권한은 매번 다시 읽는다. 그래야 취소도, 다른 프로젝트로 옮기기도 다음 호출부터 바로 반영된다.
리소스 단위 거부는 401/403이 아니라 tool 결과로 돌려준다. "이 노트는 프로젝트 B에 있다"는 토큰을 바꿔도 그대로다.
쓰기에는 expected_version과 멱등 키를 필수로 받는다. 호스트는 재시도하고, 모델은 같은 호출을 다시 보낸다.

스펙의 MCP 쪽 내용은 MCP 인가 문서에 있다. osFoundry가 정리한 짧은 정의는 용어집의 MCP 항목에 있다.

Claude का custom connector osFoundry का OAuth server कैसे ढूंढता है, और हर call पर access क्यों check होता है?

BBT — Fri, 06 Nov 2026 10:52:06 +0000

जब कोई remote MCP client बिना token के osFoundry का कोई tool call करता है, तो उसे यह मिलता है। यह request 2026-11-06 को Tokyo में एक Mac से curl से भेजी गई थी:

$ 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\", ..."]}}}

Claude के custom connector को, या ChatGPT के developer mode वाले MCP connection को, sign-in page ढूंढने के लिए बस यही एक header काफ़ी है। User को सिर्फ़ URL paste करना होता है। नीचे जो कुछ भी है वह live endpoint पर बिना authentication वाली requests से लिया गया है, साथ में Python का एक छोटा rebuild है जो locally चलाया गया। यह rebuild वह हिस्सा मापता है जो curl नहीं दिखा सकता: sign-in के बाद access के साथ क्या होता है।

Token मिलने से पहले client को क्या दिखता है?

तीन calls, तीन अलग जवाब:

Request	Status	क्या वापस आता है
`initialize`	200	protocol `2025-06-18`, server `osfoundry 0.1.0`, साथ में instructions
`tools/list`	200	59 tools, 45,368 bytes
`tools/call`	401	`WWW-Authenticate`, जो resource metadata की ओर इशारा करता है
endpoint पर `GET`	405	GET पर कोई SSE stream नहीं

Handshake और tool catalogue public हैं। सिर्फ़ tool call करने के लिए token चाहिए। इससे host किसी के sign in करने से पहले ही user को दिखा सकता है कि कौन-कौन से tools मौजूद हैं। Catalogue में कोई user data नहीं है, और initialize में मौजूद instructions string generic है:

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

tools/list का हर tool बताता है कि उसे कौन-सा OAuth scope चाहिए और क्या वह सिर्फ़ read करता है:

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

59 tools में से: 30 को osfoundry:read चाहिए और वे readOnlyHint: true से marked हैं, 26 को osfoundry:write चाहिए, और 3 को osfoundry:run चाहिए (request_session_run, run_graph_session, cancel_graph_run)। Host readOnlyHint के आधार पर तय कर सकता है कि किन calls पर approval prompt दिखाना है।

401 उसे कहां भेजता है?

resource_metadata RFC 9728 (OAuth Protected Resource Metadata) को follow करता है। Well-known suffix host के ठीक बाद आता है, और resource path उसके पीछे जुड़ता है। इसे resource URL के आख़िर में नहीं जोड़ा जाता:

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"]}

अगर आप client हाथ से बना रहे हैं, तो सबसे पहली गलती आप यही 404 वाली करेंगे। URL ख़ुद बनाने की बजाय header से पढ़िए।

Authorization server अपने बारे में क्या बताता है?

/.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}

इसे फ़ैसलों की एक chain की तरह पढ़िए। इसमें registration_endpoint है, इसलिए host ख़ुद को register कर सकता है (dynamic client registration) और user को कभी client ID से जूझना नहीं पड़ता। Token auth none है, यानी host एक public client है जिसके पास client secret नहीं है, और S256 वाला PKCE ही code को उस client से बांधता है जिसने उसे मांगा था। Authorization response में iss उस गड़बड़ी से बचाता है जब कोई host कई authorization servers से बात कर रहा हो।

Authorize step browser को osFoundry के consent page https://osfoundry.io/external-assistant-authorize पर भेजता है। वहां user ठीक एक workspace चुनता है और "I approve connecting this assistant to …" (मैं इस assistant को … से जोड़ने की अनुमति देता हूं) पर tick करता है। Approval में सिर्फ़ एक workspace का नाम होता है, और कुछ नहीं। नए connection में कोई project नहीं होता। Owner उन्हें बाद में app में जोड़ता है (key icon → Connected → Add to project)।

सिर्फ़ scope काफ़ी क्यों नहीं है?

Scope उसी समय तय हो जाता है जब token mint होता है। osfoundry:write बताता है कि connection write वाले actions कर सकता है। यह नहीं बताता कि कौन-सा Note, और इसे यह पता भी नहीं हो सकता कि वह Note दस मिनट पहले किसी दूसरे project में चला गया। osFoundry के design notes में लिखा है कि हर call पर क्या दोबारा पढ़ा जाता है: connection status, workspace, project membership, resource का मौजूदा project और ACL, channel membership या session role, tool, और OAuth scope। जिस व्यक्ति ने connection approve किया था, उसके पास उस item पर अभी भी edit rights होने चाहिए। हटाना या reassign करना "तुरंत लागू होता है"।

दूसरा रास्ता यह है कि project list को token में डाल दिया जाए, या token को key बनाकर cache में रख दिया जाए, और expiry तक उस पर भरोसा किया जाए। यह लिखने में सस्ता है। नीचे वाला rebuild दोनों को implement करता है ताकि behaviour का फ़र्क़ मापा जा सके।

Rebuild

इसमें कोई Claude binary शामिल नहीं है। client.py host का रोल निभाता है और server.py MCP server का। दोनों सिर्फ़ standard library इस्तेमाल करते हैं, मिलाकर लगभग 280 lines, और Apple M1 पर Python 3.9.6 में चलाए गए। Server plain HTTP JSON-RPC पर initialize, tools/list और tools/call implement करता है, साथ में दोनों well-known documents, /authorize (consent page एक workspace के लिए अपने आप approve हो जाता है), और S256 PKCE के साथ /token। कुछ /admin/* routes Connected tab में owner के clicks की जगह लेते हैं।

हर tool से पहले चलने वाला check:

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

Client बिना token के शुरू होता है। वह एक tool call करता है, 401 लेता है, WWW-Authenticate से resource_metadata parse करता है, दोनों metadata documents fetch करता है, नए PKCE verifier के साथ authorize और token चलाता है, और फिर scenario से गुज़रता है:

$ 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

वही client CHECK=token_only के ख़िलाफ़। यहां token में उसके पिछले refresh के समय की project list होती है:

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"

Steps 1–7 एक जैसे हैं। Token-only design में भी step 7 deny होता है, क्योंकि note का project live lookup किया जाता है। Token-only design सिर्फ़ उन्हीं बातों पर पुराना पड़ता है जो token के अंदर रखी हैं। Owner के लिए असली मायने steps 8 और 9 के हैं: उन्होंने project हटाया, फिर connection revoke किया, और chat फिर भी पढ़ती रही। Token-only design में यह token expire होने तक चलता है, जो इस rebuild में expires_in: 3600 है।

Denials दो layers में बंटे हैं। Scope न होना protocol level की failure है: error="insufficient_scope" के साथ 403, और ज़रूरी scope WWW-Authenticate में, ताकि host ज़्यादा scope मांग सके। कौन-सा item शामिल है, उससे जुड़ी हर चीज़ एक सामान्य tool result है जिसमें isError: true होता है। दोबारा authorise करने से वह ठीक नहीं होगा, इसलिए host को retry करने को कहने का कोई मतलब नहीं।

हर call पर check की क़ीमत क्या है?

Server के अंदर access() के चारों ओर time.perf_counter_ns() से मापा गया, हर run में 1,000 calls (500 allowed, 500 denied), एक ऐसे Mac पर जिस पर दूसरे jobs भी चल रहे थे:

	access() median	access() p99	loopback tool call, median
हर call पर check, 6 runs	1.3–1.6 µs	6.1–7.0 µs	0.43–0.78 ms
सिर्फ़ token, 3 runs	0.7–1.6 µs	3.5–7.7 µs	0.35–1.36 ms (2 runs)

Memory में यह recheck loopback HTTP call के noise में खो जाता है। असली server set membership की जगह database lookups करता है, इसलिए उसकी क़ीमत ज़्यादा होती है। यह rebuild उसे माप नहीं सकता, इसलिए उसके लिए कोई number नहीं दिया गया है। अंदाज़े के लिए, Tokyo से live endpoint तक network leg urllib में हर बार नए TLS connection के साथ लगभग 500 ms से 800 ms प्रति request है (हर एक के लिए n=10: initialize median 790 ms, tools/list 816 ms, 401 वाला tools/call 565 ms, हर metadata document लगभग 520–530 ms)। Connector का समय access check में नहीं जाता।

Discovery ख़ुद locally 5 HTTP round trips थी: 401, resource metadata, server metadata, authorize, token। सात runs में इसमें 7.5–13.4 ms लगे, और एक बार Mac busy होने पर 34 ms। Live server के ख़िलाफ़, बिना credentials के किए जा सकने वाले तीन GET/POST legs cold start से मिलाकर लगभग 1.6 s लेते हैं। Authorize leg तो वैसे भी किसी इंसान का इंतज़ार करता है।

Claude osFoundry को call कर सकता है, पर osFoundry आपकी Claude chats क्यों नहीं खोल सकता?

इस setup में caller host है। वही connection खोलता है, tools list करता है और तय करता है कि कब कौन-सा tool call करना है। Server सिर्फ़ जवाब देता है। इस setup में ऐसा कुछ नहीं है जो server को host की conversations तक पहुंच दे। osFoundry का plan यह बात अपनी capability table में कहता है: मनचाही personal ChatGPT/Claude chats खोलना या उनकी list निकालना "No" है, साथ में "No general host API is provided for this"।

इसी से tools का design तय होता है। link_current_chat में chat ख़ुद अपने अंदर से link बनाती है। उसका label chat ख़ुद बताती है, और osFoundry उसे routing के लिए इस्तेमाल करता है, identity के तौर पर नहीं। किसी linked Claude chat को दिया गया काम तब तक इंतज़ार करता है जब तक user वह chat खोलकर उससे check करने को न कहे। ChatGPT में subscribed chats के लिए MCP Events हैं, और osFoundry का plan इसे host-specific मानता है।

Data से जुड़े सारे फ़ैसले server side के पास हैं, क्योंकि सिर्फ़ उसे ही किसी project की मौजूदा स्थिति पता होती है। कब action लेना है और user से पूछना है या नहीं, ये सारे फ़ैसले host side के पास हैं। हर call पर होने वाला check ही server को सही बनाए रखता है जब ये दोनों sides एक-दूसरे से अलग हो जाती हैं।

अगर आप इसे ख़ुद wire up करें

401 के WWW-Authenticate में resource_metadata डालिए और RFC 9728 को /.well-known/oauth-protected-resource/<resource path> पर serve कीजिए। जो client URL हाथ से बनाता है, वह गलती कर सकता है। Header हर client को इससे बचा लेता है।
Sign-in से पहले क्या public है, यह तय कीजिए। osFoundry initialize और tools/list खुला रखता है और tools/call को guard करता है। अगर आपके tool descriptions tenants के बारे में कुछ भी leak करते हैं, तो tools/list को भी guard कीजिए।
हर tool के लिए एक scope और readOnlyHint declare कीजिए। Hosts इनसे approval prompts बना सकते हैं, और 403 insufficient_scope host को दोबारा मांगने के लिए कुछ ठोस देता है।
Token छोटा रखिए: कौन, कौन-सा connection, कौन-से scopes। Workspace, project membership, resource का project और approve करने वाले का मौजूदा role हर call पर दोबारा पढ़िए, ताकि revoke और "दूसरे project में move करना" अगली ही call पर असर करें।
Resource denials को 401/403 की बजाय tool results के रूप में लौटाइए। दूसरा token "यह Note project B में है" को ठीक नहीं करेगा।
Writes के साथ expected_version और एक idempotency key भेजिए। Hosts retry करते हैं, और models calls दोबारा भेजते हैं।

Spec का MCP वाला हिस्सा MCP authorization page पर है। osFoundry की अपनी छोटी परिभाषा उसकी MCP वाली glossary entry में है।

Bagaimana custom connector Claude menemukan server OAuth osFoundry, dan kenapa akses dicek di setiap panggilan?

BBT — Fri, 06 Nov 2026 10:45:59 +0000

Ini yang diterima client MCP remote saat memanggil tool osFoundry tanpa token. Request-nya dikirim dengan curl dari sebuah Mac di Tokyo pada 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\", ..."]}}}

Satu header itu sudah cukup bagi custom connector Claude, atau koneksi MCP di developer mode ChatGPT, untuk menemukan halaman login. Pengguna cukup menempelkan URL-nya. Semua yang ada di bawah berasal dari request tanpa autentikasi ke endpoint live, ditambah rebuild kecil dalam Python yang dijalankan secara lokal untuk mengukur bagian yang tidak bisa diperlihatkan curl: apa yang terjadi pada akses setelah login.

Apa yang dilihat client sebelum punya token?

Tiga panggilan, tiga jawaban berbeda:

Request	Status	Yang dikembalikan
`initialize`	200	protokol `2025-06-18`, server `osfoundry 0.1.0`, plus instruksi
`tools/list`	200	59 tool, 45,368 byte
`tools/call`	401	`WWW-Authenticate` yang menunjuk ke resource metadata
`GET` ke endpoint	405	tidak ada stream SSE lewat GET

Handshake dan katalog tool bersifat publik. Hanya pemanggilan tool yang butuh token. Dengan begitu host bisa menunjukkan ke pengguna tool apa saja yang ada sebelum siapa pun login. Tidak ada data pengguna di katalog, dan string instructions di initialize bersifat umum:

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

Setiap tool di tools/list mendeklarasikan scope OAuth yang dibutuhkannya dan apakah tool itu hanya membaca:

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

Dari 59 tool: 30 butuh osfoundry:read dan ditandai readOnlyHint: true, 26 butuh osfoundry:write, dan 3 butuh osfoundry:run (request_session_run, run_graph_session, cancel_graph_run). Host bisa memakai readOnlyHint untuk menentukan panggilan mana yang perlu prompt persetujuan.

Ke mana 401 itu mengarahkannya?

resource_metadata mengikuti RFC 9728 (OAuth Protected Resource Metadata). Suffix well-known diletakkan tepat setelah host, lalu path resource ditambahkan di belakangnya. Suffix itu tidak ditempel di ujung URL resource:

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"]}

Kalau kamu membuat client sendiri, 404 itu adalah kesalahan pertama yang akan kamu buat. Ambil URL dari header, jangan menyusunnya sendiri.

Apa kata authorization server tentang dirinya?

/.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}

Baca ini sebagai rangkaian keputusan. Ada registration_endpoint, jadi host bisa mendaftarkan dirinya sendiri (dynamic client registration) dan pengguna tidak pernah berurusan dengan client ID. Autentikasi token-nya none, jadi host adalah public client tanpa client secret, dan PKCE dengan S256 yang mengikat code ke client yang memintanya. iss di authorization response mencegah salah tukar saat sebuah host berbicara dengan beberapa authorization server.

Langkah authorize mengarahkan browser ke halaman consent osFoundry, https://osfoundry.io/external-assistant-authorize. Di sana pengguna memilih tepat satu workspace dan mencentang "I approve connecting this assistant to …" (saya menyetujui asisten ini dihubungkan ke …). Persetujuan itu hanya menyebut satu workspace, tidak lebih. Koneksi baru belum punya project. Owner menambahkannya belakangan di aplikasi (key icon → Connected → Add to project).

Kenapa scope saja tidak cukup?

Scope ditetapkan saat token diterbitkan. osfoundry:write menyatakan bahwa koneksi boleh melakukan aksi tulis. Scope itu tidak menyebut Note yang mana, dan tidak bisa tahu bahwa Note tersebut dipindahkan ke project lain sepuluh menit lalu. Catatan desain osFoundry mendaftar apa saja yang dibaca ulang di setiap panggilan: status koneksi, workspace, keanggotaan project, project dan ACL resource saat ini, keanggotaan channel atau role di session, tool-nya, dan scope OAuth. Orang yang menyetujui koneksi juga harus masih punya hak edit atas item tersebut. Penghapusan atau pemindahan "langsung berlaku".

Alternatifnya adalah memasukkan daftar project ke dalam token, atau ke cache yang di-key oleh token, lalu memercayainya sampai kedaluwarsa. Itu lebih murah untuk ditulis. Rebuild di bawah mengimplementasikan keduanya supaya perbedaan perilakunya bisa diukur.

Rebuild-nya

Tidak ada binary Claude yang terlibat. client.py berperan sebagai host dan server.py sebagai server MCP. Keduanya hanya memakai standard library, sekitar 280 baris jika digabung, dan dijalankan di Python 3.9.6 pada Apple M1. Server-nya mengimplementasikan initialize, tools/list, dan tools/call lewat JSON-RPC di atas HTTP biasa, dua dokumen well-known, /authorize (halaman consent otomatis disetujui untuk satu workspace), dan /token dengan PKCE S256. Beberapa route /admin/* menggantikan klik owner di tab Connected.

Pengecekan yang berjalan sebelum setiap tool:

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

Client mulai tanpa token. Ia memanggil sebuah tool, menerima 401, mem-parse resource_metadata dari WWW-Authenticate, mengambil kedua dokumen metadata, menjalankan authorize dan token dengan PKCE verifier baru, lalu menjalankan skenarionya:

$ 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

Client yang sama terhadap CHECK=token_only. Di sini token membawa daftar project dari refresh terakhirnya:

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"

Langkah 1–7 identik. Langkah 7 tetap ditolak di desain token-only karena project milik note dicek secara live. Desain token-only hanya jadi basi untuk fakta yang disimpan di dalam token. Langkah 8 dan 9 adalah yang penting bagi owner: mereka sudah menghapus project, lalu mencabut koneksi, tapi chat tetap bisa membaca. Di desain token-only, kondisi itu bertahan sampai token kedaluwarsa, yaitu expires_in: 3600 di rebuild ini.

Penolakan terbagi di dua lapisan. Scope yang kurang adalah kegagalan di level protokol: 403 dengan error="insufficient_scope" dan scope yang dibutuhkan di WWW-Authenticate, sehingga host bisa meminta lebih. Semua yang berkaitan dengan item mana yang terlibat adalah hasil tool biasa dengan isError: true. Otorisasi ulang tidak akan memperbaikinya, jadi tidak ada gunanya menyuruh host mencoba lagi.

Berapa biaya pengecekan di setiap panggilan?

Diukur dengan time.perf_counter_ns() di sekitar access() di dalam server, 1,000 panggilan per run (500 diizinkan, 500 ditolak), di Mac yang juga sedang menjalankan job lain:

	median access()	p99 access()	median tool call loopback
cek per panggilan, 6 run	1.3–1.6 µs	6.1–7.0 µs	0.43–0.78 ms
token-only, 3 run	0.7–1.6 µs	3.5–7.7 µs	0.35–1.36 ms (2 run)

Di memori, pengecekan ulang tenggelam di noise panggilan HTTP loopback. Server sungguhan melakukan query database, bukan sekadar cek keanggotaan set, jadi biayanya lebih tinggi. Rebuild ini tidak bisa mengukurnya, jadi tidak ada angka yang diberikan. Sebagai gambaran, perjalanan jaringan ke endpoint live dari Tokyo sekitar 500 ms sampai 800 ms per request dengan urllib dan koneksi TLS baru setiap kali (masing-masing n=10: median initialize 790 ms, tools/list 816 ms, tools/call yang 401 565 ms, tiap dokumen metadata sekitar 520–530 ms). Waktu sebuah connector tidak habis di pengecekan akses.

Discovery-nya sendiri butuh 5 round trip HTTP secara lokal: 401, resource metadata, server metadata, authorize, token. Itu memakan 7.5–13.4 ms dalam tujuh run dan 34 ms sekali saat Mac sedang sibuk. Terhadap server live, tiga leg GET/POST yang bisa dilakukan tanpa kredensial totalnya kira-kira 1.6 s dari cold start. Leg authorize toh menunggu manusia.

Kenapa Claude bisa memanggil osFoundry, tapi osFoundry tidak bisa membuka chat Claude kamu?

Di setup ini, host-lah yang memanggil. Host membuka koneksi, mengambil daftar tool, dan memutuskan kapan memanggil salah satunya. Server menjawab. Tidak ada apa pun di setup ini yang memberi server akses ke percakapan milik host. Rencana osFoundry menuliskannya di tabel kapabilitasnya: membuka atau mendaftar chat pribadi ChatGPT/Claude sembarang adalah "No", dengan keterangan "No general host API is provided for this".

Hal itu membentuk tool-nya. Dengan link_current_chat, chat itu sendiri yang membuat link dari dalam chat. Label-nya dilaporkan sendiri oleh chat, dan osFoundry memakainya untuk routing, bukan sebagai identitas. Pekerjaan yang ditugaskan ke chat Claude yang ter-link menunggu sampai pengguna membuka chat itu dan memintanya untuk mengecek. ChatGPT punya MCP Events untuk chat yang berlangganan, dan rencana osFoundry memperlakukannya sebagai fitur khusus host tersebut.

Sisi server memegang semua keputusan soal data, karena hanya sisi itu yang tahu kondisi terkini sebuah project. Sisi host memegang semua keputusan soal kapan bertindak dan apakah perlu bertanya ke pengguna. Pengecekan per panggilan inilah yang membuat server tetap benar ketika kedua sisi itu tidak lagi sinkron.

Kalau kamu memasangnya sendiri

Taruh resource_metadata di WWW-Authenticate milik respons 401 dan sajikan RFC 9728 di /.well-known/oauth-protected-resource/<resource path>. Client yang menyusun URL sendiri bisa salah. Header itu menyelamatkan setiap client dari kesalahan tersebut.
Tentukan apa yang publik sebelum login. osFoundry membuka initialize dan tools/list dan menjaga tools/call. Kalau deskripsi tool kamu membocorkan sesuatu tentang tenant, jaga juga tools/list.
Deklarasikan scope dan readOnlyHint per tool. Host bisa membangun prompt persetujuan dari situ, dan 403 insufficient_scope memberi host sesuatu yang konkret untuk diminta ulang.
Buat token tetap kecil: siapa, koneksi mana, scope apa. Baca ulang workspace, keanggotaan project, project milik resource, dan role terkini orang yang menyetujui di setiap panggilan, supaya pencabutan dan "pindah ke project lain" langsung berlaku di panggilan berikutnya.
Kembalikan penolakan resource sebagai hasil tool, bukan sebagai 401/403. Token yang berbeda tidak akan memperbaiki "Note ini ada di project B".
Buat operasi tulis membawa expected_version dan idempotency key. Host melakukan retry, dan model mengulang panggilan.

Sisi MCP dari spesifikasinya ada di halaman otorisasi MCP. Definisi singkat versi osFoundry ada di entri glosariumnya tentang MCP.

Come fa un connettore personalizzato di Claude a trovare il server OAuth di osFoundry, e perché l'accesso viene controllato a ogni chiamata?

BBT — Fri, 06 Nov 2026 10:45:13 +0000

Ecco cosa riceve un client MCP remoto quando chiama uno strumento di osFoundry senza token. La richiesta è stata inviata con curl da un Mac a Tokyo il 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\", ..."]}}}

Quell'unico header basta al connettore personalizzato di Claude, o alla connessione MCP della modalità sviluppatore di ChatGPT, per trovare la pagina di accesso. L'utente incolla solo l'URL. Tutto quello che segue viene da richieste non autenticate all'endpoint in produzione, più una piccola ricostruzione in Python, eseguita in locale, che misura quello che un curl non può mostrare: cosa succede all'accesso dopo il login.

Cosa vede il client prima di avere un token?

Tre chiamate, tre risposte diverse:

Richiesta	Stato	Cosa torna indietro
`initialize`	200	protocollo `2025-06-18`, server `osfoundry 0.1.0`, più le istruzioni
`tools/list`	200	59 strumenti, 45,368 byte
`tools/call`	401	`WWW-Authenticate` che punta ai metadati della risorsa
`GET` sull'endpoint	405	nessuno stream SSE in GET

L'handshake e il catalogo degli strumenti sono pubblici. Solo la chiamata a uno strumento richiede un token. Così l'host può mostrare all'utente quali strumenti esistono prima che qualcuno faccia login. Nel catalogo non ci sono dati utente, e la stringa instructions in initialize è generica:

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

Ogni strumento in tools/list dichiara lo scope OAuth che gli serve e se fa solo letture:

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

Sui 59 strumenti: 30 richiedono osfoundry:read e sono marcati readOnlyHint: true, 26 richiedono osfoundry:write e 3 richiedono osfoundry:run (request_session_run, run_graph_session, cancel_graph_run). Un host può usare readOnlyHint per decidere quali chiamate richiedono una conferma.

Dove lo manda il 401?

resource_metadata segue la RFC 9728 (OAuth Protected Resource Metadata). Il suffisso well-known va subito dopo l'host, con il percorso della risorsa aggiunto in coda. Non va aggiunto in fondo all'URL della risorsa:

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"]}

Se scrivi un client a mano, quel 404 è il primo errore che farai. Leggi l'URL dall'header invece di costruirlo tu.

Cosa dice di sé il server di autorizzazione?

/.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}

Leggilo come una catena di decisioni. C'è un registration_endpoint, quindi l'host può registrarsi da solo (registrazione dinamica del client) e l'utente non ha mai a che fare con un client ID. L'autenticazione al token endpoint è none, quindi l'host è un client pubblico senza client secret, ed è PKCE con S256 a legare il codice al client che l'ha richiesto. iss nella risposta di autorizzazione evita scambi quando un host parla con più server di autorizzazione.

Il passo di authorize porta il browser sulla pagina di consenso di osFoundry, https://osfoundry.io/external-assistant-authorize. Lì l'utente sceglie esattamente un workspace e spunta "I approve connecting this assistant to …" (approvo il collegamento di questo assistente a …). L'approvazione indica un workspace e nient'altro. Una connessione nuova non ha progetti. Il proprietario li aggiunge dopo nell'app (key icon → Connected → Add to project).

Perché lo scope non basta?

Uno scope viene fissato quando il token viene emesso. osfoundry:write dice che la connessione può eseguire azioni di scrittura. Non dice quale Note, e non può sapere che quella Note è stata spostata in un altro progetto dieci minuti fa. Le note di design di osFoundry elencano cosa viene riletto a ogni chiamata: stato della connessione, workspace, appartenenza al progetto, progetto attuale e ACL della risorsa, appartenenza al canale o ruolo nella sessione, lo strumento e lo scope OAuth. In più, chi ha approvato la connessione deve avere ancora i permessi di modifica sull'elemento. Una rimozione o una riassegnazione "ha effetto immediato".

L'alternativa è mettere l'elenco dei progetti nel token, o in una cache con il token come chiave, e fidarsi fino alla scadenza. È più economico da scrivere. La ricostruzione qui sotto implementa entrambe le cose, così la differenza di comportamento si può misurare.

La ricostruzione

Non c'è nessun binario di Claude di mezzo. client.py fa da host e server.py fa da server MCP. Entrambi usano solo la libreria standard, circa 280 righe in tutto, e sono stati eseguiti con Python 3.9.6 su un Apple M1. Il server implementa initialize, tools/list e tools/call su JSON-RPC via HTTP semplice, i due documenti well-known, /authorize (la pagina di consenso si approva da sola per un workspace) e /token con PKCE S256. Alcune route /admin/* sostituiscono i clic del proprietario nella scheda Connected.

Il controllo che gira prima di ogni strumento:

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

Il client parte senza token. Chiama uno strumento, riceve il 401, estrae resource_metadata da WWW-Authenticate, scarica i due documenti di metadati, esegue authorize e token con un verifier PKCE nuovo e poi percorre lo scenario:

$ 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

Lo stesso client contro CHECK=token_only. Qui il token porta l'elenco dei progetti dell'ultimo 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"

I passi 1–7 sono identici. Il passo 7 viene negato anche nel design solo-token, perché il progetto della nota viene letto in tempo reale. Il design solo-token diventa obsoleto solo sui dati che vivono nel token. I passi 8 e 9 sono quelli che interessano al proprietario: ha rimosso il progetto, poi ha revocato la connessione, e la chat ha continuato a leggere. Nel design solo-token questo dura finché il token non scade, cioè expires_in: 3600 in questa ricostruzione.

I rifiuti si dividono su due livelli. Uno scope mancante è un errore a livello di protocollo: 403 con error="insufficient_scope" e lo scope necessario in WWW-Authenticate, così l'host può chiederne di più. Tutto ciò che riguarda quale elemento è coinvolto è un normale risultato dello strumento con isError: true. Una nuova autorizzazione non lo risolverebbe, quindi non ha senso dire all'host di riprovare.

Quanto costa il controllo a ogni chiamata?

Misurato con time.perf_counter_ns() attorno ad access() dentro il server, 1,000 chiamate per esecuzione (500 consentite, 500 negate), su un Mac che nel frattempo eseguiva anche altri job:

	access() mediana	access() p99	chiamata a strumento in loopback, mediana
controllo a ogni chiamata, 6 esecuzioni	1.3–1.6 µs	6.1–7.0 µs	0.43–0.78 ms
solo token, 3 esecuzioni	0.7–1.6 µs	3.5–7.7 µs	0.35–1.36 ms (2 esecuzioni)

In memoria, il ricontrollo sparisce nel rumore di una chiamata HTTP in loopback. Un server vero fa query al database invece di verificare l'appartenenza a un set, quindi il suo costo è più alto. Questa ricostruzione non può misurarlo, quindi non viene dato nessun numero. Per avere un ordine di grandezza, il tratto di rete verso l'endpoint in produzione da Tokyo è di circa 500 ms–800 ms per richiesta con urllib e una nuova connessione TLS ogni volta (n=10 ciascuno: initialize mediana 790 ms, tools/list 816 ms, il tools/call con 401 565 ms, ogni documento di metadati circa 520–530 ms). Non è nel controllo degli accessi che un connettore passa il suo tempo.

La discovery in sé erano 5 round trip HTTP in locale: 401, metadati della risorsa, metadati del server, authorize, token. Ci sono voluti 7.5–13.4 ms in sette esecuzioni, e 34 ms una volta con il Mac sotto carico. Contro il server in produzione, i tre tratti GET/POST che puoi fare senza credenziali sommano circa 1.6 s a freddo. Il tratto di authorize aspetta comunque una persona.

Perché Claude può chiamare osFoundry, ma osFoundry non può aprire le tue chat di Claude?

In questo setup è l'host a chiamare. Apre la connessione, elenca gli strumenti e decide quando chiamarne uno. Il server risponde. Niente in questo setup dà al server un appiglio sulle conversazioni dell'host. Il piano di osFoundry lo scrive nella sua tabella delle capacità: aprire o elencare chat personali arbitrarie di ChatGPT/Claude è "No", con "No general host API is provided for this".

Questo dà forma agli strumenti. Con link_current_chat è la chat stessa a creare un collegamento dall'interno. La sua etichetta è dichiarata dalla chat, e osFoundry la usa per l'instradamento, non come identità. Il lavoro assegnato a una chat di Claude collegata resta in attesa finché l'utente non apre quella chat e le chiede di controllare. ChatGPT ha gli MCP Events per le chat iscritte, e il piano di osFoundry lo tratta come specifico di quell'host.

Il lato server ha in mano tutte le decisioni sui dati, perché è l'unico a conoscere lo stato attuale di un progetto. Il lato host ha in mano tutte le decisioni su quando agire e se chiedere all'utente. Il controllo a ogni chiamata è ciò che permette al server di restare corretto quando i due lati vanno fuori sincrono.

Se lo colleghi tu

Metti resource_metadata nel WWW-Authenticate del 401 e servi la RFC 9728 su /.well-known/oauth-protected-resource/<resource path>. Un client che costruisce l'URL a mano può sbagliarlo. L'header risparmia questo errore a ogni client.
Decidi cosa è pubblico prima del login. osFoundry espone initialize e tools/list e protegge tools/call. Se le descrizioni dei tuoi strumenti lasciano trapelare qualcosa sui tenant, proteggi anche tools/list.
Dichiara uno scope e readOnlyHint per ogni strumento. Gli host possono costruirci sopra le richieste di conferma, e un 403 insufficient_scope dà all'host qualcosa di concreto da richiedere di nuovo.
Tieni il token piccolo: chi, quale connessione, quali scope. Rileggi a ogni chiamata il workspace, l'appartenenza al progetto, il progetto della risorsa e il ruolo attuale di chi ha approvato, così la revoca e "sposta in un altro progetto" valgono già dalla chiamata successiva.
Restituisci i rifiuti sulle risorse come risultati dello strumento, non come 401/403. Un altro token non sistemerà "questa Note è nel progetto B".
Fai in modo che le scritture portino expected_version e una chiave di idempotenza. Gli host ritentano, e i modelli ripetono le chiamate.

La parte MCP della specifica è nella pagina sull'autorizzazione di MCP. La definizione breve di osFoundry è nella sua voce di glossario su MCP.

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.

Wie findet ein Claude Custom Connector den OAuth-Server von osFoundry, und warum wird der Zugriff bei jedem Aufruf geprüft?

BBT — Fri, 06 Nov 2026 10:38:30 +0000

Das bekommt ein Remote-MCP-Client zurück, wenn er ein Tool von osFoundry ohne Token aufruft. Die Anfrage wurde am 2026-11-06 mit curl von einem Mac in Tokio geschickt:

$ 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\", ..."]}}}

Dieser eine Header reicht dem Custom Connector von Claude, oder der MCP-Verbindung im Developer Mode von ChatGPT, um die Anmeldeseite zu finden. Der Nutzer fügt nur die URL ein. Alles Folgende stammt aus nicht authentifizierten Anfragen an den Live-Endpoint, plus einem kleinen Nachbau in Python, lokal ausgeführt, der misst, was ein curl nicht zeigen kann: was nach der Anmeldung mit dem Zugriff passiert.

Was sieht der Client, bevor er ein Token hat?

Drei Aufrufe, drei verschiedene Antworten:

Anfrage	Status	Was zurückkommt
`initialize`	200	Protokoll `2025-06-18`, Server `osfoundry 0.1.0`, dazu Instructions
`tools/list`	200	59 Tools, 45,368 Bytes
`tools/call`	401	`WWW-Authenticate` mit Verweis auf die Resource Metadata
`GET` auf den Endpoint	405	kein SSE-Stream per GET

Handshake und Tool-Katalog sind öffentlich. Nur der Tool-Aufruf braucht ein Token. Dadurch kann der Host dem Nutzer zeigen, welche Tools es gibt, bevor sich überhaupt jemand anmeldet. Im Katalog stehen keine Nutzerdaten, und der instructions-String in initialize ist generisch:

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

Jedes Tool in tools/list gibt an, welchen OAuth-Scope es braucht und ob es nur liest:

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

Über alle 59 Tools: 30 brauchen osfoundry:read und sind mit readOnlyHint: true markiert, 26 brauchen osfoundry:write, und 3 brauchen osfoundry:run (request_session_run, run_graph_session, cancel_graph_run). Ein Host kann anhand von readOnlyHint entscheiden, welche Aufrufe eine Bestätigung brauchen.

Wohin schickt ihn der 401?

resource_metadata folgt RFC 9728 (OAuth Protected Resource Metadata). Das Well-known-Suffix kommt direkt hinter den Host, der Ressourcenpfad wird hinten angehängt. Es wird nicht an die Ressourcen-URL angehängt:

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"]}

Wenn du einen Client von Hand baust, ist dieser 404 der erste Fehler, den du machst. Lies die URL aus dem Header, statt sie selbst zusammenzubauen.

Was sagt der Authorization Server über sich selbst?

/.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}

Lies das als Kette von Entscheidungen. Es gibt einen registration_endpoint, also kann sich der Host selbst registrieren (Dynamic Client Registration), und der Nutzer hat nie mit einer Client-ID zu tun. Die Token-Authentifizierung ist none, also ist der Host ein Public Client ohne Client Secret, und PKCE mit S256 bindet den Code an den Client, der ihn angefordert hat. iss in der Authorization Response schützt vor Verwechslungen, wenn ein Host mit mehreren Authorization Servern spricht.

Der Authorize-Schritt schickt den Browser auf die Consent-Seite von osFoundry, https://osfoundry.io/external-assistant-authorize. Dort wählt der Nutzer genau einen Workspace und hakt "I approve connecting this assistant to …" an (ich erlaube, diesen Assistenten zu verbinden mit …). Die Freigabe nennt einen Workspace und sonst nichts. Eine neue Verbindung hat keine Projekte. Die fügt der Owner danach in der App hinzu (key icon → Connected → Add to project).

Warum reicht der Scope nicht?

Ein Scope steht fest, sobald das Token ausgestellt wird. osfoundry:write sagt, dass die Verbindung schreibende Aktionen ausführen darf. Es sagt nicht, welche Note, und es kann nicht wissen, dass die Note vor zehn Minuten in ein anderes Projekt verschoben wurde. Die Design-Notizen von osFoundry listen auf, was bei jedem Aufruf neu gelesen wird: Verbindungsstatus, Workspace, Projektmitgliedschaft, das aktuelle Projekt und die ACL der Ressource, Channel-Mitgliedschaft oder Session-Rolle, das Tool und der OAuth-Scope. Außerdem muss die Person, die die Verbindung freigegeben hat, noch Bearbeitungsrechte auf das Element haben. Entfernen oder Neuzuweisen "wirkt sofort".

Die Alternative: die Projektliste ins Token packen, oder in einen Cache mit dem Token als Schlüssel, und ihr bis zum Ablauf vertrauen. Das ist billiger zu schreiben. Der Nachbau unten implementiert beides, damit sich der Unterschied im Verhalten messen lässt.

Der Nachbau

Es ist kein Claude-Binary beteiligt. client.py spielt den Host und server.py den MCP-Server. Beide nutzen nur die Standardbibliothek, zusammen etwa 280 Zeilen, und liefen mit Python 3.9.6 auf einem Apple M1. Der Server implementiert initialize, tools/list und tools/call über einfaches HTTP-JSON-RPC, die beiden Well-known-Dokumente, /authorize (die Consent-Seite wird für einen Workspace automatisch bestätigt) und /token mit S256-PKCE. Ein paar /admin/*-Routen ersetzen die Klicks des Owners im Tab Connected.

Die Prüfung, die vor jedem Tool läuft:

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

Der Client startet ohne Token. Er ruft ein Tool auf, bekommt den 401, parst resource_metadata aus WWW-Authenticate, holt beide Metadaten-Dokumente, macht Authorize und Token mit einem frischen PKCE-Verifier und arbeitet dann das Szenario ab:

$ 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

Derselbe Client gegen CHECK=token_only. Hier trägt das Token die Projektliste vom letzten 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"

Die Schritte 1–7 sind identisch. Schritt 7 wird auch im Token-only-Design abgelehnt, weil das Projekt der Notiz live nachgeschlagen wird. Das Token-only-Design veraltet nur bei Fakten, die im Token stecken. Die Schritte 8 und 9 sind die, auf die es dem Owner ankommt: Er hat das Projekt entfernt, dann die Verbindung widerrufen, und der Chat hat weitergelesen. Im Token-only-Design hält das an, bis das Token abläuft, in diesem Nachbau expires_in: 3600.

Ablehnungen verteilen sich auf zwei Ebenen. Ein fehlender Scope ist ein Fehler auf Protokollebene: 403 mit error="insufficient_scope" und dem benötigten Scope in WWW-Authenticate, damit ein Host mehr anfordern kann. Alles, was davon abhängt, um welches Element es geht, ist ein normales Tool-Ergebnis mit isError: true. Eine erneute Autorisierung würde das nicht beheben, also hat es keinen Sinn, den Host dazu aufzufordern.

Was kostet die Prüfung pro Aufruf?

Gemessen mit time.perf_counter_ns() um access() im Server, 1,000 Aufrufe pro Lauf (500 erlaubt, 500 abgelehnt), auf einem Mac, der nebenbei andere Jobs laufen hatte:

	access() Median	access() p99	Loopback-Tool-Aufruf, Median
Prüfung pro Aufruf, 6 Läufe	1.3–1.6 µs	6.1–7.0 µs	0.43–0.78 ms
nur Token, 3 Läufe	0.7–1.6 µs	3.5–7.7 µs	0.35–1.36 ms (2 Läufe)

Im Speicher geht die erneute Prüfung im Rauschen eines Loopback-HTTP-Aufrufs unter. Ein echter Server macht Datenbankabfragen statt Set-Lookups, die Kosten sind also höher. Das kann dieser Nachbau nicht messen, deshalb gibt es dafür keine Zahl. Zur Einordnung: Die Netzwerkstrecke zum Live-Endpoint aus Tokio liegt bei etwa 500 ms bis 800 ms pro Anfrage mit urllib und jedes Mal neuer TLS-Verbindung (je n=10: initialize Median 790 ms, tools/list 816 ms, der 401-tools/call 565 ms, jedes Metadaten-Dokument etwa 520–530 ms). Die Zugriffsprüfung ist nicht der Punkt, an dem ein Connector seine Zeit verbringt.

Die Discovery selbst waren lokal 5 HTTP-Roundtrips: 401, Resource Metadata, Server Metadata, Authorize, Token. Das dauerte 7.5–13.4 ms in sieben Läufen und einmal 34 ms, als der Mac ausgelastet war. Gegen den Live-Server summieren sich die drei GET/POST-Strecken, die ohne Credentials möglich sind, kalt auf ungefähr 1.6 s. Die Authorize-Strecke wartet sowieso auf einen Menschen.

Warum kann Claude osFoundry aufrufen, aber osFoundry deine Claude-Chats nicht öffnen?

In diesem Aufbau ist der Host der Aufrufer. Er öffnet die Verbindung, listet die Tools und entscheidet, wann er eines aufruft. Der Server antwortet. Nichts in diesem Aufbau gibt dem Server einen Zugriff auf die Unterhaltungen des Hosts. Der Plan von osFoundry sagt das in seiner Capability-Tabelle: Beliebige persönliche ChatGPT/Claude-Chats öffnen oder auflisten ist "No", mit "No general host API is provided for this".

Das prägt die Tools. Bei link_current_chat legt der Chat den Link von innen selbst an. Sein Label gibt der Chat selbst an, und osFoundry nutzt es zum Routing, nicht als Identität. Arbeit, die einem verknüpften Claude-Chat zugewiesen ist, wartet, bis der Nutzer diesen Chat öffnet und ihn bittet nachzusehen. ChatGPT hat MCP Events für abonnierte Chats, und der Plan von osFoundry behandelt das als hostspezifisch.

Die Serverseite trifft alle Entscheidungen über Daten, weil nur sie den aktuellen Stand eines Projekts kennt. Die Hostseite trifft alle Entscheidungen darüber, wann gehandelt wird und ob der Nutzer gefragt wird. Die Prüfung pro Aufruf sorgt dafür, dass der Server korrekt bleibt, wenn die beiden Seiten auseinanderlaufen.

Wenn du das selbst verdrahtest

Pack resource_metadata in den WWW-Authenticate des 401 und liefere RFC 9728 unter /.well-known/oauth-protected-resource/<resource path> aus. Ein Client, der die URL selbst baut, kann sie falsch bauen. Der Header erspart das jedem Client.
Leg fest, was vor der Anmeldung öffentlich ist. osFoundry gibt initialize und tools/list frei und schützt tools/call. Wenn deine Tool-Beschreibungen etwas über Tenants verraten, schütz auch tools/list.
Deklarier pro Tool einen Scope und readOnlyHint. Hosts können daraus Bestätigungsdialoge bauen, und ein 403 insufficient_scope gibt dem Host etwas Konkretes, das er neu anfordern kann.
Halt das Token klein: wer, welche Verbindung, welche Scopes. Lies Workspace, Projektmitgliedschaft, das Projekt der Ressource und die aktuelle Rolle der freigebenden Person bei jedem Aufruf neu, damit Widerruf und "in ein anderes Projekt verschieben" beim nächsten Aufruf greifen.
Gib Ablehnungen auf Ressourcenebene als Tool-Ergebnisse zurück, nicht als 401/403. Ein anderes Token behebt "diese Note liegt in Projekt B" nicht.
Lass Schreibvorgänge expected_version und einen Idempotency Key mitschicken. Hosts wiederholen Anfragen, und Modelle setzen Aufrufe erneut ab.

Die MCP-Seite der Spezifikation steht auf der Autorisierungsseite von MCP. Die kurze Definition von osFoundry steht im Glossareintrag zu MCP.

¿Cómo encuentra un conector personalizado de Claude el servidor OAuth de osFoundry y por qué se comprueba el acceso en cada llamada?

BBT — Fri, 06 Nov 2026 10:30:52 +0000

Esto es lo que recibe un cliente MCP remoto cuando llama a una herramienta de osFoundry sin token. La petición se hizo con curl desde un Mac en Tokio el 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\", ..."]}}}

Con esa única cabecera, el conector personalizado de Claude, o la conexión MCP del modo desarrollador de ChatGPT, encuentra la página de inicio de sesión. El usuario solo pega la URL. Todo lo que sigue sale de peticiones sin autenticar al endpoint en producción, más una pequeña reconstrucción en Python, ejecutada en local, que mide lo que un curl no puede enseñar: qué pasa con el acceso después de iniciar sesión.

¿Qué ve el cliente antes de tener un token?

Tres llamadas, tres respuestas distintas:

Petición	Estado	Qué devuelve
`initialize`	200	protocolo `2025-06-18`, servidor `osfoundry 0.1.0`, más instrucciones
`tools/list`	200	59 herramientas, 45,368 bytes
`tools/call`	401	`WWW-Authenticate` apuntando a los metadatos del recurso
`GET` sobre el endpoint	405	no hay stream SSE por GET

El handshake y el catálogo de herramientas son públicos. Solo llamar a una herramienta exige token. Así el host puede enseñar al usuario qué herramientas existen antes de que nadie inicie sesión. Nada del catálogo son datos de usuario, y el texto de instructions en initialize es genérico:

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

Cada herramienta de tools/list declara el scope OAuth que necesita y si solo lee:

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

De las 59 herramientas, 30 necesitan osfoundry:read y llevan readOnlyHint: true, 26 necesitan osfoundry:write y 3 necesitan osfoundry:run (request_session_run, run_graph_session, cancel_graph_run). Un host puede usar readOnlyHint para decidir qué llamadas piden confirmación al usuario.

¿Adónde le manda el 401?

resource_metadata sigue la RFC 9728 (OAuth Protected Resource Metadata). El sufijo well-known va justo después del host, con la ruta del recurso añadida detrás. No se añade al final de la URL del recurso:

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 escribes un cliente a mano, ese 404 es el primer error que vas a cometer. Lee la URL de la cabecera en lugar de construirla tú.

¿Qué dice de sí mismo el servidor de autorización?

/.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}

Léelo como una cadena de decisiones. Hay un registration_endpoint, así que el host puede registrarse solo (registro dinámico de clientes) y el usuario nunca toca un client ID. La autenticación en el token es none, así que el host es un cliente público sin client secret, y lo que ata el código al cliente que lo pidió es PKCE con S256. iss en la respuesta de autorización evita confusiones cuando un host habla con varios servidores de autorización.

El paso de autorización lleva el navegador a la página de consentimiento de osFoundry, https://osfoundry.io/external-assistant-authorize. Ahí el usuario elige exactamente un workspace y marca "I approve connecting this assistant to …" (apruebo conectar este asistente a …). La aprobación nombra un workspace y nada más. Una conexión nueva no tiene proyectos. El propietario los añade después en la app (key icon → Connected → Add to project).

¿Por qué no basta con el scope?

Un scope se fija cuando se emite el token. osfoundry:write dice que la conexión puede hacer acciones de escritura. No dice qué Note, y no puede saber que esa Note se movió a otro proyecto hace diez minutos. Las notas de diseño de osFoundry enumeran lo que se vuelve a leer en cada llamada: estado de la conexión, workspace, pertenencia al proyecto, el proyecto actual y la ACL del recurso, pertenencia al canal o rol en la sesión, la herramienta y el scope OAuth. Además, la persona que aprobó la conexión tiene que seguir teniendo permisos de edición sobre el elemento. Quitar o reasignar algo "tiene efecto inmediato".

La alternativa es meter la lista de proyectos en el token, o en una caché indexada por el token, y fiarse de ella hasta que caduque. Es más barato de escribir. La reconstrucción de abajo implementa las dos cosas para poder medir la diferencia de comportamiento.

La reconstrucción

No hay ningún binario de Claude de por medio. client.py hace de host y server.py hace de servidor MCP. Los dos usan solo la biblioteca estándar, unas 280 líneas entre ambos, y se ejecutaron con Python 3.9.6 en un Apple M1. El servidor implementa initialize, tools/list y tools/call sobre JSON-RPC en HTTP plano, los dos documentos well-known, /authorize (la página de consentimiento se aprueba sola para un workspace) y /token con PKCE S256. Unas cuantas rutas /admin/* sustituyen a los clics del propietario en la pestaña Connected.

La comprobación que se ejecuta antes de cada herramienta:

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

El cliente arranca sin token. Llama a una herramienta, recibe el 401, saca resource_metadata de WWW-Authenticate, descarga los dos documentos de metadatos, hace authorize y token con un verificador PKCE nuevo y luego recorre el escenario:

$ 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

El mismo cliente contra CHECK=token_only. Aquí el token lleva la lista de proyectos de su último refresco:

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"

Los pasos 1–7 son idénticos. El paso 7 sigue denegado en el diseño solo-token porque el proyecto de la nota se consulta en vivo. El diseño solo-token solo se queda desfasado en los datos que viven dentro del token. Los pasos 8 y 9 son los que le importan al propietario: quitó el proyecto, luego revocó la conexión, y el chat siguió leyendo. En el diseño solo-token eso dura hasta que caduca el token, que en esta reconstrucción es expires_in: 3600.

Las denegaciones se reparten en dos capas. Un scope que falta es un fallo a nivel de protocolo: 403 con error="insufficient_scope" y el scope necesario en WWW-Authenticate, para que el host pueda pedir más. Todo lo que tiene que ver con qué elemento está implicado es un resultado normal de herramienta con isError: true. Volver a autorizar no lo arreglaría, así que no tiene sentido decirle al host que lo intente.

¿Cuánto cuesta la comprobación en cada llamada?

Medido con time.perf_counter_ns() alrededor de access() dentro del servidor, 1,000 llamadas por ejecución (500 permitidas, 500 denegadas), en un Mac que además estaba ejecutando otros trabajos:

	access() mediana	access() p99	llamada a herramienta en loopback, mediana
comprobación por llamada, 6 ejecuciones	1.3–1.6 µs	6.1–7.0 µs	0.43–0.78 ms
solo token, 3 ejecuciones	0.7–1.6 µs	3.5–7.7 µs	0.35–1.36 ms (2 ejecuciones)

En memoria, la recomprobación se pierde en el ruido de una llamada HTTP por loopback. Un servidor real hace consultas a base de datos en lugar de comprobar pertenencia a un conjunto, así que su coste es mayor. Esta reconstrucción no puede medirlo, así que no se da ninguna cifra. Para hacerse una idea, el tramo de red hasta el endpoint en producción desde Tokio ronda los 500 ms a 800 ms por petición con urllib y una conexión TLS nueva cada vez (n=10 cada una: initialize mediana 790 ms, tools/list 816 ms, el tools/call con 401 565 ms, cada documento de metadatos unos 520–530 ms). Un conector no pierde el tiempo en la comprobación de acceso.

El descubrimiento en sí fueron 5 idas y vueltas HTTP en local: 401, metadatos del recurso, metadatos del servidor, authorize, token. Tardó 7.5–13.4 ms en siete ejecuciones y 34 ms una vez con el Mac ocupado. Contra el servidor en producción, los tres tramos GET/POST que puedes hacer sin credenciales suman aproximadamente 1.6 s en frío. El tramo de authorize espera a una persona de todos modos.

¿Por qué Claude puede llamar a osFoundry, pero osFoundry no puede abrir tus chats de Claude?

En este montaje quien llama es el host. Abre la conexión, lista las herramientas y decide cuándo llamar a una. El servidor responde. Nada en este montaje le da al servidor un acceso a las conversaciones del host. El plan de osFoundry lo dice en su tabla de capacidades: abrir o enumerar chats personales arbitrarios de ChatGPT/Claude es "No", con "No general host API is provided for this".

Eso condiciona las herramientas. Con link_current_chat, es el propio chat el que crea un enlace desde dentro. Su etiqueta la declara el propio chat, y osFoundry la usa para enrutar, no como identidad. El trabajo asignado a un chat de Claude enlazado espera hasta que el usuario abre ese chat y le pide que lo revise. ChatGPT tiene MCP Events para chats suscritos, y el plan de osFoundry lo trata como algo específico de ese host.

El lado del servidor es dueño de todas las decisiones sobre datos, porque es el único que conoce el estado actual de un proyecto. El lado del host es dueño de todas las decisiones sobre cuándo actuar y si preguntar al usuario. La comprobación en cada llamada es lo que permite que el servidor siga siendo correcto cuando esos dos lados se desincronizan.

Si lo montas tú

Pon resource_metadata en el WWW-Authenticate del 401 y sirve la RFC 9728 en /.well-known/oauth-protected-resource/<resource path>. Un cliente que construye la URL a mano puede equivocarse. La cabecera se lo ahorra a todos los clientes.
Decide qué es público antes del inicio de sesión. osFoundry expone initialize y tools/list y protege tools/call. Si las descripciones de tus herramientas filtran algo sobre los tenants, protege también tools/list.
Declara un scope y readOnlyHint por herramienta. Los hosts pueden construir con ellos las peticiones de confirmación, y un 403 insufficient_scope le da al host algo concreto que volver a pedir.
Mantén el token pequeño: quién, qué conexión, qué scopes. Vuelve a leer en cada llamada el workspace, la pertenencia al proyecto, el proyecto del recurso y el rol actual de quien aprobó, para que revocar y "mover a otro proyecto" funcionen en la siguiente llamada.
Devuelve las denegaciones sobre recursos como resultados de herramienta, no como 401/403. Otro token no va a arreglar "esta Note está en el proyecto B".
Haz que las escrituras lleven expected_version y una clave de idempotencia. Los hosts reintentan, y los modelos repiten llamadas.

La parte MCP de la especificación está en la página de autorización de MCP. La definición breve de osFoundry está en su entrada del glosario sobre MCP.

How does a Claude custom connector find osFoundry's OAuth server, and why is access checked on every call?

BBT — Fri, 06 Nov 2026 10:29:55 +0000

This is what a remote MCP client gets when it calls an osFoundry tool without a token. The request was sent with curl from a Mac in Tokyo on 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\", ..."]}}}

That one header is enough for Claude's custom connector, or ChatGPT's developer-mode MCP connection, to find the sign-in page. The user only ever pastes the URL. Everything below is from unauthenticated requests to the live endpoint, plus a small Python rebuild, run locally, that measures the part a curl can't show: what happens to access after sign-in.

What does the client see before it has a token?

Three calls, three different answers:

Request	Status	What comes back
`initialize`	200	protocol `2025-06-18`, server `osfoundry 0.1.0`, plus instructions
`tools/list`	200	59 tools, 45,368 bytes
`tools/call`	401	`WWW-Authenticate` pointing at the resource metadata
`GET` on the endpoint	405	no SSE stream on GET

The handshake and the tool catalogue are public. Only calling a tool needs a token. That lets the host show the user which tools exist before anyone signs in. Nothing in the catalogue is user data, and the instructions string in initialize is generic:

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

Every tool in tools/list declares the OAuth scope it needs and whether it only reads:

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

Across the 59 tools: 30 need osfoundry:read and are marked readOnlyHint: true, 26 need osfoundry:write, and 3 need osfoundry:run (request_session_run, run_graph_session, cancel_graph_run). A host can use readOnlyHint to decide which calls need an approval prompt.

Where does the 401 send it?

resource_metadata follows RFC 9728 (OAuth Protected Resource Metadata). The well-known suffix goes after the host, with the resource path appended. It is not appended to the resource URL:

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"]}

If you build a client by hand, that 404 is the mistake you'll make first. Read the URL from the header instead of building it yourself.

What does the authorization server say about itself?

/.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}

Read it as a chain of decisions. There's a registration_endpoint, so the host can register itself (dynamic client registration) and the user never handles a client ID. Token auth is none, so the host is a public client with no client secret, and PKCE with S256 is what ties the code to the client that asked for it. iss in the authorization response guards against mix-ups when a host talks to several authorization servers.

The authorize step sends the browser to osFoundry's consent page, https://osfoundry.io/external-assistant-authorize. There the user picks exactly one workspace and ticks "I approve connecting this assistant to …". The approval names a workspace and nothing else. A new connection has no projects. The owner adds them afterwards in the app (key icon → Connected → Add to project).

Why isn't the scope enough?

A scope is fixed when the token is minted. osfoundry:write says the connection may perform write-type actions. It doesn't say which Note, and it can't know that the Note moved to another project ten minutes ago. osFoundry's design notes list what gets re-read on each call: connection status, workspace, project membership, the resource's current project and ACL, channel membership or session role, the tool, and the OAuth scope. The person who approved the connection also has to still hold edit rights on the item. Removal or reassignment "takes effect immediately".

The alternative is to put the project list into the token, or into a cache keyed by the token, and trust it until expiry. That is cheaper to write. The rebuild below implements both so the difference in behaviour can be measured.

The rebuild

No Claude binary is involved. client.py plays the host and server.py plays the MCP server. Both use only the standard library, about 280 lines together, and ran on Python 3.9.6 on an Apple M1. The server implements initialize, tools/list and tools/call over plain HTTP JSON-RPC, the two well-known documents, /authorize (the consent page is auto-approved for one workspace), and /token with S256 PKCE. A few /admin/* routes stand in for the owner's clicks in the Connected tab.

The check that runs before every tool:

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

The client starts with no token. It calls a tool, takes the 401, parses resource_metadata out of WWW-Authenticate, fetches both metadata documents, runs authorize and token with a fresh PKCE verifier, and then works through the scenario:

$ 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

The same client against CHECK=token_only. Here the token carries the project list from its last 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"

Steps 1–7 are identical. Step 7 is still denied in the token-only design because the note's project is looked up live. The token-only design only goes stale on facts that live in the token. Steps 8 and 9 are the ones the owner cares about: they removed the project, then they revoked the connection, and the chat kept reading. In the token-only design that lasts until the token expires, which is expires_in: 3600 in this rebuild.

Denials split across two layers. A missing scope is a protocol-level failure: 403 with error="insufficient_scope" and the needed scope in WWW-Authenticate, so a host could ask for more. Anything about which item is involved is a normal tool result with isError: true. Re-authorising wouldn't fix those, so there's no point telling the host to try.

What does the per-call check cost?

Measured with time.perf_counter_ns() around access() inside the server, 1,000 calls per run (500 allowed, 500 denied), on a Mac that was also running other jobs:

	access() median	access() p99	loopback tool call, median
per-call check, 6 runs	1.3–1.6 µs	6.1–7.0 µs	0.43–0.78 ms
token-only, 3 runs	0.7–1.6 µs	3.5–7.7 µs	0.35–1.36 ms (2 runs)

In memory, the recheck is lost in the noise of a loopback HTTP call. A real server does database lookups instead of set membership, so its cost is higher. This rebuild can't measure that, so no number is given for it. For scale, the network leg to the live endpoint from Tokyo is about 500 ms to 800 ms per request in urllib with a new TLS connection each time (n=10 each: initialize median 790 ms, tools/list 816 ms, the 401 tools/call 565 ms, each metadata document about 520–530 ms). The access check isn't where a connector spends its time.

The discovery itself was 5 HTTP round trips locally: 401, resource metadata, server metadata, authorize, token. That took 7.5–13.4 ms in seven runs and 34 ms once while the Mac was busy. Against the live server, the three GET/POST legs you can make without credentials add up to roughly 1.6 s from a cold start. The authorize leg waits on a human anyway.

Why can Claude call osFoundry, but osFoundry can't open your Claude chats?

In this setup the host is the caller. It opens the connection, lists tools and decides when to call one. The server answers. Nothing in this setup gives the server a handle on the host's conversations. osFoundry's plan states it in its capability table: opening or enumerating arbitrary personal ChatGPT/Claude chats is "No", with "No general host API is provided for this".

That shapes the tools. link_current_chat has the chat create a link from inside the chat. Its label is self-reported, and osFoundry uses it as routing, not as identity. Work assigned to a linked Claude chat waits until the user opens that chat and asks it to check. ChatGPT has MCP Events for subscribed chats, and osFoundry's plan treats that as host-specific.

The server side owns every decision about data, because it's the only side that knows the current state of a project. The host side owns every decision about when to act and whether to ask the user. The per-call check is what lets the server stay correct when those two sides drift apart.

If you wire this up yourself

Put resource_metadata in the 401's WWW-Authenticate and serve RFC 9728 at /.well-known/oauth-protected-resource/<resource path>. A client that builds the URL by hand can get it wrong. The header saves every client from that.
Decide what's public before sign-in. osFoundry exposes initialize and tools/list and guards tools/call. If your tool descriptions leak anything about tenants, guard tools/list too.
Declare a scope and readOnlyHint per tool. Hosts can build approval prompts from them, and a 403 insufficient_scope gives the host something concrete to re-request.
Keep the token small: who, which connection, which scopes. Re-read workspace, project membership, the resource's project and the approver's current role on every call, so that revoke and "move to another project" work on the next call.
Return resource denials as tool results, not as 401/403. A different token won't fix "this Note is in project B".
Make writes carry expected_version and an idempotency key. Hosts retry, and models re-issue calls.

The MCP side of the spec is on the MCP authorization page. osFoundry's own short definition is in its glossary entry for MCP.