BoxedFlows MCP Server

A Model Context Protocol (MCP) server for BoxedFlows that enables Claude Code to interact with your projects and tasks programmatically.

What is this?

This MCP server allows Claude Code to:

• List and manage your BoxedFlows projects
• Create, read, and update tasks
• Query project and task details
• Automate project management workflows

TL;DR - Quick Setup

# 1. Get your API key from https://boxedbot-boxedflows.vercel.app

# 2. Add MCP server to Claude Code (replace YOUR_API_KEY with your actual key)
claude mcp add boxedflows \
  --scope user \
  --env BOXEDFLOWS_API_URL=https://boxedbot-boxedflows.vercel.app \
  --env BOXEDFLOWS_API_KEY=YOUR_API_KEY \
  -- npx -y mcp-boxedflows

# 3. Restart Claude Code (Cmd+Q)
# 4. Test: /mcp should show "boxedflows · ✔ connected"

Prerequisites

• A BoxedFlows account with API access
• Claude Code CLI installed

Setup Instructions

Step 1: Generate an API Key

You need an API key to authenticate the MCP server with your BoxedFlows account.

Option A: Via Web UI (Recommended)

1. Navigate to your BoxedFlows app: https://boxedbot-boxedflows.vercel.app
2. Go to your account's project dashboard
3. Click the "Connect Claude Code" button (if available)
4. Copy the generated API key

Option B: Via API (if logged in)

curl -X POST https://boxedbot-boxedflows.vercel.app/api/mcp/keys \
  -H "Cookie: your-session-cookie-here" \
  -H "Content-Type: application/json" \
  -d '{"label": "Claude Code MCP"}'

Important: Save your API key securely. It will only be shown once!

Step 2: Configure Claude Code

Run the following command, replacing YOUR_API_KEY with the key from Step 1:

claude mcp add boxedflows \
  --scope user \
  --env BOXEDFLOWS_API_URL=https://boxedbot-boxedflows.vercel.app \
  --env BOXEDFLOWS_API_KEY=YOUR_API_KEY \
  -- npx -y mcp-boxedflows

This registers the MCP server with Claude Code at the user level, making it available across all your projects.

Step 3: Restart Claude Code

Important: MCP server configurations only load on startup.

1. Completely quit Claude Code (Cmd+Q on macOS)
2. Restart Claude Code
3. Open any project (npm link makes it globally available)

Step 4: Verify Setup

Open Claude Code in any project directory and try:

List my BoxedFlows projects

Or check MCP connection status:

/mcp

You should see:

❯ boxedflows · ✔ connected

Claude should now be able to query your projects and tasks from any directory!

Available Tools

Once configured, Claude Code can use these tools:

Projects

• list_projects - List all projects in your account
• get_project - Get details of a specific project
• create_project - Create a new project
• update_project - Update project details (name, status, priority, etc.)

Tasks

• list_tasks - List all tasks (optionally filter by project)
• get_task - Get details of a specific task
• create_task - Create a new task in a project
• update_task - Update task details (title, status, priority, etc.)

Team Setup Guide

For other developers on your team:

1. Generate an API key at https://boxedbot-boxedflows.vercel.app
2. Run:

claude mcp add boxedflows \
  --scope user \
  --env BOXEDFLOWS_API_URL=https://boxedbot-boxedflows.vercel.app \
  --env BOXEDFLOWS_API_KEY=YOUR_API_KEY \
  -- npx -y mcp-boxedflows

3. Restart Claude Code (Cmd+Q and reopen)
4. Test: /mcp should show boxedflows · ✔ connected

Note: Each developer needs their own API key (never share keys).

Example Usage

Once set up, you can ask Claude Code things like:

• "List all my BoxedFlows projects"
• "Show me all tasks in the Authentication project"
• "Create a new task called 'Fix login bug' in the Backend project"
• "Update the API Integration project status to Completed"
• "What tasks are high priority across all projects?"

Troubleshooting

MCP server not showing up

Problem: Claude doesn't recognize BoxedFlows commands after setup.

Solution:

1. Verify the server is registered:

   claude mcp list

2. If missing, re-add it:

   claude mcp add boxedflows \
     --scope user \
     --env BOXEDFLOWS_API_URL=https://boxedbot-boxedflows.vercel.app \
     --env BOXEDFLOWS_API_KEY=YOUR_API_KEY \
     -- npx -y mcp-boxedflows

3. Restart Claude Code completely (Cmd+Q, not just the session)

Authentication errors

Problem: "Unauthorized" or "Invalid API key" errors.

Solution:

1. Verify your API key is correct in ~/.claude.json
2. Check that the API key is active (not expired or deactivated)
3. Generate a new API key via the web UI

Connection errors

Problem: "Failed to connect" or timeout errors.

Solution:

1. Verify BoxedFlows app is accessible: curl https://boxedbot-boxedflows.vercel.app/api/health
2. Check the API URL in your config matches your deployment
3. Test the API directly:

   curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://boxedbot-boxedflows.vercel.app/api/mcp/projects

API key format

Valid API keys start with bf_mcp_ followed by 64 hexadecimal characters.

Example: bf_mcp_1a2b3c4d5e6f...

Development

Running in Development Mode

pnpm dev

This watches for changes and rebuilds automatically.

Testing the Server

You can test the MCP server manually using the MCP inspector:

npx @modelcontextprotocol/inspector \
  node dist/index.js

Make sure to set environment variables:

export BOXEDFLOWS_API_URL="http://localhost:3000"
export BOXEDFLOWS_API_KEY="your_key_here"

Security Notes

• Never commit your API key to version control
• API keys are stored in ~/.claude.json on your local machine only
• Keys are hashed in the database (never stored in plain text)
• You can deactivate keys anytime via the web UI or API

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | BOXEDFLOWS_API_URL | Yes | - | URL of your BoxedFlows instance | | BOXEDFLOWS_API_KEY | Yes | - | Your API key for authentication |

Architecture

Claude Code
    ↓
MCP Protocol (stdio)
    ↓
mcp-boxedflows server (Node.js)
    ↓
HTTP API (/api/mcp/*)
    ↓
BoxedFlows Next.js App
    ↓
Supabase Database

API Endpoints Used

• GET /api/mcp/projects - List projects
• GET /api/mcp/projects/:id - Get project
• POST /api/mcp/projects - Create project
• PATCH /api/mcp/projects/:id - Update project
• GET /api/mcp/tasks - List tasks
• GET /api/mcp/tasks/:id - Get task
• POST /api/mcp/tasks - Create task
• PATCH /api/mcp/tasks/:id - Update task

Support

If you encounter issues:

1. Check this README's troubleshooting section
2. Verify all setup steps were completed
3. Check the BoxedFlows app logs for API errors
4. Ensure your API key is active and valid

License

Private - Part of the BoxedFlows monorepo