Documentation

Buildy Docs

Last Updated: June 5, 2026

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.

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.
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, ChatGPT, Grok, Gemini app, Perplexity) that support custom MCP connectors. Same tools, plus inline app rendering inside the chat where the client supports it.

Path 1: HTTP API

Three things make this path work: the prompt below, the canonical guide at buildy.so/llms-full.txt that the prompt points your agent at, and the OpenAPI spec the guide links for the full route list.

Copy the prompt

Paste this into your agent. It points the agent at buildy.so/start.md, which detects this 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.

Help me figure out what to build. Look at what you know about me and suggest 2-3 apps that fit, or ask me up to 3 short questions to find an idea.

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 app URL plus a bld_app_* token to update it later.
PUT /app/<id>: update an existing app with the same body shape.
GET /app: list apps for a signed-in user (bld_user_* token).
POST /app/<id>/api/<op>: call an app's backend operation from outside the UI.

Module shape, capabilities, error kinds, and the device-code pairing flow live in llms-full.txt. Machine-readable contract: openapi.json.

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:

Client	MCP support	Walkthrough
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. Anthropic docs.	Setup
ChatGPT	In the ChatGPT Apps directory — open the Buildy listing and click Connect (no Developer mode needed). Fallback: a Developer-mode custom connector if your workspace hides the directory. OpenAI docs.	Landing
Grok	Full. Native Custom Connectors on grok.com. Paste an MCP URL and Grok auto-discovers tools. xAI docs.	Setup
Gemini	Partial. Gemini CLI and Gemini Enterprise support custom MCP servers. The consumer Gemini web/mobile app does not yet. Gemini CLI docs.	Setup
Perplexity	Partial. Local MCP shipped in the macOS app; remote custom connectors are rolling out to paid (Pro / Max) subscribers. Perplexity docs.	Setup

Codex users should prefer the public Buildy plugin: codex plugin marketplace add https://github.com/tambo-labs/buildy-codex-plugin.git. 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. Paste-strings and per-client MCP config live in buildy.so/clients.txt. For a client-agnostic authoring skill and agent instructions, see the public 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 buildy.so/start.md, which detects your connected Buildy tools and walks the build.

Help me figure out what to build. Look at what you know about me and suggest 2-3 apps that fit, or ask me up to 3 short questions to find an idea.

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. (Maintainers: when a tool is added or removed in the server, update this table; a regression test in apps/server fails if the two drift.)

Tool	What it does
`create_app`	Store an agent-authored ES module plus optional UI and CSS, and render it inline. Returns a machine API `url` plus a token-free `shareUrl` to give the user.
`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`	Render an existing app inline (when the client supports it) 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, so an agent can inspect or revise it.
`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. Provide `text`, a `sourceUrl` the server fetches, or tiny `dataBase64`.
`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 can open it with no login and read+write its data. On the main origin visitors share one data pool (warn that anyone can wipe it); at a confirmed custom domain each anonymous visitor gets a per-visitor isolated jar. Sharing via `share_app` alone never sets `public_at`.
`unset_public`	Make a public app private again; anonymous visitors can no longer open it.
`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:

Member	What it does
`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<BuildyUser \| null>`: 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`.

Contact

Questions, bug reports, or partnership inquiries: [email protected].

See also our Privacy Notice and Terms of Use.