Let an AI agent write and plan a blueprint

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.

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

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. 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.
2. In the folder of your project, run the claude mcp add command above. The server is 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:

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:

{
  "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

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.

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:

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.

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 instead, and Connect an AI agent for adding that server to each agent client.

Next steps

• File format - what the agent writes, section by section
• Troubleshooting - what each message means and what to do
• File reference - every field a blueprint can set