# Buildy Docs > Markdown twin of . Served for agents that ask for `Accept: text/markdown` or follow the `` declared on the HTML page. Buildy is a hosted runtime for agent-authored web apps. Your agent writes an ES module (plus optional UI and CSS) and POSTs it to Buildy; Buildy returns a public URL with key-value storage and a backend reachable from the UI. You keep using and updating it across agents. Last updated: June 8, 2026. ## Pick your path Both paths talk to the same backend and produce the same apps. The choice is just how your agent talks to Buildy. - **Codex plugin** — for Codex app or CLI users. Install the public Tambo Labs marketplace once; the plugin bundles Buildy's MCP endpoint and starter workflow. Codex renders Buildy apps through its browser fallback when inline MCP Apps UI is unavailable. See . - **HTTP API** — for any agent that can `curl` or `fetch` with auth headers (Cursor, Claude Code, Codex, Cline, Windsurf, Continue, Zed, Gemini CLI, plus chat agents with a web tool). Zero install. - **MCP server** — for chat clients (Claude Desktop, ChatGPT, Goose, MCPJam, and other MCP Apps-capable hosts) that support custom MCP connectors. Same tools, plus inline app rendering inside the chat where the client supports MCP Apps UI resources. --- ## Path 1: HTTP API Three things make this path work: the prompt below, the canonical guide at that the prompt points your agent at, and the OpenAPI spec at the guide links for the full route list. ### Copy the prompt Paste this into your agent. It points the agent at , which detects the HTTP path and routes it to build via `POST https://app.buildy.so/app` (no auth for the first app; sign up later to claim it). Same one-liner the landing page and the MCP path below use. Read https://buildy.so/start.md then help me create my first app. ### Under the hood The agent ends up making one of these calls: - `POST /app` — create. Body: `{ module, ui?, styles? }`. Returns the app URL plus a `bld_app_*` token to update it later. - `PUT /app/` — update an existing app with the same body shape. - `GET /app` — list apps for a signed-in user (`bld_user_*` token). - `POST /app//api/` — call an app's backend operation from outside the UI. Module shape, capabilities, error `kind`s, and the device-code pairing flow live in . Machine-readable contract: . --- ## Path 2: MCP server Three steps: pick your client, add the Buildy MCP endpoint, paste the prompt. ### Step 1: Pick your client MCP support varies by client. - **Claude** — full. Native Custom Connectors on Free, Pro, Max, Team, and Enterprise (Free is capped at one connector). Same flow on Claude.ai and Claude Desktop. Walkthrough: . - **ChatGPT** — in the ChatGPT Apps directory. Open the Buildy listing at and click Connect (no Developer mode needed). Fallback: a Developer-mode custom connector if your workspace hides the directory. - **Grok** — full. Native Custom Connectors on grok.com. Paste an MCP URL and Grok auto-discovers tools. Walkthrough: . - **Gemini** — partial. Gemini CLI and Gemini Enterprise support custom MCP servers; the consumer Gemini web/mobile app does not yet. Walkthrough: . - **Perplexity** — partial. Local MCP shipped in the macOS app; remote custom connectors are rolling out to paid (Pro / Max) subscribers. Walkthrough: . Codex users should prefer the public Buildy plugin: `codex plugin marketplace add https://github.com/tambo-labs/buildy-codex-plugin.git`. Codex gets the Buildy tools and should open returned app URLs in its browser fallback when the app does not render inline. Other coding agents (Goose, Claude Code, Cursor, Cline, Windsurf, Continue.dev, Zed, Gemini CLI) can also wire up MCP, but the HTTP API path above is simpler. Per-client paste-strings live in . For a client-agnostic authoring skill and agent instructions, see the public [tambo-labs/buildy-mcp](https://github.com/tambo-labs/buildy-mcp) repo (`SKILL.md` + `AGENTS.md`); install the skill with `npx skills add tambo-labs/buildy-mcp`. ### Step 2: Add the Buildy MCP endpoint Most clients use the default endpoint. ChatGPT uses a separate surface tuned for its Apps SDK. OAuth (with Dynamic Client Registration) is automatic; clients that support it show a one-time consent screen. - Default: `https://app.buildy.so/mcp` - ChatGPT: `https://app.buildy.so/mcp/chatgpt` ### Step 3: Paste the prompt Once Buildy is connected in your client, paste this prompt to start a build session. It points the agent at , which detects your connected Buildy tools and walks the build. Read https://buildy.so/start.md then help me create my first app. ### Tools the agent will use Buildy exposes twenty-one tools over MCP. Connected clients discover them automatically via `tools/list`, which is canonical — schemas, hints, and the exact set all live there. - `create_app` — store an agent-authored ES module plus optional UI and CSS. Returns a machine API `url` plus a token-free `shareUrl` to give the user, and renders inline in MCP Apps-capable hosts. - `update_app` — edit an existing app, either by replacing its module/UI/styles/description or by applying exact-string edits with optimistic-concurrency versioning. - `get_app` — open an existing app (inline when the client supports MCP Apps) and return its callable API operations and metadata. - `get_app_source` — return the persisted module, UI, and styles for an existing app, plus its current version. - `list_apps` — list the calling user's apps — owned plus shared-with-them — newest first, with roles, descriptions, and capabilities for disambiguation. - `delete_app` — delete an app's module entry. Pass `purge_storage: true` to also wipe its stored state. - `upload_asset` — store a static asset (image, PDF, dataset) on an app so its code stays small; the app reads it back same-origin. - `rename_app` — change an app's URL slug. The old URL keeps working by redirecting to the new one. - `set_remixable` — mark an app remixable so any visitor opening its URL gets their own editable copy. - `unset_remixable` — stop allowing remixes; existing remixes survive untouched. - `set_public` — make an app public: anyone with the URL opens it with no login and reads AND writes its data. On the main origin (`app.buildy.so/`) everyone shares ONE data pool with no per-visitor isolation, so anyone can wipe it — surface that warning before sharing. At a confirmed custom domain, the same anonymous visitor gets a per-visitor isolated jar (via a signed `buildy_vid` cookie), so each visitor's data is their own. Sharing alone (any `share_app` role) never sets `public_at`; public access is only ever the deliberate `set_public` opt-in. For per-person access that requires login, share with the `end-user` role instead. - `unset_public` — make a public app private again; anonymous visitors can no longer open it. Data already written is kept. - `set_starter_prompt` — set or clear the prompt prefilled in the chat host when a visitor opens a shared app. - `query_app` — run a read-only backend operation inside an app module (no edits, no state change). - `mutate_app` — run a mutating backend operation inside an app module without editing code. - `submit_feedback` — record agent-authored feedback (bugs, enhancements, crash reports, notes) about an app. - `list_feedback` — list feedback rows for the caller's apps, newest first. - `share_app` — invite someone (by handle or email) to an app as a `collaborator` (read + write, default), `end-user` (run + write data, not edit source), or `viewer` (read only) — or change an existing grantee's role by calling it again with a new `role` (updates in place, no new invitation). Creates a pending invitation; access starts only when they accept. Inviting an email with no Buildy account stores a pending invite and emails a sign-up link — it activates once they register and verify that email. - `unshare_app` — revoke a pending invitation or an accepted collaborator grant on an app. - `list_app_shares` — list an app's outstanding invitations and active grants, labeled by status and role (`collaborator` / `end-user` / `viewer`). - `set_handle` — change the signed-in user's handle (the first segment of their app URLs). The old handle redirects to the new one. --- ## UI API (`window.buildy`) Buildy injects `window.buildy` into every hosted app. Key members: - `buildy.api(id)`: call a backend op by manifest id. Unwraps the `{ ok, value }` envelope; throws `BuildyOperationError` on `{ ok: false }`. - `buildy.viewer`: the caller's role. Use `buildy.viewer.can(op)` to gate mutating UI; it is a client-side UX signal, not an enforcement boundary. - `buildy.user`: `{ id, handle?, name?, image? }` for a signed-in caller, or `null` for an anonymous visitor. Server-resolved at render, available synchronously. Exposes only public fields; never trust it for authorization. - `buildy.login()` (`Promise`): starts Buildy sign-in from inside the app and resolves with the caller's public identity (or `null` if they cancel). Opens a Buildy-controlled popup; your app never sees a credential. Check `buildy.login.available` first (it is `false` inside a chat-host embed). Read `buildy.login.canonicalUrl` to surface an "open in browser to sign in" link in embeds. In an embed `login()` opens that URL via the host and then throws `BuildyLoginError`. --- ## Reference - — full build manual: module shape, capabilities, HTTP API, device-code pairing, worked examples. - — per-client MCP connector paste-strings. - — machine-readable OpenAPI 3.1 contract. - — the agent entry point (route → discover → build smallest → verify). - — markdown twin of the landing page. ## Contact Questions, bug reports, or partnership inquiries: support@buildy.so. See also: , .