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

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 section provides the MCP server URL and the connection details for different clients:

• Direct Token Setup for agents that use a bearer token, such as Codex

• OAuth Setup for clients that expect OAuth credentials, such as Claude

For direct-token clients, store the token in a user-local env file outside the repo, for example:

~/.config/buzzy/buzzy-mcp.env

At minimum, that file should contain:

BUZZY_MCP_URL=...
BUZZY_MCP_BEARER_TOKEN=...
BUZZY_MCP_TIMEOUT_SECONDS=120

For OAuth clients, copy the client ID and client secret from MCP Access and enter them in the client's connector setup screen.

Connect Your Agent

Connection details vary by client, but the pattern is the same:

1. add Buzzy as an MCP server or connector

2. use the Buzzy MCP server URL from MCP Access

3. authenticate with either a bearer token or OAuth

4. reload the agent so the Buzzy MCP tools are available

Useful prompt:

Use the Buzzy MCP connection and bootstrap the setup for this project. Do not make app changes yet.

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.

For Codex, a useful first prompt is:

You are an agent for building Buzzy applications using Buzzy's MCP server.

This repo is currently empty, and you will need to connect to Buzzy's MCP server and follow the bootstrapping instructions to set up the repo. The connection details you need are contained in this file: ~/.config/buzzy/buzzy-mcp.env

All I want you to do right now is read the configuration file, connect to the Buzzy MCP server, and follow the server's bootstrapping instructions.

For Claude or another OAuth client, refer to the MCP connection configured in that client instead of a local env file:

You are an agent for building Buzzy applications using Buzzy's MCP server.

This repo is currently empty, and you will need to connect to Buzzy's MCP server and follow the bootstrapping instructions to set up the repo. The connection details are configured in the Buzzy MCP connector.

All I want you to do right now is connect to the Buzzy MCP server and follow the server's bootstrapping instructions.

Work in Review Gates

Builder MCP works best when the agent builds in stages and pauses for review.

Typical stages are:

1. brief

2. flows

3. data model

4. theme

5. blueprint

6. screens

7. sample data

8. 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:

1. inspect the current state

2. make one coherent change

3. save it

4. re-open or re-read the app state

5. 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