Skip to main content

MCP Integration Guide

The Model Context Protocol (MCP) is Buildable's core integration technology that allows AI assistants to securely access and interact with your project data in real-time.

What is MCP?​

MCP (Model Context Protocol) is an open standard developed by Anthropic that enables AI assistants to connect to external data sources and tools. Buildable implements MCP to provide AI assistants with:

  • Contextual Project Data - Access to plans, tasks, and requirements
  • Real-time Updates - Live synchronization with your project
  • Secure Authentication - API key-based access control
  • Standardized Interface - Works with any MCP-compatible AI tool

How MCP Works with Buildable​

graph LR
    A[AI Assistant] --> B[MCP Client]
    B --> C[Buildable API]
    C --> D[Project Data]
    
    B --> E[Task Management]
    B --> F[Discussions]
    B --> G[Progress Tracking]
  1. AI Assistant makes requests through the MCP protocol
  2. MCP Client translates requests to Buildable API calls
  3. Buildable API processes requests with proper authentication
  4. Project Data is returned to the AI assistant in context

Supported MCP Features​

Core Resources​

Projects

  • Read project metadata and settings
  • Access project plans and requirements
  • View technical specifications

Tasks

  • List and filter project tasks
  • Read task details and dependencies
  • Update task status and progress
  • Create new tasks from conversations

Discussions

  • Read project discussions
  • Create new discussion threads
  • Add responses to existing discussions
  • Get discussion summaries

Tools and Actions​

Task Operations

  • complete_task - Mark tasks as completed
  • start_task - Begin working on a task
  • create_task - Add new tasks to the project
  • update_task_progress - Report progress updates

Project Queries

  • get_project_summary - Overview of project status
  • get_next_tasks - Recommended tasks to work on
  • search_tasks - Find tasks by criteria
  • get_task_dependencies - View task relationships

Discussion Tools

  • create_discussion - Start new project discussions
  • respond_to_discussion - Add responses
  • search_discussions - Find relevant conversations

Setting Up MCP​

Step 1: Install MCP Client​

The Buildable MCP client is available via npm:

# Install globally
npm install -g @bldbl/mcp

# Or use npx for one-time execution
npx @bldbl/mcp

Step 2: Configure Environment​

Set up your environment variables:

# Required
BUILDABLE_API_KEY=your_api_key_here
BUILDABLE_PROJECT_ID=your_project_id

# Optional
BUILDABLE_API_URL=https://bldbl.dev/api  # Default
BUILDABLE_AI_ASSISTANT_ID=your_assistant_id
BUILDABLE_DEBUG=false  # Enable debug logging

Step 3: Connect Your AI Tool​

The setup varies by AI assistant:

Cursor AI

{
  "mcp": {
    "buildable": {
      "command": "npx",
      "args": ["-y", "@bldbl/mcp"]
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "buildable": {
      "command": "npx",
      "args": ["-y", "@bldbl/mcp"]
    }
  }
}

Authentication & Security​

API Key Management​

  • Project-Specific Keys - Each project requires its own API key
  • Granular Permissions - Control read/write access per integration
  • Key Rotation - Regularly rotate keys for enhanced security
  • Revocation - Instantly disable compromised keys

Security Best Practices​

  1. Environment Variables - Never hardcode API keys
  2. Key Rotation - Rotate keys every 90 days
  3. Least Privilege - Use read-only keys when possible
  4. Monitoring - Review API usage logs regularly
  5. Secure Storage - Use secure credential management

Rate Limiting​

Default limits per API key:

  • Free tier: 100 requests/hour
  • Pro tier: 1000 requests/hour
  • Enterprise: Custom limits

Advanced Configuration​

Custom MCP Server​

For advanced users, you can run your own MCP server:

import { MCPServer } from '@buildable/mcp-server';

const server = new MCPServer({
  apiKey: process.env.BUILDABLE_API_KEY,
  projectId: process.env.BUILDABLE_PROJECT_ID,
  baseUrl: process.env.BUILDABLE_API_URL,
});

server.start();

Custom Tools​

Extend the MCP client with custom tools:

// custom-tools.js
export const customTools = {
  analyze_code: async (params) => {
    // Custom code analysis logic
    return { analysis: "Code looks good!" };
  },
  
  generate_tests: async (params) => {
    // Custom test generation
    return { tests: "Generated test suite" };
  }
};

Webhook Integration​

Set up webhooks for real-time updates:

# Environment variable
BUILDABLE_WEBHOOK_URL=https://your-server.com/webhook

# The MCP client will receive notifications for:
# - Task status changes
# - New discussions
# - Project updates

Troubleshooting​

Common Issues​

Connection Failed

# Check API key and project ID
echo $BUILDABLE_API_KEY
echo $BUILDABLE_PROJECT_ID

# Test API connection
curl -H "Authorization: Bearer $BUILDABLE_API_KEY" \
  https://bldbl.dev/api/projects/$BUILDABLE_PROJECT_ID

Permission Denied

  • Verify API key has required permissions
  • Check that the project ID is correct
  • Ensure the key hasn't expired

Rate Limit Exceeded

  • Monitor your API usage in the dashboard
  • Consider upgrading your plan
  • Implement request caching

MCP Client Not Found

# Reinstall the client
npm uninstall -g @bldbl/mcp
npm install -g @bldbl/mcp

# Or use npx
npx -y @bldbl/mcp

Debug Mode​

Enable detailed logging:

BUILDABLE_DEBUG=true npx @bldbl/mcp

This will show:

  • API request/response details
  • MCP protocol messages
  • Error stack traces
  • Performance metrics

Log Analysis​

Check logs for common patterns:

# Connection issues
grep "connection" ~/.buildable/logs/mcp.log

# Authentication failures
grep "401\|403" ~/.buildable/logs/mcp.log

# Rate limiting
grep "429" ~/.buildable/logs/mcp.log

Best Practices​

Efficient Usage​

  1. Cache Responses - Avoid repeated API calls
  2. Batch Requests - Group related operations
  3. Filter Data - Request only needed information
  4. Use Webhooks - Get real-time updates efficiently

AI Assistant Optimization​

  1. Clear Commands - Use specific, actionable prompts
  2. Context Awareness - Reference task IDs and project details
  3. Incremental Updates - Work on tasks step-by-step
  4. Regular Sync - Keep AI assistant updated on progress

Team Collaboration​

  1. Shared Keys - Use team-shared API keys for collaboration
  2. Consistent Setup - Standardize MCP configuration across team
  3. Documentation - Document custom tools and workflows
  4. Monitoring - Track team usage and performance

Getting Help​

What's Next?​