接入 AI 工具（MCP）

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

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

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

Claude Code（一條命令）

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

# 本地开发服务器
claude mcp add --transport http my-app http://localhost:3000/api/v1/mcp

# 已部署的实例
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_..." }  —— 只显示一次；存入你的 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 和會話呼叫者獲得完整工具集，但每次呼叫仍會做許可權檢查。
• 操作體一經呼叫即作為可信應用程式碼執行（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 命令。

故障排查

下一步