From c538ed7ea778110bb5665c460ea171d21a3a06e7 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 10:14:52 +0000 Subject: [PATCH] =?UTF-8?q?docs(cloud):=20MCP=20build=20=E2=80=94=20build?= =?UTF-8?q?=20with=20an=20agent=20over=20metadata:write,=20and=20the=20two?= =?UTF-8?q?=20developer=20routes=20(cloud#3304)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - configure/mcp: "Build with an agent" under On ObjectOS Cloud: requesting metadata:write (OAuth only, never an API key), what the authoring tools do, every write a draft in any environment with no publish tool, publish in Studio > Changes, confirm: true for removing or narrowing edits, the request limits plus the 200 / 2,000 build writes and 500 drafts, and the one-line answer to "why is my flow refused". Four troubleshooting rows. - build/packages: the two developer routes on Cloud, package publish (versioned, Marketplace) and MCP build (drafts, for iteration). - start/cloud: names both routes from step 4. English only; the locale siblings follow the translation pass. Claude-Session: https://claude.ai/code/session_01QUs3Brx2C3J1bPhD6AK2wB Co-authored-by: Claude --- content/docs/build/packages.mdx | 15 ++++++ content/docs/configure/mcp.mdx | 86 ++++++++++++++++++++++++++++++++- content/docs/start/cloud.mdx | 7 ++- 3 files changed, 104 insertions(+), 4 deletions(-) diff --git a/content/docs/build/packages.mdx b/content/docs/build/packages.mdx index 1947bbe8..c01cef9c 100644 --- a/content/docs/build/packages.mdx +++ b/content/docs/build/packages.mdx @@ -117,6 +117,21 @@ Installing below). See [Marketplace](/docs/build/marketplace). > [Environment Variables](/docs/reference/environment-variables) before copying > either name into a deployment's configuration. +## Two developer routes on ObjectOS Cloud + +A developer gets changes into a hosted environment one of two ways: + +| | Package publish | MCP build | +|---|---|---| +| How | Build in source, then `os package publish` and install from the **Marketplace** | Your own agent, connected over [MCP](/docs/configure/mcp#build-with-an-agent) with the `metadata:write` scope, builds in the environment | +| What lands | A **versioned** package, installed whole | **Drafts** in the environment, which a person publishes in Studio → **Changes** | +| What it can build | Everything the environment runs, including scripts, webhooks and API-triggered flows | What the environment's AI build offers: data model, interface, sample data, app shell, record- and button-started flows, no-code actions | +| Best for | Releases: the same version in several environments, review in your repository, the Marketplace | Iteration: trying a change in one environment and seeing it in the app | + +Use the MCP build to shape an app quickly, and a package once it needs a +version: to ship it to another environment or organization, to keep it in a +repository, or to carry metadata the MCP build does not offer. + ## Installing Installing is an **in-environment** action — distinct from publishing. You diff --git a/content/docs/configure/mcp.mdx b/content/docs/configure/mcp.mdx index d8e46c98..8242e6d1 100644 --- a/content/docs/configure/mcp.mdx +++ b/content/docs/configure/mcp.mdx @@ -155,6 +155,9 @@ Two exposure rules to know: `data:write`, and `actions:execute` scopes — tools outside the granted scopes are not even registered for that session. API-key and session callers get the full set, still permission-checked per call. + A fourth scope, `metadata:write`, serves build tools only where the + deployment provides them: on ObjectOS Cloud, see + [Build with an agent](#build-with-an-agent). - **Action bodies run as trusted app code** once invoked (the `ai.exposed` gate and `requiredPermissions` are checked at *invoke* time). Treat writing an action as a code-review-worthy act — that's @@ -184,8 +187,8 @@ fully operational. ## On ObjectOS Cloud Everything above applies to an ObjectOS Cloud environment once its endpoint -is on. Three things differ: the switch, the limits, and where the connection -details live. +is on. Four things differ: the switch, the limits, where the connection +details live, and that an agent can build the app as drafts. ### Turn on AI agent access @@ -218,6 +221,81 @@ access. Headless clients — CI, scripts — use an [API key](#headless-api-keys minted on **Connect an Agent** in the card **API keys · headless**; a key acts as the person who minted it and can never be minted for someone else. +### Build with an agent + +An agent can also **build the app**: create and change its objects, fields, +views, pages, dashboards, flows and actions, not only its records. Everything +it builds is a **draft** until a person publishes it. + +**Ask for `metadata:write`.** The build tools are served only to a browser +sign-in whose grant includes the `metadata:write` scope. The environment +advertises it beside `data:read`, `data:write` and `actions:execute`, so a +client that asks for the scopes an environment advertises gets it when you +sign in. If your client asks for scopes by name, add `metadata:write`; if you +signed in without it, reconnect. An [API key](#headless-api-keys) never opens +the build tools. The scope opens the tools and nothing more: every call runs as +you, and needs the `manage_metadata` or `studio.access` permission in that +environment, the same as the [AI Builder](/docs/build/ai-builder). + +**What the tools do.** + +| Tools | What they do | +|---|---| +| `get_authoring_rules`, `get_metadata_schema` | The rules this environment builds by, and the shape of a metadata type | +| `list_metadata`, `describe_metadata`, `list_packages`, `get_package` | What the environment holds now | +| `propose_blueprint`, `apply_blueprint` | Design an app or a feature from a description, then stage the whole design | +| `create_object`, `add_field`, `modify_field`, `delete_field` | Change objects and fields | +| `create_metadata`, `update_metadata`, `apply_edit` | Create any type the environment builds, change one, or apply a structured edit to an existing app | +| `create_seed` | Add sample data | +| `create_package` | Create a package to build in | +| `verify_build` | Check the drafts against the platform's rules and report what it refuses | + +Each call names its package (`packageId` or `targetApp`); nothing carries a +working package from one call to the next. `toggle_flow` and `test_flow` are +not served here, because a flow an agent stages is a draft that does not run. + +**Every write is a draft, in every environment.** That includes production. +No tool publishes and no tool discards. Each write's result says the change is +not live and carries a `staged` block naming the drafts and the address where +they are published. + +**A person publishes in Studio → Changes.** Open the package in Studio and its +**Changes** view (`/_console/studio//data` in the environment), review +what the agent staged, and publish or discard it. An agent that tells you it +has created something has drafted it; the app shows it once it is published. + +**Removing or narrowing needs `confirm: true`.** `delete_field`, +`modify_field`, `apply_edit` and `update_metadata` take a `confirm` argument. A +call that would remove a field, change a field's type or drop a step from a +flow stages nothing without `confirm: true`, and the answer names what +publishing it would lose. A change that only adds never needs it. + +**How much an agent can build.** Build calls are MCP requests, so the +[request limits](#limits) apply to them. Two more limits count building +([Storage and Limits](/docs/cloud/storage-and-limits#drafts-and-authoring-writes)): + +| | Free | Team and above | +|---|---|---| +| Build writes through MCP, per environment per UTC day | 200 | 2,000 | +| Unpublished drafts per environment, made any way | 500 | 500 | + +Reads and `verify_build` do not count as writes. Past either limit the tool +call is refused with `RATE_LIMIT_EXCEEDED`, the count, and what resets it: the +next UTC day for writes, a publish or a discard for drafts. + +> **Why is my flow refused?** It uses something an agent cannot build here, and +> the refusal names which: a scheduled or time-relative flow on Free, an +> approval step where approval workflows are not part of the plan, or a kind +> that is built in source and published as a [package](/docs/build/packages). + +An agent builds flows started by a record change or a button, from create, +update and delete record, assignment, decision, loop and wait steps. Scheduled +and time-relative flows are built on Team and above, and approval steps where +the plan includes [approval workflows](/docs/cloud/plans-and-seats). Scripts, +webhooks, API-triggered and screen flows, and the types script, webhook, API, +job, email template, translation, theme, plugin, agent, skill and data source +are built in source on any plan. + ### Limits Each environment's endpoint accepts a set number of requests, shared by every @@ -256,6 +334,10 @@ and API keys alike. It does not revoke anything else: | **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 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 | +| A build tool answers `PERMISSION_DENIED` | You lack `manage_metadata` and `studio.access` in that environment | +| The agent built something the app does not show | It is a draft; publish it in Studio → **Changes** | +| A build tool answers `RATE_LIMIT_EXCEEDED` naming build writes or drafts | The day's build writes or the draft limit is used up; wait for the next UTC day, or publish or discard drafts | ## Troubleshooting diff --git a/content/docs/start/cloud.mdx b/content/docs/start/cloud.mdx index 509b352a..8ea19fb0 100644 --- a/content/docs/start/cloud.mdx +++ b/content/docs/start/cloud.mdx @@ -41,8 +41,11 @@ Two ways, and you can use both: - **Install a [template](/docs/build/templates)** and start from a working app. -Either way the result is ordinary ObjectStack metadata: REST APIs, generated -screens, permissions and audit come with it. See [Build](/docs/build) for +Developers have two more routes: build in source and publish a +[package](/docs/build/packages#two-developer-routes-on-objectos-cloud), or let +their own agent build over [MCP](/docs/configure/mcp#build-with-an-agent) as +drafts a person publishes. Either way the result is ordinary ObjectStack +metadata: REST APIs, generated screens, permissions and audit come with it. See [Build](/docs/build) for everything you can add next. ## 5. Invite your team