接入 AI 工具（MCP）

每個 ObjectOS 部署天生就是一個 MCP 伺服器。執行時在 /api/v1/mcp 上提供 Model Context Protocol 服務——預設開啟，無需安裝外掛，無需配置步驟。你的物件和已暴露的動作在定義的那一刻就成為帶型別的工具；剩下唯一要做的就是接入一個客戶端並驗證它能用。

要關閉這個入口，設定 OS_MCP_SERVER_ENABLED=false——端點將返回 404，Setup → Connect an Agent（接入 Agent）頁面也隨之消失。

在 ObjectOS Cloud 上正好相反：每個環境的 MCP 端點在所有者或管理員開啟之前都是關閉的，並且每個套餐都有請求上限。參見在 ObjectOS Cloud 上。

本頁講的是把外部 AI 工具接入你的應用。服務端 AI 棧——聊天 Provider、Embedder、RAG，以及在程式碼中顯式註冊 MCP 伺服器外掛——參見 AI 服務。

Claude Code（一條命令）

互動式客戶端使用 OAuth——每個部署本身就是一個 OAuth 2.1 授權伺服器，因此不存在需要管理員簽發再分發的憑據。第一次工具呼叫會開啟瀏覽器登入，你以自己的身份接入：

# local dev server
claude mcp add --transport http my-app http://localhost:3000/api/v1/mcp

# a deployed instance
claude mcp add --transport http my-app https://your-deployment.example.com/api/v1/mcp

在本地開發伺服器上，這條命令甚至不用你親手輸入：自 16.0 起，os dev 的啟動橫幅會列印 MCP 端點、agent skill 的 URL，以及一條可直接複製貼上的 claude mcp add 命令。

無頭場景（CI、容器）跳過 OAuth，改為附加 API Key：

claude mcp add --transport http my-app https://your-deployment.example.com/api/v1/mcp \
  --header "x-api-key: osk_..."

Claude Desktop 與 claude.ai

Settings → Connectors → Add custom connector（設定 → 聯結器 → 新增自定義聯結器），然後貼上 MCP URL（https://your-deployment.example.com/api/v1/mcp）。首次使用時會走同樣的瀏覽器登入流程。

任意 MCP 客戶端（.mcp.json）

讀取 mcpServers 對映的客戶端以同樣方式接入。使用 API Key：

{
  "mcpServers": {
    "objectstack": {
      "type": "http",
      "url": "https://your-deployment.example.com/api/v1/mcp",
      "headers": { "x-api-key": "osk_..." }
    }
  }
}

無頭場景：API Key

在 Setup → Connect an Agent（接入 Agent，那裡還提供各客戶端可直接複製貼上的接入片段）中簽發 Key，或通過 REST：

curl -b cookies.txt -X POST https://your-deployment.example.com/api/v1/keys
# → { "key": "osk_..." }  — shown once; store it in your secret manager

每次請求以三種等價形式之一攜帶它：

OAuth 要求 TLS——純 HTTP 部署（localhost 除外）會回退到僅 API Key 模式：瀏覽器登入通道被停用，而不是被允許以不安全的方式執行。

對於長期整合，把 Key 繫結到帶最小許可權集的專用服務使用者——參見服務賬號與 API Key。

stdio 傳輸（16.0）

除了 HTTP，執行時還可以通過 stdio 提供 MCP 服務，供以子程序方式拉起伺服器的宿主使用。自 16.0（ADR-0101）起，stdio 擁有自己的開關，並且始終以真實身份執行：

• OS_MCP_STDIO_ENABLED=true 開啟 stdio 自動啟動（預設關閉）。OS_MCP_SERVER_ENABLED 現在只管 HTTP 入口——OS_MCP_SERVER_ENABLED=true 同時拉起 stdio 的舊行為還會保留一個版本，並伴隨棄用警告。
• stdio 必須配置 OS_MCP_STDIO_API_KEY=osk_...。該 Key 通過與 HTTP、REST 完全相同的驗證 + 授權鏈解析，因此物件許可權、記錄訪問、欄位級安全和租戶隔離對 stdio 呼叫的作用與 /api/v1/mcp 完全一致——並且每次讀取都會重新解析 Key，吊銷立即生效。
• 該傳輸是 fail-closed 的：開啟自動啟動卻沒有可解析的 Key，啟動會直接被拒絕；刻意不提供任何無身份回退，也沒有 system 旁路。若需要完整許可權，請在平臺管理員或專用服務身份上簽發 Key。

Agent 能得到什麼

十一個數據、動作與創作工具，由你的後設資料生成：

要了解的兩條暴露規則：

• 物件自動暴露——但 sys_* 系統物件除外，它們以 fail-closed 方式被攔截。
• 動作需要作者顯式選擇加入：ai: { exposed: true } 加上不少於 40 個字元的 ai.description，且該動作必須可以在無 UI 的情況下呼叫（帶 body 或已註冊 handler 的 script，或 flow）。

許可權強制執行

• **每次呼叫都以呼叫者身份執行。**MCP 橋接解析的執行上下文與 REST 請求相同，因此物件許可權、記錄訪問和欄位級安全對 Agent 的作用與對 UI 中的真人完全一致。結果稀疏或寫入被拒，通常意味著治理在正常工作，而不是連線壞了。
• **OAuth scope 會收窄工具集。**Token 攜帶 data:read、data:write 和 actions:execute 這些 scope——不在已授予 scope 內的工具，在該會話中根本不會被註冊。API Key 和會話呼叫者獲得完整工具集，但每次呼叫仍會做許可權檢查。第四個 scope metadata:write 只在部署提供構建工具的地方才開放這些工具：在 ObjectOS Cloud 上，參見用 Agent 構建。
• 動作體一經呼叫即作為可信應用程式碼執行（ai.exposed 門檻和 requiredPermissions 在呼叫時檢查）。把編寫動作當作值得程式碼評審的行為——那才是真正的安全邊界。
• 動作還可以宣告 ai.requiresConfirmation；看起來具有破壞性的動作預設要求確認。

驗證連線

問 Agent 一個只有即時 schema 才能回答的問題：

What objects does this app have, and what fields does the main one carry?

你應該看到 list_objects 和 describe_object 被觸發。Agent 的自然工作模式是 list_objects → describe_object → query_records → run_action——四者都能跑通，連線就完全就緒了。

配上應用的 skill 檔案，Agent 的表現會明顯更好：從 GET /api/v1/mcp/skill 下載它，或安裝官方 Claude 外掛（claude plugin marketplace add objectstack-ai/claude-plugin），後者打包了該 skill 和一個引導式的 /objectstack:connect 命令。

在 ObjectOS Cloud 上

一旦端點開啟，上述所有內容都適用於 ObjectOS Cloud 環境。有四處不同：開關、上限、連線資訊所在的位置，以及 Agent 可以把應用構建為草稿。

開啟 AI Agent 訪問

把環境的資料暴露給外部 AI 客戶端是組織的決定，因此在 ObjectOS Cloud 上，端點在每個套餐上都按環境預設關閉（裁定見 cloud#1248）。

1. 在雲控制台中，開啟該環境的頁面及其 Settings（設定）標籤頁。在 Access and sign-in 下，AI agent access (MCP) 一行顯示 Now: off。
2. 選擇 Enable AI Agent Access 並確認。只有組織的所有者和管理員會看到這個選項。
3. 稍等幾秒：環境會自行獲取變更，無需重新部署。隨後這一行顯示 Now: on，環境的 Overview 也會顯示同樣的狀態。

開啟後，Connect an Agent 會出現在環境自己的控制台中，有兩個入口開啟的是同一個頁面：Account → Developer，所有已登入使用者都能看到；以及 Setup → Integrations，擁有 Manage Platform Settings 的使用者能看到。該頁面顯示環境的端點 URL——其地址後接 /api/v1/mcp——以及每個客戶端的接入卡片、skill 檔案和 API Key 簽發器。

接入

互動式客戶端使用上文描述的瀏覽器登入：Agent 隨後以你的身份行事，處於你自己的許可權、行級安全和欄位訪問之內。無頭客戶端——CI、指令碼——使用在 Connect an Agent 的 API keys · headless 卡片中簽發的 API Key；Key 以簽發它的人的身份行事，並且永遠不能替其他人簽發。

用 Agent 構建

Agent 還可以構建應用：建立和修改它的物件、欄位、檢視、頁面、儀表盤、流程和動作，而不只是它的記錄。它構建的一切在有人釋出之前都是草稿。

**請求 metadata:write。**構建工具只提供給授權中包含 metadata:write scope 的瀏覽器登入。環境會把它與 data:read、data:write 和 actions:execute 一起公佈，因此請求環境所公佈 scope 的客戶端，在你登入時就會獲得它。如果你的客戶端按名稱請求 scope，加上 metadata:write；如果你登入時沒有它，重新連線。API Key 永遠不會開放構建工具。該 scope 只開放工具，僅此而已：每次呼叫都以你的身份執行，並需要你在該環境中擁有 manage_metadata 或 studio.access 許可權，與 AI Builder 相同。

這些工具做什麼。

每次呼叫都要指明它的包（packageId 或 targetApp）；沒有任何東西會把工作包從一次呼叫帶到下一次。這裡不提供 toggle_flow 和 test_flow，因為 Agent 暫存的流程是不會執行的草稿。

**每次寫入都是草稿，在每個環境中都是。**包括生產環境。沒有工具會發布，也沒有工具會丟棄。每次寫入的結果都會說明變更尚未生效，並帶有一個 staged 塊，列出這些草稿以及釋出它們的地址。

**由人在 Studio → Changes 中釋出。**在 Studio 中開啟該包及其 Changes 檢視（環境中的 /_console/studio/<package>/data），評審 Agent 暫存的內容，然後釋出或丟棄。告訴你它已經建立了某樣東西的 Agent，其實是起草了它；釋出之後應用才會顯示它。

刪除或收窄需要 confirm: true。delete_field、modify_field、apply_edit 和 update_metadata 接受一個 confirm 引數。會刪除欄位、改變欄位型別或從流程中刪去步驟的呼叫，在沒有 confirm: true 時什麼都不會暫存，並且回答會指出釋出它將失去什麼。只做新增的變更永遠不需要它。

**Agent 能構建多少。**構建呼叫也是 MCP 請求，因此請求上限對它們適用。另有兩項上限計入構建（儲存與限制）：

讀取和 verify_build 不計為寫入。超過任一上限後，工具呼叫會以 RATE_LIMIT_EXCEEDED 被拒絕，並附上計數和重置條件：寫入在下一個 UTC 日重置，草稿在釋出或丟棄後重置。

**為什麼我的流程被拒絕？**它用到了 Agent 在這裡無法構建的東西，拒絕資訊會指出是哪一項：Free 上的定時或相對時間流程、Free 上的審批步驟，或者一種需在原始碼中構建並作為包釋出的型別。

Agent 可以構建由記錄變更或按鈕啟動的流程，使用建立、更新和刪除記錄、賦值、判斷、迴圈和等待步驟。定時和相對時間流程在 Team 及以上可以構建，審批步驟也在 Team 及以上可以構建（套餐）。指令碼、Webhook、API 觸發的流程和螢幕流程，以及 script、webhook、API、job、郵件模板、翻譯、主題、外掛、agent、skill 和資料來源這些型別，在任何套餐上都在原始碼中構建。

上限

每個環境的端點接受一定數量的請求，由連線到它的所有 Agent 共享（裁定見 cloud#3203）：

超過上限後，端點以 429 加 Retry-After 和程式碼 RATE_LIMIT_EXCEEDED 應答；訊息會說明觸發了哪個上限以及何時重置。什麼算作一次請求，以及與之並列的草稿和創作寫入上限，參見儲存與限制。開關在套餐變更時保持不變，因此降級或升級永遠不會把它開啟或關閉。

關閉

在同一行中，Disable AI Agent Access 會在幾秒內讓環境停止提供端點，切斷所有已連線的 Agent——瀏覽器登入和 API Key 都一樣。它不會弔銷其他任何東西：

• **API Key 對 REST API 仍然有效。**要停用 Key 本身，從 Account → Developer → API Keys（你自己的）或 Setup → Access Control → API Keys（所有人的，需要 Manage Platform Settings）中刪除它。
• 瀏覽器登入不會被吊銷，但它們的 token 只被 MCP 端點接受，所以端點關閉期間它們什麼也訪問不到。

在 ObjectOS Cloud 上：故障排查

故障排查

下一步