docs(cloud): MCP build — build with an agent over metadata:write, and the two developer routes (cloud#3304)

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

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/<package>/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
 

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