接入 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

无头场景（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。

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 命令。

故障排查

下一步