From ada28a7dbfbde778a41c7c13a115f3a49987fb5e Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 7 Nov 2026 14:38:44 +0000 Subject: [PATCH] docs(configure/mcp): a new Cloud environment starts with AI agent access on cloud v2.10.0 (cloud#3640, ruled on cloud#3628) creates new environments with AI Agent Access on; the page still said the endpoint is off by default. The enable steps now apply only to an older environment or one that was turned off. The page reverses a capability assertion, so its zh-Hans, zh-Hant and ja siblings are deleted rather than left to state the old default. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012dn2AdARJtc4RgABPH7PHk --- content/docs/configure/mcp.ja.mdx | 235 ------------------------ content/docs/configure/mcp.mdx | 22 ++- content/docs/configure/mcp.zh-Hans.mdx | 235 ------------------------ content/docs/configure/mcp.zh-Hant.mdx | 236 ------------------------- 4 files changed, 15 insertions(+), 713 deletions(-) delete mode 100644 content/docs/configure/mcp.ja.mdx delete mode 100644 content/docs/configure/mcp.zh-Hans.mdx delete mode 100644 content/docs/configure/mcp.zh-Hant.mdx diff --git a/content/docs/configure/mcp.ja.mdx b/content/docs/configure/mcp.ja.mdx deleted file mode 100644 index 9c429d6..0000000 --- a/content/docs/configure/mcp.ja.mdx +++ /dev/null @@ -1,235 +0,0 @@ ---- -title: AI ツールを接続する（MCP） -description: Claude Code、Claude Desktop、または任意の MCP クライアントを ObjectOS アプリに向け、エージェントにあなたの権限モデルのもとでデータを扱わせます。 -editions: [community, cloud, enterprise] -translation: - source_sha: 0bec90d540bb424e11d1cedf6c0532227a9ce328717d2448f1c7fdc8b8291017 - guide_rev: 1 - mode: auto ---- - -すべての ObjectOS デプロイメントは、すでに MCP サーバーです。ランタイムは **`/api/v1/mcp`** で [Model Context Protocol](https://modelcontextprotocol.io) を提供しています。デフォルトで有効で、インストールするプラグインも設定の手順もありません。オブジェクトと公開したアクションは、定義した瞬間に型付きのツールになります。残っている作業は、クライアントを接続して動作を確かめることだけです。 - -> この機能をオフにするには `OS_MCP_SERVER_ENABLED=false` を設定します。するとエンドポイントは 404 を返し、**Setup → Connect an Agent** のページもあわせて消えます。 - -> **ObjectOS Cloud では逆です：** 各環境の MCP エンドポイントは**オーナーまたは管理者が有効にするまでオフ**で、すべてのプランにリクエストの上限があります。[ObjectOS Cloud の場合](#on-objectos-cloud)を参照してください。 - -このページは、*外部の* AI ツールをアプリに接続することについて扱います。サーバー側の AI スタック（チャットのプロバイダー、埋め込み、RAG、コードでの MCP サーバープラグインの明示的な登録）については、[AI サービス](/docs/configure/ai)を参照してください。 - -## Claude Code（コマンド 1 つ） [#claude-code-one-command] - -対話型のクライアントは OAuth を使います。各デプロイメントが独自の OAuth 2.1 認可サーバーなので、管理者が発行した認証情報を受け渡す必要はありません。最初のツールの呼び出しでブラウザのログインが開き、**あなた自身として**接続します。 - -```bash -# 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 エンドポイント、エージェントスキルの URL、そしてそのまま貼り付けられる `claude mcp add` コマンドが表示されます。 - -ヘッドレスで使う場合（CI、コンテナ）は、OAuth を使わずに代わりに [API キー](#headless-api-keys)を付けます。 - -```bash -claude mcp add --transport http my-app https://your-deployment.example.com/api/v1/mcp \ - --header "x-api-key: osk_..." -``` - -## Claude Desktop と claude.ai [#claude-desktop-and-claudeai] - -**Settings → Connectors → Add custom connector** を開き、MCP の URL（`https://your-deployment.example.com/api/v1/mcp`）を貼り付けます。初回の利用時に、同じブラウザのログインを経ます。 - -## 任意の MCP クライアント（`.mcp.json`） [#any-mcp-client-mcpjson] - -`mcpServers` マップを読むクライアントも同じように接続します。API キーを使う場合： - -```json -{ - "mcpServers": { - "objectstack": { - "type": "http", - "url": "https://your-deployment.example.com/api/v1/mcp", - "headers": { "x-api-key": "osk_..." } - } - } -} -``` - -## ヘッドレス：API キー [#headless-api-keys] - -**Setup → Connect an Agent**（クライアントごとにコピーしてすぐ使える接続のスニペットも表示されます）から、または REST でキーを発行します。 - -```bash -curl -b cookies.txt -X POST https://your-deployment.example.com/api/v1/keys -# → { "key": "osk_..." } — shown once; store it in your secret manager -``` - -すべてのリクエストで、同等な 3 つの形式のいずれかで送ります。 - -| ヘッダー | 例 | -|---|---| -| `x-api-key` | `x-api-key: osk_...` | -| `Authorization: ApiKey` | `Authorization: ApiKey osk_...` | -| `Authorization: Bearer` | `Authorization: Bearer osk_...`（`osk_` プレフィックスで認識されます） | - -> OAuth には TLS が必要です。プレーンな HTTP のデプロイメント（`localhost` を除く）は **API キーのみ**にフォールバックします。ブラウザログインの経路は、安全でない状態で動かすことを許すのではなく、無効になります。 - -長期間の連携では、キーを最小限の権限セットを持つ専用のサービスユーザーに結び付けてください。[Service accounts & API keys](/docs/configure/users#service-accounts--api-keys) を参照してください。 - -## stdio トランスポート（16.0） [#the-stdio-transport-160] - -ランタイムは 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 も起動していた旧来の動作は、1 リリースの間、非推奨の警告付きで引き続き機能します。 -- stdio には **`OS_MCP_STDIO_API_KEY=osk_...` が必要です**。キーは HTTP や REST と同じ検証 + 認可の連鎖で解決されるので、オブジェクトの権限、レコードアクセス、フィールドレベルのセキュリティ、テナントのスコープは、`/api/v1/mcp` とまったく同じように stdio の呼び出しにも適用されます。また、キーは読み取りのたびに再解決されるので、失効させると即座に有効になります。 -- このトランスポートは**安全側に倒れて失敗します**。解決できるキーなしに自動起動を有効にすると起動を拒否し、スコープなしのフォールバックや `system` によるすり抜けは意図的に用意されていません。完全な権限が必要なら、プラットフォーム管理者または専用のサービスアイデンティティでキーを発行してください。 - -## エージェントが得るもの [#what-the-agent-gets] - -メタデータから生成される、データ、アクション、作成の 11 個のツールです。 - -| ツール | 働き | -|---|---| -| `list_objects` / `describe_object` | どんなオブジェクトがあり、どんなフィールドを持つかを調べます | -| `query_records` / `get_record` | データを読みます（リストのクエリは、デフォルトで 1 ページあたり 50 行が上限です） | -| `validate_expression` | 数式を保存する*前に*、実際のオブジェクトのスキーマに照らして検査します（16.0）。エラー（素のフィールド参照、候補付きの不明なフィールド）、警告（型の健全性、日付の等価比較の落とし穴）、スコープ内のフィールド / 関数の一覧、推論された結果の型を返します。読み取り専用で、`data:read` のスコープで、`sys_*` では安全側に倒れて失敗します | -| `aggregate_records` | グループ化した集計（アクティブなドライバーがサポートしている場合に登録されます） | -| `create_record` / `update_record` / `delete_record` | データを書き込みます | -| `list_actions` / `run_action` | 業務アクションを名前で見つけて呼び出します | - -知っておくべき公開のルールが 2 つあります。 - -- **オブジェクトは自動的に公開されます。** ただし `sys_*` のシステムオブジェクトは、安全側に倒れてブロックされます。 -- **アクションには作成者のオプトインが必要です。** `ai: { exposed: true }` と 40 文字以上の `ai.description` を指定し、アクションが UI なしで呼び出せる（本体または登録済みのハンドラーを持つ `script`、または `flow`）必要があります。 - -## 権限の強制 [#permission-enforcement] - -- **すべての呼び出しは呼び出し元として実行されます。** MCP のブリッジは REST のリクエストと同じ実行コンテキストを解決するので、オブジェクトの権限、[レコードアクセス](/docs/configure/permissions/record-access)、[フィールドレベルのセキュリティ](/docs/configure/permissions/field-level-security)は、UI で人に適用されるのとまったく同じようにエージェントに適用されます。結果が少なかったり書き込みが拒否されたりするのは、たいていは接続が壊れているのではなく、ガバナンスが*機能している*ということです。 -- **OAuth のスコープはツールの集合を絞り込みます。** トークンは `data:read`、`data:write`、`actions:execute` のスコープを持ち、付与されたスコープの外にあるツールは、そのセッションでは登録すらされません。API キーとセッションの呼び出し元は完全な集合を得ますが、やはり呼び出しごとに権限がチェックされます。4 つ目のスコープ `metadata:write` は、デプロイメントがビルドツールを提供している場合にだけそれを提供します。ObjectOS Cloud では [エージェントで構築する](#build-with-an-agent)を参照してください。 -- **アクションの本体は、呼び出されると信頼されたアプリのコードとして実行されます**（`ai.exposed` のゲートと `requiredPermissions` は*呼び出し*時にチェックされます）。アクションを書くことはコードレビューに値する行為として扱ってください。それが本当のセキュリティの境界です。 -- アクションは `ai.requiresConfirmation` を宣言することもできます。破壊的に見えるアクションは、デフォルトでそれを必要とします。 - -## 接続を確認する [#verify-the-connection] - -稼働中のスキーマでしか答えられないことをエージェントに尋ねます。 - -```text -What objects does this app have, and what fields does the main one carry? -``` - -`list_objects` と `describe_object` が呼び出されるはずです。エージェントの自然な作業パターンは `list_objects` → `describe_object` → `query_records` → `run_action` です。4 つすべてが動けば、接続は完全に機能しています。 - -> エージェントは、アプリの**スキルファイル**があると目に見えてうまく動きます。`GET /api/v1/mcp/skill` からダウンロードするか、スキルとガイド付きの `/objectstack:connect` コマンドを同梱した[公式の Claude プラグイン](https://github.com/objectstack-ai/claude-plugin)（`claude plugin marketplace add objectstack-ai/claude-plugin`）をインストールしてください。 - -## ObjectOS Cloud の場合 [#on-objectos-cloud] - -ここまでの内容はすべて、エンドポイントが有効になった ObjectOS Cloud の環境に当てはまります。異なるのは 4 点です。スイッチ、上限、接続の詳細がある場所、そしてエージェントがアプリをドラフトとして構築できることです。 - -### AI エージェントのアクセスを有効にする [#turn-on-ai-agent-access] - -環境のデータを外部の AI クライアントに公開するのは組織の判断なので、ObjectOS Cloud ではエンドポイントは、すべてのプランで、環境ごとに**デフォルトでオフ**です（[cloud#1248](https://github.com/objectstack-ai/cloud/issues/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** が現れます。同じページを開く場所が 2 つあります。サインインしているすべてのユーザー向けの **Account → Developer** と、Manage Platform Settings を持つユーザー向けの **Setup → Integrations** です。そのページには、環境のエンドポイントの URL（環境のアドレスの後に `/api/v1/mcp`）、クライアントごとの接続カード、スキルファイル、API キーの発行機能が表示されます。 - -### 接続する [#connect] - -対話型のクライアントは、上で説明したブラウザのサインインを使います。するとエージェントは、あなた自身の権限、行レベルセキュリティ、フィールドアクセスの範囲内で、**あなた**として動作します。ヘッドレスのクライアント（CI、スクリプト）は、**Connect an Agent** の **API keys · headless** カードで発行した [API キー](#headless-api-keys)を使います。キーは発行した人として動作し、ほかの誰かのために発行することは決してできません。 - -### エージェントで構築する [#build-with-an-agent] - -エージェントは**アプリを構築する**こともできます。レコードだけでなく、オブジェクト、フィールド、ビュー、ページ、ダッシュボード、フロー、アクションを作成し、変更できます。構築したものはすべて、人が公開するまでは**ドラフト**です。 - -**`metadata:write` を求めます。** ビルドツールは、付与に `metadata:write` スコープを含むブラウザのサインインにだけ提供されます。環境は `data:read`、`data:write`、`actions:execute` と並べてこれを通知するので、環境が通知するスコープを求めるクライアントなら、サインインしたときにこれを得られます。クライアントがスコープを名前で求める場合は `metadata:write` を加えてください。これなしでサインインした場合は、接続し直してください。[API キー](#headless-api-keys)でビルドツールが開くことはありません。このスコープはツールを開くだけで、それ以上のことはしません。すべての呼び出しはあなたとして実行され、[AI Builder](/docs/build/ai-builder) と同じく、その環境での `manage_metadata` または `studio.access` 権限が必要です。 - -**ツールの働き。** - -| ツール | 働き | -|---|---| -| `get_authoring_rules`、`get_metadata_schema` | この環境が従う構築のルールと、メタデータの種類の形 | -| `list_metadata`、`describe_metadata`、`list_packages`、`get_package` | 環境が現在保持しているもの | -| `propose_blueprint`、`apply_blueprint` | 説明からアプリや機能を設計し、その設計全体をステージングします | -| `create_object`、`add_field`、`modify_field`、`delete_field` | オブジェクトとフィールドを変更します | -| `create_metadata`、`update_metadata`、`apply_edit` | 環境が構築する任意の種類を作成する、1 つを変更する、または既存のアプリに構造化された編集を適用します | -| `create_seed` | サンプルデータを追加します | -| `create_package` | 構築先のパッケージを作成します | -| `verify_build` | ドラフトをプラットフォームのルールに照らしてチェックし、拒否されるものを報告します | - -各呼び出しは自分のパッケージ（`packageId` または `targetApp`）を指定します。ある呼び出しから次の呼び出しへ作業中のパッケージが引き継がれることはありません。`toggle_flow` と `test_flow` はここでは提供されません。エージェントがステージングするフローは、実行されないドラフトだからです。 - -**すべての書き込みは、どの環境でもドラフトです。** 本番も含みます。公開するツールも、破棄するツールもありません。各書き込みの結果は、変更がまだ有効ではないことを伝え、ドラフトとそれらが公開される場所を示す `staged` ブロックを持ちます。 - -**公開するのは人で、Studio → Changes で行います。** Studio でパッケージとその **Changes** ビュー（環境内の `/_console/studio//data`）を開き、エージェントがステージングしたものを確認して、公開または破棄します。何かを作成したと言うエージェントは、それをドラフトにしたということです。アプリに表示されるのは公開されてからです。 - -**削除や絞り込みには `confirm: true` が必要です。** `delete_field`、`modify_field`、`apply_edit`、`update_metadata` は `confirm` 引数を取ります。フィールドを削除する、フィールドの型を変える、フローからステップを外すような呼び出しは、`confirm: true` がなければ何もステージングせず、公開すると何が失われるかを答えます。追加するだけの変更には決して必要ありません。 - -**エージェントがどれだけ構築できるか。** ビルドの呼び出しは MCP のリクエストなので、[リクエストの上限](#limits)が適用されます。さらに 2 つの上限が構築を数えます（[ストレージと上限](/docs/cloud/storage-and-limits#drafts-and-authoring-writes)）。 - -| | Free | Team 以上 | -|---|---|---| -| MCP 経由のビルドの書き込み（環境ごと、UTC の 1 日あたり） | 200 | 2,000 | -| 環境ごとの未公開のドラフト（作成方法を問わず） | 500 | 500 | - -読み取りと `verify_build` は書き込みとして数えられません。どちらかの上限を超えると、ツールの呼び出しは `RATE_LIMIT_EXCEEDED`、その数、そして何でリセットされるかとともに拒否されます。書き込みは UTC の翌日に、ドラフトは公開または破棄でリセットされます。 - -> **フローが拒否されるのはなぜ？** エージェントがここでは構築できないものを使っており、拒否の理由がそれを示します。Free でのスケジュールまたは相対時間のフロー、Free での承認ステップ、またはソースで構築して[パッケージ](/docs/build/packages)として公開する種類です。 - -エージェントが構築するのは、レコードの変更またはボタンで開始するフローで、レコードの作成、更新、削除、割り当て、判断、ループ、待機のステップから構成されます。スケジュールと相対時間のフローは Team 以上で、承認ステップも Team 以上で構築できます（[プラン](/docs/cloud/plans-and-seats)）。スクリプト、Webhook、API で起動するフローと画面フロー、そしてスクリプト、Webhook、API、ジョブ、メールテンプレート、翻訳、テーマ、プラグイン、エージェント、スキル、データソースの種類は、どのプランでもソースで構築します。 - -### 上限 [#limits] - -各環境のエンドポイントが受け付けるリクエストの数は決まっており、それに接続しているすべてのエージェントで共有されます（[cloud#3203](https://github.com/objectstack-ai/cloud/issues/3203) で決定）。 - -| プラン | 1 分あたり | UTC の 1 日あたり | -|---|---|---| -| Free | 20 | 1,000 | -| Team 以上 | 120 | 1 日の上限なし | - -上限を超えると、エンドポイントは `Retry-After` とコード `RATE_LIMIT_EXCEEDED` とともに `429` で応答します。メッセージには、どの上限に達したか、いつリセットされるかが示されます。何がリクエストとして数えられるか、そしてそれと並ぶドラフトと作成の書き込みの上限は、[ストレージと上限](/docs/cloud/storage-and-limits#mcp-limits)にあります。スイッチはプランの変更を越えて保持されるので、ダウングレードやアップグレードによってオンやオフになることはありません。 - -### オフにする [#turn-it-off] - -同じ行の **Disable AI Agent Access** は、数秒以内に環境がエンドポイントを提供するのを止め、ブラウザのサインインと API キーのどちらも含めて、接続しているすべてのエージェントを切断します。それ以外のものは何も失効させません。 - -- **API キーは REST API では引き続き機能します。** キーそのものを廃止するには、**Account → Developer → API Keys**（自分のもの）または **Setup → Access Control → API Keys**（全員のもの、Manage Platform Settings が必要）から削除してください。 -- **ブラウザのサインインは失効しません**が、そのトークンを受け付けるのは MCP エンドポイントだけなので、オフの間は何にも届きません。 - -### ObjectOS Cloud の場合：トラブルシューティング [#on-objectos-cloud-troubleshooting] - -| 症状 | 原因 | -|---|---| -| 環境の **Settings** に **AI agent access (MCP)** の行がない | それが見えるのは組織のオーナーと管理者だけです | -| **Connect an Agent** が **Account → Developer** にも **Setup → Integrations** にもない | AI エージェントのアクセスがまだオフか、たった今オンにしたところです。再読み込みしてください | -| **Connect an Agent** が **Account → Developer** の下にしかない | その環境で Manage Platform Settings を持っていません。Account のエントリでも同じページが開きます | -| クライアントから `429` が返る | 環境のエージェントが上限を超えました。`Retry-After` の秒数だけ待ち、同じ呼び出しを繰り返しているエージェントがないか確認してください | -| 接続にビルドツールがない | サインインで `metadata:write` が付与されなかったか、クライアントが API キーを使っています。ブラウザのサインインで接続し直し、付与してください | -| ビルドツールが `PERMISSION_DENIED` を返す | その環境で `manage_metadata` と `studio.access` を持っていません | -| エージェントが構築したものがアプリに表示されない | それはドラフトです。Studio → **Changes** で公開してください | -| ビルドツールが、ビルドの書き込みまたはドラフトを示して `RATE_LIMIT_EXCEEDED` を返す | その日のビルドの書き込みまたはドラフトの上限を使い切りました。UTC の翌日まで待つか、ドラフトを公開または破棄してください | - -## トラブルシューティング [#troubleshooting] - -| 症状 | 原因 → 対処 | -|---|---| -| `/api/v1/mcp` で `404` | この機能が無効です。`OS_MCP_SERVER_ENABLED` の設定を外してください（デフォルトは有効） | -| `501 Not Implemented` | MCP プラグインがこのビルドに含まれていません。スタックのプラグインを確認してください | -| stdio を有効にすると起動が拒否される | stdio は安全側に倒れて失敗します（16.0）。`OS_MCP_STDIO_API_KEY` に解決できる `osk_` キーを設定するか、`OS_MCP_STDIO_ENABLED` をオフにしてください | -| すべての呼び出しで `401` | 匿名、または無効な認証情報です。対話型のクライアント：ブラウザのログインを完了してください。ヘッドレス：`osk_` キーとヘッダーの綴りを確認してください | -| `403 insufficient_scope` | OAuth のトークンに、そのツール群のスコープがありません（例：`data:write` なしの書き込み）。接続し直してスコープを付与してください | -| アクションが `list_actions` にない | `ai.exposed` が `true` でない、`ai.description` が 40 文字より短い、種類がヘッドレスで呼び出せない（`url` / `modal` / `form` は決して現れません）、`sys_*` オブジェクトを対象にしている、または呼び出し元が `requiredPermissions` を満たしていない | -| 読み取りの行が少ない / 書き込みが拒否される | 設計どおりの動作です。呼び出し元の権限とレコードアクセスが適用されています。UI で同じユーザーとして確認してください | - -## 次に進む [#where-to-go-next] - -| タスク | ページ | -|---|---| -| AI プロバイダー、埋め込み、MCP サーバーのプラグインを設定する | [AI サービス](/docs/configure/ai) | -| サービスユーザーと API キーを作成する | [ユーザーと組織](/docs/configure/users) | -| エージェントが何を見てよいかを理解する | [権限](/docs/configure/permissions) | -| REST API とキーの管理 | [API アクセス](/docs/configure/api-access) | -| 特定のユーザーのアクセスを確認する | [アクセスの管理](/docs/configure/permissions/managing-access) | diff --git a/content/docs/configure/mcp.mdx b/content/docs/configure/mcp.mdx index 4a4fe0d..e4957d9 100644 --- a/content/docs/configure/mcp.mdx +++ b/content/docs/configure/mcp.mdx @@ -15,9 +15,10 @@ client and prove it works. > endpoint then returns 404 and the **Setup → Connect an Agent** page > disappears with it. -> **On ObjectOS Cloud it is the other way round:** each environment's MCP -> endpoint is **off until an owner or admin turns it on**, and every plan has -> a request limit. See [On ObjectOS Cloud](#on-objectos-cloud). +> **On ObjectOS Cloud each environment has its own switch:** a new +> environment's MCP endpoint starts **on**, an owner or admin can turn it off +> at any time, and every plan has a request limit. See +> [On ObjectOS Cloud](#on-objectos-cloud). This page is about connecting *external* AI tools to your app. For the server-side AI stack — chat providers, embedders, RAG, and registering @@ -193,9 +194,16 @@ details live, and that an agent can build the app as drafts. ### Turn on AI agent access Exposing an environment's data to an outside AI client is the organization's -decision, so on ObjectOS Cloud the endpoint is **off by default**, per -environment, on every plan (ruled on -[cloud#1248](https://github.com/objectstack-ai/cloud/issues/1248)). +decision, so each environment has its own switch, on every plan (ruled on +[cloud#1248](https://github.com/objectstack-ai/cloud/issues/1248)). A **new +environment starts with it on**, and an owner or admin can +[turn it off](#turn-it-off) at any time (ruled on +[cloud#3628](https://github.com/objectstack-ai/cloud/issues/3628)). An +environment created before that keeps the switch it had, so an older +environment may still be off. + +The steps below are needed only for an environment whose endpoint is off: an +older one, or one that was turned off. 1. In the cloud console, open the environment's page and its **Settings** tab. Under **Access and sign-in**, the **AI agent access (MCP)** row reads @@ -331,7 +339,7 @@ and API keys alike. It does not revoke anything else: | Symptom | Cause | |---|---| | No **AI agent access (MCP)** row on the environment's **Settings** | Only owners and admins of the organization see it | -| **Connect an Agent** is in neither **Account → Developer** nor **Setup → Integrations** | AI agent access is still off, or was turned on a moment ago — reload | +| **Connect an Agent** is in neither **Account → Developer** nor **Setup → Integrations** | AI agent access is off (an older environment, or one that was turned off) — [turn it on](#turn-on-ai-agent-access); if it was turned on a moment ago, reload | | **Connect an Agent** is under **Account → Developer** only | You lack Manage Platform Settings in that environment; the Account entry opens the same page | | `429` from the client | The environment's agents went past its limit; wait the `Retry-After` seconds, and look for an agent repeating the same call | | No build tools on the connection | The sign-in did not grant `metadata:write`, or the client uses an API key; reconnect with the browser sign-in and grant it | diff --git a/content/docs/configure/mcp.zh-Hans.mdx b/content/docs/configure/mcp.zh-Hans.mdx deleted file mode 100644 index 84f3ff5..0000000 --- a/content/docs/configure/mcp.zh-Hans.mdx +++ /dev/null @@ -1,235 +0,0 @@ ---- -title: 接入 AI 工具（MCP） -description: 把 Claude Code、Claude Desktop 或任意 MCP 客户端指向你的 ObjectOS 应用，让 Agent 在你的权限模型约束下处理你的数据。 -editions: [community, cloud, enterprise] -translation: - source_sha: 0bec90d540bb424e11d1cedf6c0532227a9ce328717d2448f1c7fdc8b8291017 - guide_rev: 1 - mode: auto ---- - -每个 ObjectOS 部署天生就是一个 MCP 服务器。运行时在 **`/api/v1/mcp`** 上提供 [Model Context Protocol](https://modelcontextprotocol.io) 服务——默认开启，无需安装插件，无需配置步骤。你的对象和已暴露的动作在定义的那一刻就成为带类型的工具；剩下唯一要做的就是接入一个客户端并验证它能用。 - -> 要关闭这个入口，设置 `OS_MCP_SERVER_ENABLED=false`——端点将返回 404，**Setup → Connect an Agent**（接入 Agent）页面也随之消失。 - -> **在 ObjectOS Cloud 上正好相反：**每个环境的 MCP 端点**在所有者或管理员开启之前都是关闭的**，并且每个套餐都有请求上限。参见[在 ObjectOS Cloud 上](#on-objectos-cloud)。 - -本页讲的是把*外部* AI 工具接入你的应用。服务端 AI 栈——聊天 Provider、Embedder、RAG，以及在代码中显式注册 MCP 服务器插件——参见 [AI 服务](/docs/configure/ai)。 - -## Claude Code（一条命令） [#claude-code-one-command] - -交互式客户端使用 OAuth——每个部署本身就是一个 OAuth 2.1 授权服务器，因此不存在需要管理员签发再分发的凭据。第一次工具调用会打开浏览器登录，你**以自己的身份**接入： - -```bash -# 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](#headless-api-keys)： - -```bash -claude mcp add --transport http my-app https://your-deployment.example.com/api/v1/mcp \ - --header "x-api-key: osk_..." -``` - -## Claude Desktop 与 claude.ai [#claude-desktop-and-claudeai] - -**Settings → Connectors → Add custom connector**（设置 → 连接器 → 添加自定义连接器），然后粘贴 MCP URL（`https://your-deployment.example.com/api/v1/mcp`）。首次使用时会走同样的浏览器登录流程。 - -## 任意 MCP 客户端（`.mcp.json`） [#any-mcp-client-mcpjson] - -读取 `mcpServers` 映射的客户端以同样方式接入。使用 API Key： - -```json -{ - "mcpServers": { - "objectstack": { - "type": "http", - "url": "https://your-deployment.example.com/api/v1/mcp", - "headers": { "x-api-key": "osk_..." } - } - } -} -``` - -## 无头场景：API Key [#headless-api-keys] - -在 **Setup → Connect an Agent**（接入 Agent，那里还提供各客户端可直接复制粘贴的接入片段）中签发 Key，或通过 REST： - -```bash -curl -b cookies.txt -X POST https://your-deployment.example.com/api/v1/keys -# → { "key": "osk_..." } — shown once; store it in your secret manager -``` - -每次请求以三种等价形式之一携带它： - -| 请求头 | 示例 | -|---|---| -| `x-api-key` | `x-api-key: osk_...` | -| `Authorization: ApiKey` | `Authorization: ApiKey osk_...` | -| `Authorization: Bearer` | `Authorization: Bearer osk_...`（通过 `osk_` 前缀识别） | - -> OAuth 要求 TLS——纯 HTTP 部署（`localhost` 除外）会回退到**仅 API Key** 模式：浏览器登录通道被禁用，而不是被允许以不安全的方式运行。 - -对于长期集成，把 Key 绑定到带最小权限集的专用服务用户——参见[服务账号与 API Key](/docs/configure/users#service-accounts--api-keys)。 - -## stdio 传输（16.0） [#the-stdio-transport-160] - -除了 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 能得到什么 [#what-the-agent-gets] - -十一个数据、动作与创作工具，由你的元数据生成： - -| 工具 | 用途 | -|---|---| -| `list_objects` / `describe_object` | 发现有哪些对象及其字段 | -| `query_records` / `get_record` | 读取数据（列表查询默认每页上限 50 行） | -| `validate_expression` | 在保存*之前*对照真实对象 schema 校验公式（16.0）：错误（裸字段引用、未知字段并给出 did-you-mean）、警告（类型健全性、日期相等陷阱）、作用域内的字段/函数清单，以及推断的结果类型。只读、`data:read` scope、对 `sys_*` fail-closed | -| `aggregate_records` | 分组聚合（当前驱动支持时才注册） | -| `create_record` / `update_record` / `delete_record` | 写入数据 | -| `list_actions` / `run_action` | 按名称发现并调用你的业务动作 | - -要了解的两条暴露规则： - -- **对象自动暴露**——但 `sys_*` 系统对象除外，它们以 fail-closed 方式被拦截。 -- **动作需要作者显式选择加入**：`ai: { exposed: true }` 加上不少于 40 个字符的 `ai.description`，且该动作必须可以在无 UI 的情况下调用（带 body 或已注册 handler 的 `script`，或 `flow`）。 - -## 权限强制执行 [#permission-enforcement] - -- **每次调用都以调用者身份运行。**MCP 桥接解析的执行上下文与 REST 请求相同，因此对象权限、[记录访问](/docs/configure/permissions/record-access)和[字段级安全](/docs/configure/permissions/field-level-security)对 Agent 的作用与对 UI 中的真人完全一致。结果稀疏或写入被拒，通常意味着治理在*正常工作*，而不是连接坏了。 -- **OAuth scope 会收窄工具集。**Token 携带 `data:read`、`data:write` 和 `actions:execute` 这些 scope——不在已授予 scope 内的工具，在该会话中根本不会被注册。API Key 和会话调用者获得完整工具集，但每次调用仍会做权限检查。第四个 scope `metadata:write` 只在部署提供构建工具的地方才开放这些工具：在 ObjectOS Cloud 上，参见[用 Agent 构建](#build-with-an-agent)。 -- **动作体一经调用即作为可信应用代码运行**（`ai.exposed` 门槛和 `requiredPermissions` 在*调用*时检查）。把编写动作当作值得代码评审的行为——那才是真正的安全边界。 -- 动作还可以声明 `ai.requiresConfirmation`；看起来具有破坏性的动作默认要求确认。 - -## 验证连接 [#verify-the-connection] - -问 Agent 一个只有实时 schema 才能回答的问题： - -```text -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 插件](https://github.com/objectstack-ai/claude-plugin)（`claude plugin marketplace add objectstack-ai/claude-plugin`），后者打包了该 skill 和一个引导式的 `/objectstack:connect` 命令。 - -## 在 ObjectOS Cloud 上 [#on-objectos-cloud] - -一旦端点开启，上述所有内容都适用于 ObjectOS Cloud 环境。有四处不同：开关、上限、连接信息所在的位置，以及 Agent 可以把应用构建为草稿。 - -### 开启 AI Agent 访问 [#turn-on-ai-agent-access] - -把环境的数据暴露给外部 AI 客户端是组织的决定，因此在 ObjectOS Cloud 上，端点在每个套餐上都按环境**默认关闭**（裁定见 [cloud#1248](https://github.com/objectstack-ai/cloud/issues/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 签发器。 - -### 接入 [#connect] - -交互式客户端使用上文描述的浏览器登录：Agent 随后以**你**的身份行事，处于你自己的权限、行级安全和字段访问之内。无头客户端——CI、脚本——使用在 **Connect an Agent** 的 **API keys · headless** 卡片中签发的 [API Key](#headless-api-keys)；Key 以签发它的人的身份行事，并且永远不能替其他人签发。 - -### 用 Agent 构建 [#build-with-an-agent] - -Agent 还可以**构建应用**：创建和修改它的对象、字段、视图、页面、仪表盘、流程和动作，而不只是它的记录。它构建的一切在有人发布之前都是**草稿**。 - -**请求 `metadata:write`。**构建工具只提供给授权中包含 `metadata:write` scope 的浏览器登录。环境会把它与 `data:read`、`data:write` 和 `actions:execute` 一起公布，因此请求环境所公布 scope 的客户端，在你登录时就会获得它。如果你的客户端按名称请求 scope，加上 `metadata:write`；如果你登录时没有它，重新连接。[API Key](#headless-api-keys) 永远不会开放构建工具。该 scope 只开放工具，仅此而已：每次调用都以你的身份运行，并需要你在该环境中拥有 `manage_metadata` 或 `studio.access` 权限，与 [AI Builder](/docs/build/ai-builder) 相同。 - -**这些工具做什么。** - -| 工具 | 用途 | -|---|---| -| `get_authoring_rules`、`get_metadata_schema` | 该环境遵循的构建规则，以及某种元数据类型的结构 | -| `list_metadata`、`describe_metadata`、`list_packages`、`get_package` | 环境当前包含的内容 | -| `propose_blueprint`、`apply_blueprint` | 根据描述设计一个应用或功能，然后暂存整个设计 | -| `create_object`、`add_field`、`modify_field`、`delete_field` | 修改对象和字段 | -| `create_metadata`、`update_metadata`、`apply_edit` | 创建环境可构建的任意类型、修改其中之一，或对现有应用应用一次结构化编辑 | -| `create_seed` | 添加示例数据 | -| `create_package` | 创建一个用于构建的包 | -| `verify_build` | 对照平台规则检查草稿，并报告它拒绝的内容 | - -每次调用都要指明它的包（`packageId` 或 `targetApp`）；没有任何东西会把工作包从一次调用带到下一次。这里不提供 `toggle_flow` 和 `test_flow`，因为 Agent 暂存的流程是不会运行的草稿。 - -**每次写入都是草稿，在每个环境中都是。**包括生产环境。没有工具会发布，也没有工具会丢弃。每次写入的结果都会说明变更尚未生效，并带有一个 `staged` 块，列出这些草稿以及发布它们的地址。 - -**由人在 Studio → Changes 中发布。**在 Studio 中打开该包及其 **Changes** 视图（环境中的 `/_console/studio//data`），评审 Agent 暂存的内容，然后发布或丢弃。告诉你它已经创建了某样东西的 Agent，其实是起草了它；发布之后应用才会显示它。 - -**删除或收窄需要 `confirm: true`。**`delete_field`、`modify_field`、`apply_edit` 和 `update_metadata` 接受一个 `confirm` 参数。会删除字段、改变字段类型或从流程中删去步骤的调用，在没有 `confirm: true` 时什么都不会暂存，并且回答会指出发布它将失去什么。只做添加的变更永远不需要它。 - -**Agent 能构建多少。**构建调用也是 MCP 请求，因此[请求上限](#limits)对它们适用。另有两项上限计入构建（[存储与限制](/docs/cloud/storage-and-limits#drafts-and-authoring-writes)）： - -| | Free | Team 及以上 | -|---|---|---| -| 通过 MCP 的构建写入，每个环境每个 UTC 日 | 200 | 2,000 | -| 每个环境的未发布草稿，无论以何种方式产生 | 500 | 500 | - -读取和 `verify_build` 不计为写入。超过任一上限后，工具调用会以 `RATE_LIMIT_EXCEEDED` 被拒绝，并附上计数和重置条件：写入在下一个 UTC 日重置，草稿在发布或丢弃后重置。 - -> **为什么我的流程被拒绝？**它用到了 Agent 在这里无法构建的东西，拒绝信息会指出是哪一项：Free 上的定时或相对时间流程、Free 上的审批步骤，或者一种需在源码中构建并作为[包](/docs/build/packages)发布的类型。 - -Agent 可以构建由记录变更或按钮启动的流程，使用创建、更新和删除记录、赋值、判断、循环和等待步骤。定时和相对时间流程在 Team 及以上可以构建，审批步骤也在 Team 及以上可以构建（[套餐](/docs/cloud/plans-and-seats)）。脚本、Webhook、API 触发的流程和屏幕流程，以及 script、webhook、API、job、邮件模板、翻译、主题、插件、agent、skill 和数据源这些类型，在任何套餐上都在源码中构建。 - -### 上限 [#limits] - -每个环境的端点接受一定数量的请求，由连接到它的所有 Agent 共享（裁定见 [cloud#3203](https://github.com/objectstack-ai/cloud/issues/3203)）： - -| 套餐 | 每分钟 | 每个 UTC 日 | -|---|---|---| -| Free | 20 | 1,000 | -| Team 及以上 | 120 | 无每日上限 | - -超过上限后，端点以 `429` 加 `Retry-After` 和代码 `RATE_LIMIT_EXCEEDED` 应答；消息会说明触发了哪个上限以及何时重置。什么算作一次请求，以及与之并列的草稿和创作写入上限，参见[存储与限制](/docs/cloud/storage-and-limits#mcp-limits)。开关在套餐变更时保持不变，因此降级或升级永远不会把它打开或关闭。 - -### 关闭 [#turn-it-off] - -在同一行中，**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 上：故障排查 [#on-objectos-cloud-troubleshooting] - -| 症状 | 原因 | -|---|---| -| 环境的 **Settings** 上没有 **AI agent access (MCP)** 一行 | 只有组织的所有者和管理员能看到它 | -| **Connect an Agent** 既不在 **Account → Developer** 中，也不在 **Setup → Integrations** 中 | AI Agent 访问仍处于关闭状态，或刚刚才开启——重新加载 | -| **Connect an Agent** 只出现在 **Account → Developer** 下 | 你在该环境中没有 Manage Platform Settings；Account 入口打开的是同一个页面 | -| 客户端收到 `429` | 环境的 Agent 超过了上限；等待 `Retry-After` 秒数，并排查是否有 Agent 在重复同一个调用 | -| 连接上没有构建工具 | 登录时没有授予 `metadata:write`，或客户端使用的是 API Key；用浏览器登录重新连接并授予它 | -| 构建工具返回 `PERMISSION_DENIED` | 你在该环境中既没有 `manage_metadata` 也没有 `studio.access` | -| Agent 构建了应用中看不到的东西 | 它是草稿；在 Studio → **Changes** 中发布它 | -| 构建工具返回 `RATE_LIMIT_EXCEEDED`，并指明构建写入或草稿 | 当天的构建写入或草稿上限已用完；等到下一个 UTC 日，或发布或丢弃草稿 | - -## 故障排查 [#troubleshooting] - -| 症状 | 原因 → 解决 | -|---|---| -| `/api/v1/mcp` 返回 `404` | 入口被禁用——取消设置 `OS_MCP_SERVER_ENABLED`（默认开启） | -| `501 Not Implemented` | 此构建不包含 MCP 插件——检查你的栈的插件配置 | -| 开启 stdio 后启动被拒绝 | stdio 是 fail-closed 的（16.0）——把 `OS_MCP_STDIO_API_KEY` 设为可解析的 `osk_` Key，或关闭 `OS_MCP_STDIO_ENABLED` | -| 每次调用都 `401` | 匿名或凭据无效。交互式客户端：完成浏览器登录。无头场景：检查 `osk_` Key 和请求头拼写 | -| `403 insufficient_scope` | OAuth token 缺少该工具族所需的 scope（例如没有 `data:write` 却尝试写入）——重新连接并授予该 scope | -| 某个动作没出现在 `list_actions` 中 | `ai.exposed` 不为 `true`、`ai.description` 短于 40 个字符、类型不可无头调用（`url` / `modal` / `form` 永远不会出现）、目标是 `sys_*` 对象，或调用者未通过其 `requiredPermissions` | -| 读取返回的行很少 / 写入被拒 | 符合设计——调用者的权限和记录访问在生效。用同一用户在 UI 中验证 | - -## 下一步 [#where-to-go-next] - -| 任务 | 页面 | -|---|---| -| 配置 AI Provider、Embedder 和 MCP 服务器插件 | [AI 服务](/docs/configure/ai) | -| 创建服务用户和 API Key | [用户与组织](/docs/configure/users) | -| 理解 Agent 被允许看到什么 | [权限](/docs/configure/permissions) | -| REST API 与 Key 管理 | [API 访问](/docs/configure/api-access) | -| 验证某个用户的访问权限 | [权限分配](/docs/configure/permissions/managing-access) | diff --git a/content/docs/configure/mcp.zh-Hant.mdx b/content/docs/configure/mcp.zh-Hant.mdx deleted file mode 100644 index dc29d41..0000000 --- a/content/docs/configure/mcp.zh-Hant.mdx +++ /dev/null @@ -1,236 +0,0 @@ ---- -# @generated zh-Hant from zh-Hans -- do not edit. Edit the English source, then regenerate: pnpm --filter @objectos/docs gen:zh-hant -title: 接入 AI 工具（MCP） -description: 把 Claude Code、Claude Desktop 或任意 MCP 客戶端指向你的 ObjectOS 應用，讓 Agent 在你的許可權模型約束下處理你的資料。 -editions: [community, cloud, enterprise] -translation: - source_sha: 0bec90d540bb424e11d1cedf6c0532227a9ce328717d2448f1c7fdc8b8291017 - guide_rev: 1 - mode: auto ---- - -每個 ObjectOS 部署天生就是一個 MCP 伺服器。執行時在 **`/api/v1/mcp`** 上提供 [Model Context Protocol](https://modelcontextprotocol.io) 服務——預設開啟，無需安裝外掛，無需配置步驟。你的物件和已暴露的動作在定義的那一刻就成為帶型別的工具；剩下唯一要做的就是接入一個客戶端並驗證它能用。 - -> 要關閉這個入口，設定 `OS_MCP_SERVER_ENABLED=false`——端點將返回 404，**Setup → Connect an Agent**（接入 Agent）頁面也隨之消失。 - -> **在 ObjectOS Cloud 上正好相反：**每個環境的 MCP 端點**在所有者或管理員開啟之前都是關閉的**，並且每個套餐都有請求上限。參見[在 ObjectOS Cloud 上](#on-objectos-cloud)。 - -本頁講的是把*外部* AI 工具接入你的應用。服務端 AI 棧——聊天 Provider、Embedder、RAG，以及在程式碼中顯式註冊 MCP 伺服器外掛——參見 [AI 服務](/docs/configure/ai)。 - -## Claude Code（一條命令） [#claude-code-one-command] - -互動式客戶端使用 OAuth——每個部署本身就是一個 OAuth 2.1 授權伺服器，因此不存在需要管理員簽發再分發的憑據。第一次工具呼叫會開啟瀏覽器登入，你**以自己的身份**接入： - -```bash -# 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](#headless-api-keys)： - -```bash -claude mcp add --transport http my-app https://your-deployment.example.com/api/v1/mcp \ - --header "x-api-key: osk_..." -``` - -## Claude Desktop 與 claude.ai [#claude-desktop-and-claudeai] - -**Settings → Connectors → Add custom connector**（設定 → 聯結器 → 新增自定義聯結器），然後貼上 MCP URL（`https://your-deployment.example.com/api/v1/mcp`）。首次使用時會走同樣的瀏覽器登入流程。 - -## 任意 MCP 客戶端（`.mcp.json`） [#any-mcp-client-mcpjson] - -讀取 `mcpServers` 對映的客戶端以同樣方式接入。使用 API Key： - -```json -{ - "mcpServers": { - "objectstack": { - "type": "http", - "url": "https://your-deployment.example.com/api/v1/mcp", - "headers": { "x-api-key": "osk_..." } - } - } -} -``` - -## 無頭場景：API Key [#headless-api-keys] - -在 **Setup → Connect an Agent**（接入 Agent，那裡還提供各客戶端可直接複製貼上的接入片段）中簽發 Key，或通過 REST： - -```bash -curl -b cookies.txt -X POST https://your-deployment.example.com/api/v1/keys -# → { "key": "osk_..." } — shown once; store it in your secret manager -``` - -每次請求以三種等價形式之一攜帶它： - -| 請求頭 | 示例 | -|---|---| -| `x-api-key` | `x-api-key: osk_...` | -| `Authorization: ApiKey` | `Authorization: ApiKey osk_...` | -| `Authorization: Bearer` | `Authorization: Bearer osk_...`（通過 `osk_` 字首識別） | - -> OAuth 要求 TLS——純 HTTP 部署（`localhost` 除外）會回退到**僅 API Key** 模式：瀏覽器登入通道被停用，而不是被允許以不安全的方式執行。 - -對於長期整合，把 Key 繫結到帶最小許可權集的專用服務使用者——參見[服務賬號與 API Key](/docs/configure/users#service-accounts--api-keys)。 - -## stdio 傳輸（16.0） [#the-stdio-transport-160] - -除了 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 能得到什麼 [#what-the-agent-gets] - -十一個數據、動作與創作工具，由你的後設資料生成： - -| 工具 | 用途 | -|---|---| -| `list_objects` / `describe_object` | 發現有哪些物件及其欄位 | -| `query_records` / `get_record` | 讀取資料（列表查詢預設每頁上限 50 行） | -| `validate_expression` | 在儲存*之前*對照真實物件 schema 校驗公式（16.0）：錯誤（裸欄位引用、未知欄位並給出 did-you-mean）、警告（型別健全性、日期相等陷阱）、作用域內的欄位/函式清單，以及推斷的結果型別。只讀、`data:read` scope、對 `sys_*` fail-closed | -| `aggregate_records` | 分組聚合（當前驅動支援時才註冊） | -| `create_record` / `update_record` / `delete_record` | 寫入資料 | -| `list_actions` / `run_action` | 按名稱發現並呼叫你的業務動作 | - -要了解的兩條暴露規則： - -- **物件自動暴露**——但 `sys_*` 系統物件除外，它們以 fail-closed 方式被攔截。 -- **動作需要作者顯式選擇加入**：`ai: { exposed: true }` 加上不少於 40 個字元的 `ai.description`，且該動作必須可以在無 UI 的情況下呼叫（帶 body 或已註冊 handler 的 `script`，或 `flow`）。 - -## 許可權強制執行 [#permission-enforcement] - -- **每次呼叫都以呼叫者身份執行。**MCP 橋接解析的執行上下文與 REST 請求相同，因此物件許可權、[記錄訪問](/docs/configure/permissions/record-access)和[欄位級安全](/docs/configure/permissions/field-level-security)對 Agent 的作用與對 UI 中的真人完全一致。結果稀疏或寫入被拒，通常意味著治理在*正常工作*，而不是連線壞了。 -- **OAuth scope 會收窄工具集。**Token 攜帶 `data:read`、`data:write` 和 `actions:execute` 這些 scope——不在已授予 scope 內的工具，在該會話中根本不會被註冊。API Key 和會話呼叫者獲得完整工具集，但每次呼叫仍會做許可權檢查。第四個 scope `metadata:write` 只在部署提供構建工具的地方才開放這些工具：在 ObjectOS Cloud 上，參見[用 Agent 構建](#build-with-an-agent)。 -- **動作體一經呼叫即作為可信應用程式碼執行**（`ai.exposed` 門檻和 `requiredPermissions` 在*呼叫*時檢查）。把編寫動作當作值得程式碼評審的行為——那才是真正的安全邊界。 -- 動作還可以宣告 `ai.requiresConfirmation`；看起來具有破壞性的動作預設要求確認。 - -## 驗證連線 [#verify-the-connection] - -問 Agent 一個只有即時 schema 才能回答的問題： - -```text -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 外掛](https://github.com/objectstack-ai/claude-plugin)（`claude plugin marketplace add objectstack-ai/claude-plugin`），後者打包了該 skill 和一個引導式的 `/objectstack:connect` 命令。 - -## 在 ObjectOS Cloud 上 [#on-objectos-cloud] - -一旦端點開啟，上述所有內容都適用於 ObjectOS Cloud 環境。有四處不同：開關、上限、連線資訊所在的位置，以及 Agent 可以把應用構建為草稿。 - -### 開啟 AI Agent 訪問 [#turn-on-ai-agent-access] - -把環境的資料暴露給外部 AI 客戶端是組織的決定，因此在 ObjectOS Cloud 上，端點在每個套餐上都按環境**預設關閉**（裁定見 [cloud#1248](https://github.com/objectstack-ai/cloud/issues/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 簽發器。 - -### 接入 [#connect] - -互動式客戶端使用上文描述的瀏覽器登入：Agent 隨後以**你**的身份行事，處於你自己的許可權、行級安全和欄位訪問之內。無頭客戶端——CI、指令碼——使用在 **Connect an Agent** 的 **API keys · headless** 卡片中簽發的 [API Key](#headless-api-keys)；Key 以簽發它的人的身份行事，並且永遠不能替其他人簽發。 - -### 用 Agent 構建 [#build-with-an-agent] - -Agent 還可以**構建應用**：建立和修改它的物件、欄位、檢視、頁面、儀表盤、流程和動作，而不只是它的記錄。它構建的一切在有人釋出之前都是**草稿**。 - -**請求 `metadata:write`。**構建工具只提供給授權中包含 `metadata:write` scope 的瀏覽器登入。環境會把它與 `data:read`、`data:write` 和 `actions:execute` 一起公佈，因此請求環境所公佈 scope 的客戶端，在你登入時就會獲得它。如果你的客戶端按名稱請求 scope，加上 `metadata:write`；如果你登入時沒有它，重新連線。[API Key](#headless-api-keys) 永遠不會開放構建工具。該 scope 只開放工具，僅此而已：每次呼叫都以你的身份執行，並需要你在該環境中擁有 `manage_metadata` 或 `studio.access` 許可權，與 [AI Builder](/docs/build/ai-builder) 相同。 - -**這些工具做什麼。** - -| 工具 | 用途 | -|---|---| -| `get_authoring_rules`、`get_metadata_schema` | 該環境遵循的構建規則，以及某種後設資料型別的結構 | -| `list_metadata`、`describe_metadata`、`list_packages`、`get_package` | 環境當前包含的內容 | -| `propose_blueprint`、`apply_blueprint` | 根據描述設計一個應用或功能，然後暫存整個設計 | -| `create_object`、`add_field`、`modify_field`、`delete_field` | 修改物件和欄位 | -| `create_metadata`、`update_metadata`、`apply_edit` | 建立環境可構建的任意型別、修改其中之一，或對現有應用應用一次結構化編輯 | -| `create_seed` | 新增示例資料 | -| `create_package` | 建立一個用於構建的包 | -| `verify_build` | 對照平臺規則檢查草稿，並報告它拒絕的內容 | - -每次呼叫都要指明它的包（`packageId` 或 `targetApp`）；沒有任何東西會把工作包從一次呼叫帶到下一次。這裡不提供 `toggle_flow` 和 `test_flow`，因為 Agent 暫存的流程是不會執行的草稿。 - -**每次寫入都是草稿，在每個環境中都是。**包括生產環境。沒有工具會發布，也沒有工具會丟棄。每次寫入的結果都會說明變更尚未生效，並帶有一個 `staged` 塊，列出這些草稿以及釋出它們的地址。 - -**由人在 Studio → Changes 中釋出。**在 Studio 中開啟該包及其 **Changes** 檢視（環境中的 `/_console/studio//data`），評審 Agent 暫存的內容，然後釋出或丟棄。告訴你它已經建立了某樣東西的 Agent，其實是起草了它；釋出之後應用才會顯示它。 - -**刪除或收窄需要 `confirm: true`。**`delete_field`、`modify_field`、`apply_edit` 和 `update_metadata` 接受一個 `confirm` 引數。會刪除欄位、改變欄位型別或從流程中刪去步驟的呼叫，在沒有 `confirm: true` 時什麼都不會暫存，並且回答會指出釋出它將失去什麼。只做新增的變更永遠不需要它。 - -**Agent 能構建多少。**構建呼叫也是 MCP 請求，因此[請求上限](#limits)對它們適用。另有兩項上限計入構建（[儲存與限制](/docs/cloud/storage-and-limits#drafts-and-authoring-writes)）： - -| | Free | Team 及以上 | -|---|---|---| -| 通過 MCP 的構建寫入，每個環境每個 UTC 日 | 200 | 2,000 | -| 每個環境的未釋出草稿，無論以何種方式產生 | 500 | 500 | - -讀取和 `verify_build` 不計為寫入。超過任一上限後，工具呼叫會以 `RATE_LIMIT_EXCEEDED` 被拒絕，並附上計數和重置條件：寫入在下一個 UTC 日重置，草稿在釋出或丟棄後重置。 - -> **為什麼我的流程被拒絕？**它用到了 Agent 在這裡無法構建的東西，拒絕資訊會指出是哪一項：Free 上的定時或相對時間流程、Free 上的審批步驟，或者一種需在原始碼中構建並作為[包](/docs/build/packages)釋出的型別。 - -Agent 可以構建由記錄變更或按鈕啟動的流程，使用建立、更新和刪除記錄、賦值、判斷、迴圈和等待步驟。定時和相對時間流程在 Team 及以上可以構建，審批步驟也在 Team 及以上可以構建（[套餐](/docs/cloud/plans-and-seats)）。指令碼、Webhook、API 觸發的流程和螢幕流程，以及 script、webhook、API、job、郵件模板、翻譯、主題、外掛、agent、skill 和資料來源這些型別，在任何套餐上都在原始碼中構建。 - -### 上限 [#limits] - -每個環境的端點接受一定數量的請求，由連線到它的所有 Agent 共享（裁定見 [cloud#3203](https://github.com/objectstack-ai/cloud/issues/3203)）： - -| 套餐 | 每分鐘 | 每個 UTC 日 | -|---|---|---| -| Free | 20 | 1,000 | -| Team 及以上 | 120 | 無每日上限 | - -超過上限後，端點以 `429` 加 `Retry-After` 和程式碼 `RATE_LIMIT_EXCEEDED` 應答；訊息會說明觸發了哪個上限以及何時重置。什麼算作一次請求，以及與之並列的草稿和創作寫入上限，參見[儲存與限制](/docs/cloud/storage-and-limits#mcp-limits)。開關在套餐變更時保持不變，因此降級或升級永遠不會把它開啟或關閉。 - -### 關閉 [#turn-it-off] - -在同一行中，**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 上：故障排查 [#on-objectos-cloud-troubleshooting] - -| 症狀 | 原因 | -|---|---| -| 環境的 **Settings** 上沒有 **AI agent access (MCP)** 一行 | 只有組織的所有者和管理員能看到它 | -| **Connect an Agent** 既不在 **Account → Developer** 中，也不在 **Setup → Integrations** 中 | AI Agent 訪問仍處於關閉狀態，或剛剛才開啟——重新載入 | -| **Connect an Agent** 只出現在 **Account → Developer** 下 | 你在該環境中沒有 Manage Platform Settings；Account 入口開啟的是同一個頁面 | -| 客戶端收到 `429` | 環境的 Agent 超過了上限；等待 `Retry-After` 秒數，並排查是否有 Agent 在重複同一個呼叫 | -| 連線上沒有構建工具 | 登入時沒有授予 `metadata:write`，或客戶端使用的是 API Key；用瀏覽器登入重新連線並授予它 | -| 構建工具返回 `PERMISSION_DENIED` | 你在該環境中既沒有 `manage_metadata` 也沒有 `studio.access` | -| Agent 構建了應用中看不到的東西 | 它是草稿；在 Studio → **Changes** 中釋出它 | -| 構建工具返回 `RATE_LIMIT_EXCEEDED`，並指明構建寫入或草稿 | 當天的構建寫入或草稿上限已用完；等到下一個 UTC 日，或釋出或丟棄草稿 | - -## 故障排查 [#troubleshooting] - -| 症狀 | 原因 → 解決 | -|---|---| -| `/api/v1/mcp` 返回 `404` | 入口被停用——取消設定 `OS_MCP_SERVER_ENABLED`（預設開啟） | -| `501 Not Implemented` | 此構建不包含 MCP 外掛——檢查你的棧的外掛配置 | -| 開啟 stdio 後啟動被拒絕 | stdio 是 fail-closed 的（16.0）——把 `OS_MCP_STDIO_API_KEY` 設為可解析的 `osk_` Key，或關閉 `OS_MCP_STDIO_ENABLED` | -| 每次呼叫都 `401` | 匿名或憑據無效。互動式客戶端：完成瀏覽器登入。無頭場景：檢查 `osk_` Key 和請求頭拼寫 | -| `403 insufficient_scope` | OAuth token 缺少該工具族所需的 scope（例如沒有 `data:write` 卻嘗試寫入）——重新連線並授予該 scope | -| 某個動作沒出現在 `list_actions` 中 | `ai.exposed` 不為 `true`、`ai.description` 短於 40 個字元、型別不可無頭呼叫（`url` / `modal` / `form` 永遠不會出現）、目標是 `sys_*` 物件，或呼叫者未通過其 `requiredPermissions` | -| 讀取返回的行很少 / 寫入被拒 | 符合設計——呼叫者的許可權和記錄訪問在生效。用同一使用者在 UI 中驗證 | - -## 下一步 [#where-to-go-next] - -| 任務 | 頁面 | -|---|---| -| 配置 AI Provider、Embedder 和 MCP 伺服器外掛 | [AI 服務](/docs/configure/ai) | -| 建立服務使用者和 API Key | [使用者與組織](/docs/configure/users) | -| 理解 Agent 被允許看到什麼 | [許可權](/docs/configure/permissions) | -| REST API 與 Key 管理 | [API 訪問](/docs/configure/api-access) | -| 驗證某個使用者的訪問許可權 | [許可權分配](/docs/configure/permissions/managing-access) |