MCP

The Buildpad MCP allows AI assistants to interact with the component registry. You can browse available components, search for specific ones, and install them directly into your project using natural language.

For example, you can ask an AI assistant to “Generate a CollectionForm for a products collection” or “Add the input, select-dropdown, and datetime components to my project”.

Quick Start


# Using npx (recommended — no install required)
npx @buildpad/mcp@latest

Restart your MCP client and try the following prompts:

“List all available Buildpad components”
“Add the input, select-dropdown, and datetime components to my project”
“Generate a CollectionForm for a products collection”

What is MCP?

Model Context Protocol (MCP) is an open protocol that enables AI assistants to securely connect to external data sources and tools. With the Buildpad MCP, your AI assistant gains direct access to:

Browse Components — List all available components, their categories, and dependencies from the registry
Read Source Code — Access full component and lib-module source code. The sources ship inside the MCP package, so this works offline
Install with Natural Language — Add components using simple conversational prompts like “add a collection form”
Generate Code — Generate forms, interfaces, and usage examples
RBAC Patterns — Get role-based access control setup patterns for DaaS applications

How It Works

The MCP acts as a bridge between your AI assistant, the component registry, and the Buildpad CLI.

Registry — Each MCP release embeds the Buildpad component registry (registry.json) of its release. It also bundles every source file that the registry lists, checked against the registry’s hashes at build time
Natural Language — You describe what you need in plain English
AI Processing — The assistant translates your request into registry commands
Component Delivery — The CLI installs the components in your project and rewrites their imports to your paths

The source tools (get_component, copy_component and the component resources) return the files exactly as published, with @buildpad/* imports. If a file cannot be read, the tool returns an error that lists the missingSources. It never returns an empty result. To install a component with its imports rewritten for your project, use npx @buildpad/cli add <name>.

Available Tools

Tool	Description
`list_components`	List all available components with descriptions and categories
`get_component`	Get detailed information and source code for a specific component
`list_packages`	List all Buildpad packages with their exports
`get_install_command`	Get CLI commands to install components by name or category
`copy_component`	Get complete source code and file structure to manually copy a component
`generate_form`	Generate a CollectionForm with specified collection and fields
`generate_interface`	Generate a field interface component with custom props
`get_usage_example`	Get real-world usage examples with local imports
`get_copy_own_info`	Get detailed information about the Copy & Own distribution model
`get_rbac_pattern`	Get RBAC setup patterns (own_items, role_hierarchy, public_read, multi_tenant, etc.)
`list_lib_modules`	List available CLI lib modules (e.g. external-oauth, supabase-auth, api-routes)
`list_outdated`	List installed components and lib modules whose upstream source changed since they were installed
`get_package_versions`	Get the current registry version for each `@buildpad/*` package
`get_component_changelog`	Get the changelog for a component between the installed and latest version
`get_upgrade_plan`	Preview what an upgrade would change before applying it. Each file is `pristine`, `modified`, `missing`, `untracked` (on disk with no install hash: the CLI overwrites it whatever the strategy, so back up edits first) or `invalid-target` (outside the project or not a regular file; not read)
`apply_upgrade`	Run `npx @buildpad/cli@<MCP version> upgrade` for the project (strategy: `overwrite`, `new-file` or `three-way`). Naming a component also upgrades the outdated lib modules it depends on

apply_upgrade runs the CLI release that matches the MCP’s own version, so the upgrade applies the same registry that get_upgrade_plan showed. The tool refuses to run if the project, or an entry it would upgrade, was installed from a newer release, because that would downgrade it. A failed CLI run returns isError: true. In that case, update the MCP (npx -y @buildpad/mcp@latest). Upgrading everything (leave out components) is the safest choice.

Configuration

VS Code

Add to your project’s .vscode/mcp.json:

.vscode/mcp.json


{
  "servers": {
    "buildpad": {
      "command": "npx",
      "args": ["@buildpad/mcp@latest"]
    }
  }
}

After adding the configuration, open .vscode/mcp.json and click Start next to the Buildpad server.

Or add to your VS Code settings.json:

settings.json


{
  "mcp": {
    "servers": {
      "buildpad": {
        "command": "npx",
        "args": ["@buildpad/mcp@latest"]
      }
    }
  }
}

Reload VS Code window (Cmd+Shift+P → “Developer: Reload Window”).

Kiro

Add to your project’s .kiro/mcp.json:

.kiro/mcp.json


{
  "mcpServers": {
    "buildpad": {
      "command": "npx",
      "args": ["@buildpad/mcp@latest"]
    }
  }
}

After adding the configuration, enable the Buildpad MCP in Kiro Settings. Once enabled, you should see a green dot next to the Buildpad server in the MCP list.

Claude Code

Add to your project’s .mcp.json:

.mcp.json


{
  "mcpServers": {
    "buildpad": {
      "command": "npx",
      "args": ["@buildpad/mcp@latest"]
    }
  }
}

Restart Claude Code and run /mcp to verify the Buildpad server is connected.

Local Build

For development within the monorepo, build the MCP locally:


cd /path/to/buildpad-ui
pnpm build:mcp

Then configure your MCP client to use the local build:

settings.json


{
  "mcp": {
    "servers": {
      "buildpad": {
        "command": "node",
        "args": [
          "/absolute/path/to/buildpad-ui/packages/mcp-server/dist/index.js"
        ]
      }
    }
  }
}

RBAC Patterns

The get_rbac_pattern tool provides step-by-step setup patterns for role-based access control in DaaS applications:

Pattern	Description
`own_items`	Users manage their own records, read others’ published items
`role_hierarchy`	Admin → Editor → Viewer cascading permissions
`public_read`	Public read + authenticated write
`multi_tenant`	Organization-level data isolation
`full_crud`	Unrestricted CRUD access
`read_only`	Read-only access

Example Prompts

Browse & Search

“Show me all available components in Buildpad”
“List all selection components”
“Show me the source code for VForm”

Install Components

“Add the input, select-dropdown, and datetime components to my project”
“Install all relational components”
“Bootstrap my project with all Buildpad components”

Generate Code

“Generate a CollectionForm for a products collection”
“Show me how to use the SelectDropdown component”
“Set up RBAC with own_items pattern for articles”
“Generate role hierarchy for Admin, Editor, Viewer”

Copy & Own Model

Buildpad uses the Copy & Own distribution model (similar to shadcn/ui):

Components are copied as source code to your project
Full customization — components become your application code
No external package dependencies for component code
No breaking changes from upstream updates
Works offline after installation

When installed via CLI, imports like @buildpad/hooks are automatically transformed to local paths like @/lib/buildpad/hooks.

Troubleshooting

MCP Not Responding

If the MCP isn’t responding to prompts:

Check Configuration — Verify the MCP is properly configured and enabled in your MCP client
Restart MCP Client — Restart your MCP client after configuration changes
Verify Installation — Ensure npx @buildpad/mcp@latest is accessible
Check Network — Confirm you can access npm for the npx command

Source Tools Return `missingSources`

If get_component or copy_component returns an error with a missingSources list, the MCP package could not read its bundled sources. To fix this:

Clear the npx cache: npx clear-npx-cache
Reinstall the MCP: npx -y @buildpad/mcp@latest
As an alternative, install the component with the CLI: npx @buildpad/cli add <name>

No Tools or Prompts

If you see the “No tools or prompts” message:

Clear the npx cache: npx clear-npx-cache
Re-enable the MCP in your MCP client
Check logs — In VS Code, open the Output panel (Cmd+Shift+U) and select “MCP” from the dropdown

MCP