You run an MCP server that lets AI assistants connect directly to Buildable projects. It provides the API surface and a structured workflow for accessing project context, picking tasks, updating progress, and collaborating with humans, all in a type-safe, AI-friendly way.

How to use

Install and run the MCP server locally, then configure your AI assistant to talk to Buildable through the server. You will use the MCP client to fetch project context, request the next best task, start work on a task, report progress, and complete tasks with notes. When you need human input, you can create discussions. Regular health checks verify the connection to Buildable.

How to install

# Prerequisites: Node.js and npm (or npx)
# Install the MCP server globally
npm install -g @bldbl/mcp

# Or run directly with npx (no installation needed)
npx @bldbl/mcp

PHP, Python, Go, or other runtimes are not required for MCP in this setup; the CLI handles the server lifecycle for you.

## Additional setup and notes

Configure your MCP client with your Buildable API key, project ID, and a stable AI assistant identifier. You can run multiple MCP server configurations to manage different Buildable projects or environments.

Environment variables you will typically provide for each MCP server

export BUILDABLE_API_KEY="bp_your_api_key_here" export BUILDABLE_PROJECT_ID="your-project-id" export BUILDABLE_AI_ASSISTANT_ID="my-ai-assistant"

Optional default API URL if your setup uses a custom endpoint

export BUILDABLE_API_URL="https://bldbl.dev/api"

If you work with multiple projects, you can create separate MCP server entries for each project, each with its own API key and project ID.

Available tools

getProjectContext

Fetches the complete project context, including the current plan, tasks, and recent activity.

getNextTask

Retrieves the next recommended task to work on based on dependencies and priorities.

startTask

Starts working on a specific task with optional approach and timing estimates.

updateProgress

Sends detailed progress updates for the current task.

completeTask

Marks a task as completed with notes and outcomes.

createDiscussion

Opens a discussion for human input when guidance is needed.

healthCheck

Verifies connectivity and health of the MCP integration.

disconnect

Disconnects and cleans up the client connection.