> For the complete documentation index, see [llms.txt](https://docs.buzzy.buzz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buzzy.buzz/the-building-blocks/mcp/buzzy-builder-mcp/getting-started.md). # 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 {% hint style="warning" %} 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. {% endhint %} ## 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 setup * a **bearer token** — only for the token-based alternative below * **OAuth client ID / secret** — only for connectors that ask for them explicitly {% hint style="success" %} **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](#connect-your-agent). {% endhint %} ### 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: ```bash ~/.config/buzzy/buzzy-mcp.env ``` At minimum, that file should contain: ```bash BUZZY_MCP_URL=... BUZZY_MCP_BEARER_TOKEN=... BUZZY_MCP_TIMEOUT_SECONDS=120 ``` 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: 1. add Buzzy as an MCP server or connector, pointing at the server URL from **MCP Access** (for example `https://app.buzzy.buzz/mcp`) 2. log in with **OAuth** — or, as a fallback, supply a bearer token 3. 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: ```bash claude mcp add --transport http buzzy https://app.buzzy.buzz/mcp ``` 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: ```bash claude mcp add --transport http --header "Authorization: Bearer " buzzy https://app.buzzy.buzz/mcp ``` This skips OAuth entirely, so it is also the reliable fallback if the OAuth login does not complete (see [Troubleshooting](#troubleshooting-the-connection)). ### 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: ```bash codex mcp add buzzy --url https://app.buzzy.buzz/mcp codex mcp login buzzy ``` 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: ```bash export BUZZY_MCP_BEARER_TOKEN= codex mcp add buzzy --url https://app.buzzy.buzz/mcp --bearer-token-env-var BUZZY_MCP_BEARER_TOKEN ``` 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: ``` Use the Buzzy MCP connection and bootstrap the setup for this project. Do not make app changes yet. ``` ### 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: ``` You are an agent for building Buzzy applications using Buzzy's MCP server. This repo is currently empty. Connect to Buzzy's MCP server using the configured connection and follow the bootstrapping instructions to set up the repo. All I want you to do right now is connect to the Buzzy MCP server and follow the server's bootstrapping instructions. ``` If you used the bearer-token env file instead, tell the agent where it is so it can read the connection details: ``` 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. ``` ## 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 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.buzzy.buzz/the-building-blocks/mcp/buzzy-builder-mcp/getting-started.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.