# Let an AI agent write and plan a blueprint

Connect Claude Code or another MCP client to the blueprint tools, and see what an agent can and cannot do.

An AI coding agent, such as Claude Code, Cursor or Codex, can write a blueprint for you and plan it. You read the plan, and the agent applies it only after you agree. The agent connects through MCP (Model Context Protocol), an open standard that lets an AI assistant call tools on your computer.

```bash
claude mcp add buildbase \
  -e BUILDBASE_SERVER_URL=https://api.console.buildbase.app \
  -e BUILDBASE_API_TOKEN="$BUILDBASE_API_TOKEN" \
  -- npx -y @buildbase/sdk blueprint mcp
```

> **Note:**

- [Node.js](https://nodejs.org) 18 or later, on the computer the agent runs on.
- An API key with the owner or admin role. [Before you start](/blueprints/overview#before-you-start) shows how to make one.
- An AI agent that can use MCP tools.



`npx -y @buildbase/sdk blueprint mcp` starts a small server that offers the blueprint tools to the agent. It talks to the agent through its input and output (this is called **stdio**), so it opens no network port on your computer. It sends your blueprints to the same BuildBase routes as the [command line](/blueprints/cli). The `blueprint` commands are in the @buildbase/sdk package from 1.0.0.

## Set it up in Claude Code

1. In a terminal, set your API key without showing it, as on the [command line page](/blueprints/cli#set-the-two-variables-safely).
2. In the folder of your project, run the `claude mcp add` command above. The server is [https://api.console.buildbase.app](https://api.console.buildbase.app) on BuildBase's cloud, or your own server when self-hosted.
3. Start Claude Code in that folder and type `/mcp`. The `buildbase` server should be listed as connected.

Claude Code saves the two values in its settings on your computer, so the key stays there until you remove the server with `claude mcp remove buildbase`. Use a key you can deactivate, and deactivate it when you are done.

If your blueprint names values as `${env:NAME}`, such as a Stripe key, give the server each value and list each name in `BUILDBASE_BLUEPRINT_ENV`, comma separated. The server reads a variable from its own environment only when that list names it, because the agent writes the blueprint and your shell holds other secrets:

```bash
claude mcp add buildbase \
  -e BUILDBASE_SERVER_URL=https://api.console.buildbase.app \
  -e BUILDBASE_API_TOKEN="$BUILDBASE_API_TOKEN" \
  -e STRIPE_SECRET_KEY="$STRIPE_SECRET_KEY" \
  -e BUILDBASE_BLUEPRINT_ENV=STRIPE_SECRET_KEY \
  -- npx -y @buildbase/sdk blueprint mcp
```

## Set it up in another MCP client

Most MCP clients read a JSON settings file. Add the server to it:

{/* json: not a blueprint */}

```json title="MCP client settings"
{
  "mcpServers": {
    "buildbase": {
      "command": "npx",
      "args": ["-y", "@buildbase/sdk", "blueprint", "mcp"],
      "env": {
        "BUILDBASE_SERVER_URL": "https://api.console.buildbase.app",
        "BUILDBASE_API_TOKEN": "your-organization-id:your-key-secret",
        "STRIPE_SECRET_KEY": "your-stripe-test-key",
        "BUILDBASE_BLUEPRINT_ENV": "STRIPE_SECRET_KEY"
      }
    }
  }
}
```

- `-y` lets `npx` download the package without asking.
- The server takes its settings from these environment variables, not from options such as `--server-url`.
- For each `${env:NAME}` your blueprint uses, add its value to `env` and its name to `BUILDBASE_BLUEPRINT_ENV`, comma separated (`STRIPE_SECRET_KEY,SMTP_PASSWORD`). A variable that list does not name is not read, even when it is set, and a `BUILDBASE_*` name never is. Or let the agent pass an `envFile` inside the folder instead.
- File paths the agent passes, such as `buildbase.blueprint.json`, are read from the folder the client starts the server in.
- Keep this settings file private: it holds your API key.

## The tools

| Tool                 | What it does                                                                                                                             | Changes anything? |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `blueprint_schema`   | Returns the JSON Schema: every section and field, each with a description                                                                | No                |
| `blueprint_export`   | Returns your organization's current setup as a blueprint, with each secret as a `${env:NAME}`                                            | No                |
| `blueprint_validate` | Checks a file and lists the problems and the `${env:NAME}` values that are not set                                                       | No                |
| `blueprint_plan`     | Compares a file with your organization, and returns the plan as text and its `planHash`                                                  | No                |
| `blueprint_apply`    | Applies a file. Needs the `planHash` from `blueprint_plan`, and BuildBase refuses it if the plan has changed since                       | Yes               |
| `environment_list`   | Lists your [development and staging environments](/quick-start/environments), each with its key                                          | No                |
| `environment_create` | Adds an environment (owner or admin) and points the app's `.env.local` at it. The client secret goes to `.env.local`, never to the agent | Yes               |

The two environment tools do what `buildbase env list` and `buildbase env create` do, as the member `buildbase login` signed in, so they need that login rather than the API key above. Creating one uses one of your plan's environments, so the agent asks you first.

`blueprint_validate`, `blueprint_plan` and `blueprint_apply` take these inputs. Each tool checks what it gets, and refuses a name it does not know or a value of the wrong kind.

| Input       | What it is                                                                                                                                                                                                                    |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file`      | The path of the blueprint file. The default is `buildbase.blueprint.json`                                                                                                                                                     |
| `blueprint` | The blueprint itself, instead of a file                                                                                                                                                                                       |
| `envFile`   | A file of `NAME=value` lines with the values for `${env:NAME}`, inside the folder. A variable from the server's environment that `BUILDBASE_BLUEPRINT_ENV` names wins; a `BUILDBASE_*` name is never read, even from the file |
| `prune`     | `blueprint_plan` and `blueprint_apply`: also delete what the file no longer lists, for the kinds in `policy.prune`                                                                                                            |
| `planHash`  | `blueprint_apply` only, and required: the `planHash` that `blueprint_plan` returned                                                                                                                                           |
| `outputs`   | `blueprint_apply` only: where shown-once values go. The default is `.buildbase/blueprint-outputs.json`                                                                                                                        |

## What the agent can and cannot do

The agent can:

- read the schema and your current setup, write a blueprint, check it and plan it;
- apply a plan, with the `planHash` of that plan;
- do only what your API key's role allows, because every change goes through the same checks as a click in the console.

The tools never:

- return the value of a secret. The file holds `${env:NAME}`, and the values come from the server's environment (only the names `BUILDBASE_BLUEPRINT_ENV` lists) or the `envFile`, and go only to BuildBase;
- return a shown-once value. Webhook signing secrets, new API keys and client secrets go to the outputs file instead, readable only by your user account on a Mac or Linux, and the tool result names that file;
- delete anything unless the file lists that kind in `policy.prune` and the agent also passes `prune: true`.

An agent that can also read the files on your computer could open the outputs file or an `envFile` with its own tools. Give it the same care as any program you let read your files, and move the shown-once values to your secret store soon after an apply.

## Why apply needs the plan hash

`blueprint_plan` returns a `planHash`: a short code that stands for that exact plan. `blueprint_apply` needs it: without it, or with an empty one, the tool refuses before it sends anything, and BuildBase refuses too. When the agent applies, BuildBase makes the plan again and compares the codes. If the organization or the file changed after the plan you saw, the codes differ and BuildBase refuses, with this message:

{/* message: os */}

```text
This organization or the file changed after that plan was made, so nothing was applied. Plan again, review the new plan, then apply it.
```

So what is applied is exactly the plan the agent fetched, and never a newer one that nobody has read. The hash does not make the agent wait for you: that is up to the agent and your instructions. Claude Code asks you before it calls a tool, unless you allowed that tool before. Keep that question on for `blueprint_apply`, and read the plan before you say yes.

## A prompt to give your agent

Copy this into your agent, and replace the last line with what you want. The console's **Copy a prompt for an AI agent** button gives a similar prompt.

```text
Help me set up my BuildBase organization with a blueprint.

1. Call blueprint_schema to learn the fields, and blueprint_export to see how my organization is set up now.
2. Edit buildbase.blueprint.json to describe what I ask for. Leave out anything I did not mention.
3. Write every secret (passwords, API keys, client secrets) as "${env:NAME}". Never write a real secret into the file.
4. Call blueprint_validate and fix every problem it lists.
5. Call blueprint_plan and show me the whole plan in plain words.
6. Do not call blueprint_apply until I say yes. Then apply with the planHash of the plan I agreed to.

What I want: a support role that can read and update users, and a webhook to https://hooks.acme.example/buildbase for each new sign-up.
```

## This is not your app's MCP server

These tools set up your BuildBase organization. To let agents use your own product on behalf of its users, see [MCP and agents](/reference/mcp-agents) instead, and [Connect an AI agent](/agents/connect-an-agent) for adding that server to each agent client.

## Next steps

- [File format](/blueprints/file-format) - what the agent writes, section by section
- [Troubleshooting](/blueprints/troubleshooting) - what each message means and what to do
- [File reference](/blueprints/reference) - every field a blueprint can set