如何用自訂連接器把 Claude 聊天連到你的 osFoundry 專案

照著做完之後，claude.ai 上一段普通的 Claude 對話，就能打開你某個 osFoundry 專案裡的 Notes、知識庫和 Records，根據內容回答，並在該專案的討論頻道發文。經過你的核准，它也能編輯這些內容。你照常登入 Claude 即可。每一次工具呼叫，都由 osFoundry 決定這段聊天能碰哪些東西，而且每次呼叫都會列在 osFoundry 中該連線的 Recent activity 裡。ChatGPT 也用同樣的方式、同一個伺服器位址連線。

誰負責什麼

	Claude 這邊	osFoundry 這邊
登入	你的 Claude 帳號，不變	你的 osFoundry 帳號核准連線一次，限一個工作區
誰執行模型	Claude，就在你平常用的聊天裡	沒有。這條路徑上沒有模型，也沒有供應商金鑰
工具在哪裡執行	Claude 送出工具呼叫	`api.osfoundry.io` 先檢查存取權限再執行
能存取什麼	伺服器回傳的內容	你加入此連線的專案，加上你邀請它加入的頻道
核准	Claude 本身的工具權限提示	GitNest 與 Room 的變更會在「Needs your approval」等待
資料留在哪裡	回答留在你的 Claude 聊天裡	Notes、records 和文章留在 osFoundry。僅限本機的項目永遠不會離開裝置

設定

1. 在 osFoundry 建立連線

在 osFoundry 中，點標頭的鑰匙圖示，打開 Connected 分頁。面板標題是「Connected agents」，並顯示你目前所在的工作區。在「Connect in three steps」下方：

Assistant：選擇 Claude
Display name：任何你之後認得出來的名稱，例如 Claude research
點 Add assistant（新增助理）

新的連線會顯示「Setup pending. This assistant cannot read or change anything yet.」。用旁邊的 Copy 按鈕複製 Server address：

https://api.osfoundry.io/api/v1/external-mcp

範例：按下 Add assistant 後的 Connected 分頁，顯示伺服器位址和待設定的連線

2. 在 Claude 中加入自訂連接器

在 Claude 中打開 Customize → Connectors，用這個網址新增一個自訂連接器。如果是 Team 或 Enterprise 方案，要先由組織擁有者在 Organization settings → Connectors 中新增，接著每位成員各自連線。Anthropic 針對遠端 MCP 連接器的步驟，請見 Claude 自訂連接器指南。

按下 Connect 後，Claude 會自己找到 osFoundry 的登入頁面。你不需要貼上任何 client ID 或金鑰。

3. 核准一個工作區

瀏覽器會來到 https://osfoundry.io/external-assistant-authorize，頁面標題是「Connect an agent」。頁面會顯示助理的 client 和它要返回的主機，接著要求你選擇：

Workspace to connect：一個工作區。第二個工作區需要另建一個連線。
Requested capabilities，以白話列出：「Read supported resources in projects you add」、「Change supported resources where you have edit access」、「Run sessions where you grant a runner role」。
Connection：選「Use pending: Claude research」，讓它接上步驟 1 建立的連線；或保留「Create a new connection」。
勾選「I approve connecting this assistant to <工作區>」，再按 Connect。

接著你會被導回 Claude。連線已經生效，但還什麼都看不到。新連線一開始的專案數是零。

4. 加入專案

回到鑰匙圖示 → Connected，選取這個連線。現在它顯示「Connected.」。在 Projects 下選一個專案，點 Add to project。

範例：已加入專案的連線，下方是它連結的聊天

這樣就授予了該專案中受支援的已同步內容：Notes、知識庫、Record 頻道、雲端 Room、指派給該專案的 GitNest 儲存庫，以及專案的討論頻道。之後再加進專案的內容也會包含在內。一般的 Message 頻道是分開的。聊天需要閱讀和回覆的每一個頻道，都要用 Message channels → Choose a Message channel → Invite 個別邀請。

Tools 區塊寫著「All supported tools are on by default.」。把不想給這個連線的工具取消勾選，再點 Save tools。

範例：Claude 連線的 Tools 清單，預設全部開啟

5. 在聊天中開啟

在 Claude 對話中打開 + 選單 → Connectors，啟用 osFoundry 連接器。接著用平常的話提問就行。

實際跑一次

下面的提示和回答是示範專案中的範例內容。工具名稱和參數名稱，都是正式伺服器在 tools/list 中公布的。在 claude.ai 裡，這些呼叫會顯示在連接器名稱下方。如果你把同一個網址以 osfoundry 的名稱加到 Claude Code，同樣的工具就會顯示為 mcp__osfoundry__list_project_resources 等。

範例 你：用 osFoundry 看一下，Q3 上線檢查清單還有哪些沒完成？ 順便查支援 KB 有沒有跟它矛盾的地方，然後把 「pricing page」這筆 record 標成 Ready。 Claude → list_granted_resources {} ← 1 個已連線專案："Launch Q3"（工作區） Claude → list_project_resources {"project_id": "…", "resource_type": "note", "search": "checklist"} ← Note "Q3 launch checklist" Claude → list_note_tabs {"note_id": "…"} ← 分頁：Note（文字）、Sheet "Owners" Claude → read_note_tab {"note_id": "…", "tab_id": "…"} ← 9 個項目，3 個未勾選 Claude → search_knowledge_base {"knowledge_base_id": "…", "query": "refund window"} ← 文章 "Refund policy"（2 天前更新） Claude → read_record_item {"record_channel_id": "…", "item_id": "…"} ← "pricing page"，status Draft，version … Claude → edit_record_item {"record_channel_id": "…", "item_id": "…", "values": {"status": "Ready"}, "expected_version": "…", "idempotency_key": "…"} [Claude 請你允許這次工具呼叫 → Allow] ← 已儲存，新的 version … Claude：還有三項沒完成：媒體禁發日期、FAQ 翻譯， 以及 pricing page 上關於退款的那一行。檢查清單寫 14 天， KB 文章 "Refund policy" 寫 30 天。 pricing page 這筆 record 我已經標成 Ready。

這段紀錄裡有兩個細節是刻意設計的。edit_record_item 需要 read_record_item 回傳的 version，所以如果這筆 record 在中間被改過，就會被拒絕，而不是被覆蓋。重複的 idempotency_key 會回傳第一次的結果，所以重試的呼叫不會寫入兩次。

界線在哪裡

osFoundry 無法打開你的 Claude 聊天。MCP 連線讓 Claude 在它判斷需要時呼叫 osFoundry 的工具。反方向，osFoundry 沒有任何 API 可以列出、讀取或開啟個人對話。把聊天連結到專案的工具（link_current_chat）接收的是聊天自己回報的標籤，osFoundry 把它當作路由提示，而不是經過驗證的身分。同樣的道理，Claude 不會收到來自 osFoundry 的背景通知。只有在你打開對話並提出要求時，它才會動作。

僅限本機的資料會留在本機。伺服器在自己的 initialize 回應中就這麼寫：「Local-only data is unavailable to cloud clients.」。本機 Room、本機 Graph 工作階段，以及從未同步的內容，連線都看不到。分享桌面版 Graph 工作階段是同一個分頁中的另一個開關，而且桌面版必須開著並已登入。

存取權限是每次呼叫都檢查，而不是只在登入時檢查。每次呼叫都會比對連線的狀態、它的工作區、專案目前的成員、該項目此刻位於哪個專案，以及你自己對該項目的角色。把一則 Note 移到別的專案、移除專案，或點 Revoke connection，下一次呼叫就會被拒絕。編輯也要求你，也就是核准連線的人，仍然擁有編輯權限。

有些寫入會變成提案。GitNest 工作、change set、檔案匯入、pull request 和 Room 應用程式安裝，都會經過 propose_… 工具。它們會在 Connected 分頁的「Needs your approval」下等待，你可以先看到目標儲存庫或 Room 以及相關檔案，再選擇 Approve 或 Decline。Claude 永遠拿不到你的 Git 供應商 token 或任何機密值。

Message 頻道需要邀請。加入專案只會開放該專案的討論頻道。其他每個頻道都需要明確的 Invite，私人頻道則需要由擁有者邀請。