@bldbl/mcp
The @bldbl/mcp server enables AI assistants to manage Buildable projects through the Model Context Protocol (MCP), offering comprehensive development task management and collaboration capabilities:
Project Context: Retrieve detailed project structure, plans, and current state information
Task Management: Start tasks, track progress with completion percentages, mark tasks complete, and identify next priority tasks
Collaboration: Create discussions for questions or blockers requiring human input, specifying urgency levels
Health Check: Verify connection and status with the Buildable API
Integration: Works directly with AI assistants like Claude Desktop and Cursor AI
Multi-Project Support: Manage multiple Buildable projects through distinct configurations
Autonomous Workflow: Enables AI assistants to automatically handle project tasks with minimal human intervention
Offers community support for the Buildable platform through their Discord server.
Supports GitHub OAuth for authentication with NextAuth.js as mentioned in the implementation example.
Serves as the runtime environment for the MCP server, enabling the execution of the Buildable client.
Provides type-safe development with comprehensive type definitions for interacting with the Buildable API.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@bldbl/mcpwhat's the next task for my dashboard project?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@bldbl/mcp
Official MCP client for Buildable - AI-powered development platform that makes any project buildable
This package enables AI assistants (Claude, GPT, etc.) to work directly with Buildable projects using the Model Context Protocol (MCP). AI assistants can get project context, manage tasks, track progress, and communicate with human developers.
๐ What is Buildable?
Buildable (bldbl.dev) is an AI-powered development platform that makes any project buildable. It provides:
AI-Generated Build Plans: Comprehensive project roadmaps with implementation details
Smart Task Management: Automated task breakdown with dependencies and priorities
AI Assistant Integration: Direct integration with Claude, GPT, and other AI assistants
Real-time Collaboration: Seamless human-AI collaboration on complex projects
Progress Tracking: Live monitoring of development progress and blockers
Related MCP server: Autodesk Build MCP Server
๐ Features
Full Project Integration: Get complete project context, plans, and task details
Autonomous Task Management: Start, update progress, and complete tasks
Human Collaboration: Create discussions for questions and blockers
Real-time Progress Tracking: Live updates and status monitoring
Type-Safe API: Full TypeScript support with comprehensive type definitions
Claude Desktop Ready: CLI interface for seamless Claude Desktop integration
๐ฆ Installation
Installing via Smithery
To install @bldbl/mcp for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @buildable/bldbl-mcp --client claudeManual Installation
npm install @bldbl/mcp๐ Quick Start
Step 1: Install the MCP Server
npm install -g @bldbl/mcpStep 2: Get Your Buildable API Key
Go to bldbl.dev and create an account
Create or select a project
Go to Project Settings โ AI Assistants โ Generate API Key
Step 3: Configure Your AI Assistant
๐ค For Claude Desktop:
Add this to your Claude Desktop config file (~/.config/claude/claude_desktop_config.json):
{
"mcpServers": {
"buildable": {
"command": "npx",
"args": ["-y", "@bldbl/mcp"],
"env": {
"BUILDABLE_API_KEY": "bp_your_api_key_here",
"BUILDABLE_PROJECT_ID": "your-project-id",
"BUILDABLE_AI_ASSISTANT_ID": "claude-desktop"
}
}
}
}Minimal setup - only API URL is auto-detected.
โจ For Cursor AI:
Option 1: One-Click Setup (Recommended)
Go to your project on bldbl.dev
Navigate to Integrations
Click "Add to Cursor" - Done! ๐
Option 2: Manual Configuration Add this to your Cursor AI config file:
{
"mcpServers": {
"buildable": {
"command": "npx",
"args": ["-y", "@bldbl/mcp"],
"env": {
"BUILDABLE_API_KEY": "bp_your_api_key_here",
"BUILDABLE_PROJECT_ID": "your-project-id",
"BUILDABLE_AI_ASSISTANT_ID": "cursor-ide"
}
}
}
}Minimal setup - only API URL is auto-detected.
Step 4: Start AI-Powered Development!
Once configured, your AI assistant has access to these powerful tools:
๐๏ธ
get_project_context- Understand your entire project structure๐
get_next_task- Find what to work on next based on prioritiesโถ๏ธ
start_task- Begin working on a specific task๐
update_progress- Report detailed progress updatesโ
complete_task- Mark tasks finished with comprehensive notes๐ฌ
create_discussion- Ask questions when you need human input๐
health_check- Verify connection to Buildable
๐ก Example AI Conversation:
You: "What should I work on next in my project?"
AI: *calls get_project_context & get_next_task*
"I see you're building a React dashboard app. The next
high-priority task is 'Implement user authentication'.
Should I start working on it?"
You: "Yes, go ahead!"
AI: *calls start_task*
"Perfect! I'm starting the authentication task. I'll use
NextAuth.js with GitHub OAuth. Let me break this down:
1. Install dependencies
2. Set up NextAuth config
3. Create login/logout components
4. Add protected routes
I'll update you on progress as I work!"
[AI works and calls update_progress periodically]
AI: *calls update_progress*
"Progress update: 75% complete! I've implemented:
โ
NextAuth.js configuration
โ
GitHub OAuth provider setup
โ
Login/logout components
๐ Currently working on: Protected route middleware
Should I continue with the remaining work?"๐ง Advanced Configuration
Environment Variables
3 environment variables are recommended for proper AI assistant tracking:
export BUILDABLE_API_KEY="bp_your_api_key_here" # Your API key (required)
export BUILDABLE_PROJECT_ID="your-project-id" # Target project (required)
export BUILDABLE_AI_ASSISTANT_ID="my-ai-assistant" # AI Assistant ID (recommended)
# Optional (has smart default):
# export BUILDABLE_API_URL="https://bldbl.dev/api" # API endpoint (default)Why AI Assistant ID matters: This helps you track which AI assistant is doing what work in your project dashboard.
CLI Usage
You can also run the MCP server directly:
# Install globally and use bldbl command
npm install -g @bldbl/mcp
bldbl
# Or run with npx (no installation needed)
npx @bldbl/mcpMultiple Projects
To work with multiple Buildable projects, create different MCP server configs:
{
"mcpServers": {
"buildable-frontend": {
"command": "npx",
"args": ["-y", "@bldbl/mcp"],
"env": {
"BUILDABLE_API_KEY": "bp_frontend_key_here",
"BUILDABLE_PROJECT_ID": "frontend-project-id",
"BUILDABLE_AI_ASSISTANT_ID": "claude-frontend"
}
},
"buildable-backend": {
"command": "npx",
"args": ["-y", "@bldbl/mcp"],
"env": {
"BUILDABLE_API_KEY": "bp_backend_key_here",
"BUILDABLE_PROJECT_ID": "backend-project-id",
"BUILDABLE_AI_ASSISTANT_ID": "claude-backend"
}
}
}
}๐ ๏ธ API Reference
BuildPlannerMCPClient
The main client class for interacting with Buildable projects.
Constructor
new BuildPlannerMCPClient(config: BuildPlannerConfig, options?: ClientOptions)Config Parameters:
apiUrl: Buildable API URL (defaults to 'https://bldbl.dev/api')apiKey: Your Buildable API key (starts with 'bp_')projectId: Target project IDaiAssistantId: Unique identifier for your AI assistanttimeout: Request timeout in milliseconds (default: 30000)
Options:
retryAttempts: Number of retry attempts (default: 3)retryDelay: Delay between retries in ms (default: 1000)
Methods
getProjectContext(): Promise<ProjectContext>
Get complete project context including plan, tasks, and recent activity.
getNextTask(): Promise<NextTaskResponse>
Get the next recommended task to work on based on dependencies and priority.
startTask(taskId: string, options?: StartTaskOptions): Promise<StartTaskResponse>
Start working on a specific task with optional approach and timing estimates.
updateProgress(taskId: string, progress: ProgressUpdate): Promise<ProgressResponse>
Update progress on the current task with detailed status information.
completeTask(taskId: string, completion: CompleteTaskRequest): Promise<CompleteTaskResponse>
Mark a task as completed with detailed completion information.
createDiscussion(discussion: CreateDiscussionRequest): Promise<DiscussionResponse>
Create a discussion/question for human input when you need guidance.
healthCheck(): Promise<{status: string, timestamp: string}>
Check connectivity and health of the Buildable API.
disconnect(): Promise<void>
Properly disconnect and cleanup the client connection.
๐ Authentication
Generate API Key: Go to your Buildable project โ AI Assistant tab โ Generate API Key
Secure Storage: Store your API key securely (environment variables recommended)
Key Format: API keys start with
bp_followed by project and random identifiers
๐ Error Handling
The client includes comprehensive error handling:
try {
const context = await client.getProjectContext();
} catch (error) {
if (error.code === 'UNAUTHORIZED') {
console.error('Invalid or expired API key');
} else if (error.code === 'PROJECT_NOT_FOUND') {
console.error('Project not found or access denied');
} else {
console.error('API error:', error.message);
}
}๐ Development Workflow
Typical AI assistant workflow with Buildable:
Initialize - Connect to Buildable with API key
Get Context - Understand the project structure and current state
Find Work - Get the next priority task
Start Task - Begin working with approach and estimates
Progress Updates - Regular progress reports with details
Ask Questions - Create discussions for blockers or decisions
Complete Task - Finish with comprehensive completion notes
Repeat - Continue with next tasks
๐ Usage Statistics
// Get usage statistics for your AI assistant
const stats = await client.getUsageStats();
console.log(`Tasks completed: ${stats.tasksCompleted}`);
console.log(`Average completion time: ${stats.avgCompletionTime}min`);
console.log(`Success rate: ${stats.successRate}%`);โก CLI Usage
Once installed, you can use the CLI in several ways:
# Run directly with npx (no installation needed)
npx @bldbl/mcp
# Or install globally and use the bldbl command
npm install -g @bldbl/mcp
bldbl
# For Claude Desktop, use the bldbl command in your configEnvironment Variables Required:
BUILDABLE_API_URL- Your Buildable API URLBUILDABLE_API_KEY- Your API key (starts with 'bp_')BUILDABLE_PROJECT_ID- Target project IDBUILDABLE_AI_ASSISTANT_ID- Unique assistant identifier
๐งช Testing
The package includes comprehensive test utilities:
import { createTestClient } from '@bldbl/mcp/test';
// Create a test client with mock responses
const testClient = createTestClient({
mockProject: {
id: 'test-project',
title: 'Test Project'
}
});
// Use in your tests
await testClient.startTask('test-task-id');๐ Links
๐ Homepage: bldbl.dev
๐ Documentation: bldbl.dev/docs
๐ฌ Community: Discord
๐ Support: support@bldbl.dev
๐ฆ NPM Package: npmjs.com/package/@bldbl/mcp
๐๏ธ Built With
TypeScript - Type-safe development
Model Context Protocol (MCP) - Standardized AI assistant communication
Node.js - Runtime environment
REST API - Simple and reliable communication
๐ License
Copyright ยฉ 2025 Buildable Team. All rights reserved.
This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.
Made with โค๏ธ by the Buildable team
Buildable is a commercial AI-powered development platform. Visit bldbl.dev to get started.
๐ Support
Documentation: https://bldbl.dev/docs
Email: support@bldbl.dev
Website: https://bldbl.dev
Built with โค๏ธ by the BuildPlanner team
Available Tools
7 toolscomplete_taskD
| Name | Required | Description | Default |
|---|---|---|---|
| completion_notes | Yes | Notes about task completion | |
| documentation_updated | No | Whether documentation was updated | |
| files_modified | No | List of files that were modified | |
| task_id | Yes | The ID of the task to complete | |
| testing_completed | No | Whether testing was completed | |
| time_spent | No | Total time spent in minutes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_discussionD
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Detailed question or discussion content | |
| tags | No | Tags to categorize the discussion | |
| title | Yes | Title of the discussion/question | |
| urgency | No | Urgency level of the question |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_next_taskD
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_project_contextD
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
health_checkD
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
start_taskD
| Name | Required | Description | Default |
|---|---|---|---|
| approach | No | Optional approach or strategy for the task | |
| estimated_duration | No | Estimated duration in minutes | |
| notes | No | Optional notes about the task | |
| task_id | Yes | The ID of the task to start |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_progressD
| Name | Required | Description | Default |
|---|---|---|---|
| challenges | No | Any challenges or blockers encountered | |
| completed_steps | No | List of completed steps | |
| current_step | No | Current step being worked on | |
| files_modified | No | List of files that were modified | |
| notes | No | Additional notes | |
| progress | Yes | Progress percentage (0-100) | |
| status_update | Yes | Brief status update message | |
| task_id | Yes | The ID of the task being updated | |
| time_spent | No | Time spent in minutes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
7 tool updates
v1.0.0- First observed
complete_task - First observed
create_discussion - First observed
get_next_task - First observed
get_project_context - First observed
health_check - First observed
start_task - First observed
update_progress
TDQS
The tools have distinct purposes with minimal overlap: 'complete_task' and 'start_task' are clearly different lifecycle stages, while 'get_next_task', 'get_project_context', and 'update_progress' serve unique informational or update functions. However, 'create_discussion' might be ambiguous in relation to task management, as it could overlap with task-related communication.
All tool names follow a consistent verb_noun pattern using snake_case, such as 'complete_task', 'create_discussion', and 'get_next_task'. This uniformity makes the tool set predictable and easy to understand, with no deviations in naming conventions.
With 7 tools, the count is well-scoped for a task or project management server. It covers core operations like starting, completing, and tracking tasks, along with auxiliary functions like health checks and discussions, without being overly sparse or bloated.
The tool set covers basic task lifecycle (start, complete, progress update) and project context, but lacks obvious operations like listing tasks, updating task details, or deleting tasks. This creates minor gaps that agents might need to work around, though core workflows are partially supported.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Share one project context across ChatGPT, Claude, Telegram and any MCP client.
Project management MCP for AI agents with safe task reads and writes.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yoโฆ
Nifty's MCP server โ exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA Model Context Protocol server that enables AI assistants like Claude to perform Python development tasks through file operations, code analysis, project management, and safe code execution.9MIT
- -licenseNot gradedqualityNot gradedmaintenanceA Model Context Protocol server implementation for Autodesk Construction Cloud Build that enables AI assistants to manage construction issues, RFIs, submittals, photos, forms, and costs through natural language.-
- AlicenseNot gradedqualityCmaintenanceA comprehensive Model Context Protocol toolkit that transforms AI assistants into autonomous agents capable of executing real-world tasks across filesystems, web requests, Git workflows, databases, system commands, and AI integrations.MIT
- AlicenseAqualityDmaintenanceConnect AI agents to your Todoist tasks via the Model Context Protocol (MCP).281MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/chunkydotdev/bldbl-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server