Getting started with Builder MCP
Use this page before any Builder MCP workflow. It covers the common setup for new apps, template-based apps, and edits to existing apps.
What You Need
a Buzzy workspace with MCP access enabled
an MCP-capable agent such as Codex, Claude Code, or Claude Desktop
a normal git repo for the agent to work in
access to screenshots or browser inspection if you want visual review
for template or existing-app work, the editor URL or app ID of the source app
Codex, Claude Code, Cursor, Antigravity, and other compatible tools apply their own subscription, usage allowance, billing, and limits. A Buzzy Deployment does not include a recurring monthly AI credit allowance. Direct Adapt work on a copied template or existing app does not require Buzzy AI generation credits. A Create workflow that asks Buzzy to generate a new brief, flows, data model, theme, blueprint, sample data, or screens requires separately purchased Buzzy AI credits or a supported bring-your-own OpenAI API key. See Builder MCP: Create vs Adapt.
AI output quality and cost depend on the app, your instructions, the selected model, and current model performance. AI can make mistakes. Keep human review in the workflow and test important behavior before publishing.
Keep access tokens, client secrets, OAuth credentials, and local env files out of the repo. Do not paste secrets into prompts, screenshots, issue comments, or docs.
Get MCP Connection Details
In the Buzzy workspace, open your profile menu, launch Account Settings, and go to Developer -> MCP Access. This screen has everything you might need:
the MCP server URL (for example
https://app.buzzy.buzz/mcp) — this is all you need for the recommended setupa bearer token — only for the token-based alternative below
OAuth client ID / secret — only for connectors that ask for them explicitly
Recommended: just use the URL. For Codex and Claude Code, the smoothest setup is OAuth through the client's own CLI — you give it the server URL, it opens a browser login and registers itself automatically. There are no tokens or client secrets to copy, store, or rotate. Skip straight to Connect Your Agent.
Alternative: bearer token and env file
Use this only if your client doesn't support OAuth, or you want a portable fallback (for example for scripts or CI). Copy a bearer token from MCP Access and store it in a user-local env file outside the repo, for example:
At minimum, that file should contain:
Some connectors instead ask for an OAuth client ID and secret — copy those from MCP Access and paste them into the connector's setup screen. Clients that register themselves (Codex, Claude Code) don't need them.
Connect Your Agent
Connection details vary by client, but the pattern is the same:
add Buzzy as an MCP server or connector, pointing at the server URL from MCP Access (for example
https://app.buzzy.buzz/mcp)log in with OAuth — or, as a fallback, supply a bearer token
reload the agent so the Buzzy MCP tools are available
For Codex and Claude Code, prefer the OAuth commands below: you add the server with just the URL, and the client handles the browser login and registers itself for you — nothing to copy or paste. Reach for the bearer-token option only when OAuth isn't available or doesn't complete. Replace the URL with the one from your MCP Access screen.
Claude Code
Option A — OAuth (recommended). Add the server with no credentials, then log in through the browser:
Then start Claude Code and run /mcp, choose buzzy, and complete the browser login. Claude Code registers itself automatically and stores the token for you.
Option B — bearer token. Pass the token from MCP Access as an Authorization header:
This skips OAuth entirely, so it is also the reliable fallback if the OAuth login does not complete (see Troubleshooting).
Codex
Use the codex mcp commands — they write the entry to ~/.codex/config.toml for you, so you don't edit it by hand.
Option A — OAuth (recommended). Add the server, then log in through the browser:
Codex registers itself and stores the token. If it needs a fixed callback port, add a top-level mcp_oauth_callback_port = 5555 to ~/.codex/config.toml and run codex mcp login buzzy again.
Option B — bearer token. Export the token from MCP Access, then add the server pointing at that variable:
Make sure BUZZY_MCP_BEARER_TOKEN is set in the environment Codex runs in (for example exported from your user-local env file).
Check it registered with codex mcp list, or remove it with codex mcp remove buzzy.
Other clients
For Claude Desktop or another connector, add Buzzy as a custom MCP/HTTP connector using the URL from MCP Access, then authenticate with OAuth or the bearer token as the client allows.
Useful prompt once connected:
Troubleshooting the connection
Incompatible auth server: does not support dynamic client registration— the OAuth client tried to register itself but the server it reached does not support it. Confirm you are using the URL from MCP Access, then either retry the OAuth login or switch to the bearer token method above, which does not use OAuth at all.401 Unauthorized/Invalid or expired token— bearer tokens expire. Re-copy a fresh token from MCP Access and update your client config or env file.OAuth login opens but never connects — remove the server and re-add it with the bearer-token method as a fallback. In Claude Code:
claude mcp remove buzzy, then re-run the Option B command above.
Bootstrap the Repo
Buzzy Builder MCP is guide-driven. The agent should read the Buzzy MCP guides, install the repo-local helper files, and prepare the local mirror before building or editing an app.
When bootstrap is complete, you should expect repo-local Buzzy scaffolding such as:
AGENTS.md.buzzy/.agents/skills/workspace bootstrap state files
That scaffolding gives the agent the local guides, shell helpers, artifact mirrors, and workflow rules needed for the rest of the project.
If you connected with OAuth (the recommended setup for Codex and Claude Code), the agent is already authenticated — just point it at the bootstrap:
If you used the bearer-token env file instead, tell the agent where it is so it can read the connection details:
Work in Review Gates
Builder MCP works best when the agent builds in stages and pauses for review.
Typical stages are:
brief
flows
data model
theme
blueprint
screens
sample data
refinements
Approve or redirect at each gate. Early feedback is cheaper than changing the app after screens and data are already built.
Useful review prompts:
Move on to the brief review summary and stop there.Move on to flows and then the data model. Stop after each one if there is anything I should review.Can I get the workspace URL for this app?Can I get the editor URL too?Can I have a preview URL for the app?Please make a plan before changing these screens.Use Playwright to inspect this workflow and summarize issues before changing anything.
Verification Habits
Ask the agent to verify the exact thing it changed.
For visual work, use screenshots.
For search, filtering, forms, or navigation, exercise the actual runtime path.
For permission-sensitive work, test both allowed and denied users.
For broad screen changes, inspect a small batch before generating or changing everything.
The most reliable loop is:
inspect the current state
make one coherent change
save it
re-open or re-read the app state
verify with concrete evidence
Template and Existing-App Safety
When starting from a template or editing an existing app:
identify the source app clearly by editor URL or app ID
expect source templates to be treated as protected reference material by the Buzzy guides, skills, and app locks
create or edit the intended target app only
ask the agent to summarize what it found before changing anything
watch for leftover source-domain wording in briefs, data, screens, and sample content
Last updated