Skip to main content

AI Assistant Setup

Connect your favorite AI assistants to Buildable for intelligent development assistance. Get contextual help with coding, planning, and project management directly in your preferred tools.

Supported AI Assistants​

Code Editors with AI​

Standalone AI Assistants​

General Setup Process​

All AI assistant integrations follow a similar pattern:

1. Generate API Key​

  1. Navigate to your project's Integrations page
  2. Click "Generate New API Key"
  3. Choose appropriate permissions:
    • Read-only - View project data only
    • Read/Write - Full access to tasks and discussions
    • Admin - Project management capabilities

2. Install MCP Client​

# Global installation
npm install -g @bldbl/mcp

# Or use npx (recommended)
npx @bldbl/mcp

3. Configure Environment​

Set up environment variables for your system:

# Required
export BUILDABLE_API_KEY="your_api_key_here"
export BUILDABLE_PROJECT_ID="your_project_id"

# Optional configuration
export BUILDABLE_API_URL="https://bldbl.dev/api"
export BUILDABLE_AI_ASSISTANT_ID="your_assistant_name"
export BUILDABLE_DEBUG="false"

4. Connect Your Tool​

Each AI assistant has specific configuration requirements - see individual integration guides for details.

Common AI Assistant Commands​

Once connected, you can use these commands with any MCP-compatible AI assistant:

Project Overview​

  • @buildable What is this project about?
  • @buildable Show me the project requirements
  • @buildable What's the current project status?
  • @buildable What are the key milestones?

Task Management​

  • @buildable What should I work on next?
  • @buildable Show me all pending tasks
  • @buildable Mark task [ID] as completed
  • @buildable Create a task for [description]
  • @buildable What are the dependencies for task [ID]?

Code Assistance​

  • @buildable Help me implement task [ID]
  • @buildable Review this code for correctness
  • @buildable What files need to be modified for this feature?
  • @buildable Generate tests for this function
  • @buildable Explain this code in the context of the project

Planning & Architecture​

  • @buildable What's the technical architecture?
  • @buildable How should I structure this new feature?
  • @buildable What are the best practices for this project?
  • @buildable Review my implementation approach

Discussions & Collaboration​

  • @buildable Start a discussion about [topic]
  • @buildable What are the latest team discussions?
  • @buildable Summarize the discussion about [topic]
  • @buildable Add my thoughts to discussion [ID]

Best Practices​

Effective Prompting​

Be Specific

❌ "Help me with the code"
✅ "Help me implement the user authentication for task #23"

Reference Context

❌ "Create a function"
✅ "Create a function for task #15 that validates email addresses according to our project requirements"

Use Task IDs

❌ "I'm working on the login feature"
✅ "I'm working on task #23: Implement OAuth login flow"

Workflow Integration​

Start with Overview

  1. Ask for project summary when starting
  2. Get recommended next tasks
  3. Focus on one task at a time
  4. Update progress regularly

Code Review Process

  1. Implement feature for specific task
  2. Ask AI to review code in project context
  3. Get suggestions for improvements
  4. Update task status when complete

Planning Sessions

  1. Discuss new features with AI
  2. Break down into specific tasks
  3. Validate against project architecture
  4. Create tasks directly from conversation

Security Considerations​

API Key Management

  • Use environment variables, never hardcode keys
  • Generate separate keys for different tools
  • Rotate keys regularly (every 90 days)
  • Revoke unused or compromised keys immediately

Permissions

  • Use read-only keys for AI assistants that only need to view data
  • Limit write permissions to trusted integrations
  • Monitor API usage for unusual activity
  • Review audit logs regularly

Data Privacy

  • Be mindful of sensitive information in prompts
  • Use project-specific keys to limit access scope
  • Avoid sharing API keys with unauthorized team members
  • Keep local environment variables secure

Troubleshooting​

Common Issues​

AI Assistant Can't See Project Data

  1. Verify API key is correctly set in environment
  2. Check that project ID matches your Buildable project
  3. Ensure MCP client is properly installed
  4. Test API connection manually

Commands Not Working

  1. Restart your AI assistant after configuration changes
  2. Check that MCP client is running
  3. Verify environment variables are loaded
  4. Enable debug mode to see detailed logs

Permission Errors

  1. Check API key permissions in Buildable dashboard
  2. Ensure key hasn't expired
  3. Verify project access rights
  4. Generate new key if needed

Connection Timeouts

  1. Check internet connection
  2. Verify API URL is accessible
  3. Try increasing timeout values
  4. Test with different MCP client version

Debug Mode​

Enable detailed logging to troubleshoot issues:

# Enable debug logging
export BUILDABLE_DEBUG=true

# Run MCP client with verbose output
npx @bldbl/mcp --verbose

This will show detailed logs of MCP client operations and help identify connection or configuration issues.

Getting Help​

Documentation

Community Support

Professional Support

  • Priority support for Pro/Enterprise users
  • Custom integration assistance
  • Team training and onboarding

What's Next?​