BitFlik MCP Server

Model Context Protocol (MCP) server for BitFlik feature flag service.

🎯 What You Can Do

• Instant Onboarding: Start using BitFlik immediately with no signup
• Email Verification: Verify your email for expanded access
• Project Management: Create and manage feature flag projects
• Flag Operations: Create, update, list, and evaluate feature flags

📚 Available Tools

Onboarding Tools

bitflik_start_frictionless

Start using BitFlik instantly with no signup.

No input required

{
  "name": "bitflik_start_frictionless"
}

Returns: Session ID and temporary API key

bitflik_verify_email

Verify your email to expand access.

Requires: session_id, email

{
  "name": "bitflik_verify_email",
  "arguments": {
    "session_id": "sess_abc123",
    "email": "[email protected]"
  }
}

Returns: OTP sent confirmation

bitflik_confirm_otp

Confirm OTP to create permanent account.

Requires: email, otp

{
  "name": "bitflik_confirm_otp",
  "arguments": {
    "email": "[email protected]",
    "otp": "123456"
  }
}

Returns: Permanent API key and project ID

Project Management

bitflik_create_project

Create a new project.

Requires: api_key, name, optional description

bitflik_list_projects

List all your projects.

Requires: api_key

Flag Management

bitflik_create_flag

Create a feature flag.

Requires: api_key, project_id, key, name, value_type, default_value

bitflik_list_flags

List flags in a project.

Requires: api_key, project_id

bitflik_get_flag

Get flag details.

Requires: api_key, project_id, flag_key

bitflik_update_flag

Update a flag.

Requires: api_key, project_id, flag_key

bitflik_evaluate_flag

Evaluate a flag value.

Requires: api_key, project_id, flag_key

🚀 Installation

npm install

🎯 Usage

Start Server:

npm start

With Custom Backend URL:

BITFLIK_API_URL=https://api.bitflik.com npm start

🔄 Onboarding Flow

┌─────────────────────────────────────────────────────────┐
│                                                         │
│  Step 1: bitflik_start_frictionless                    │
│  ├─ No signup required                                 │
│  └─ Get temp API key                                   │
│                                                         │
│  ↓                                                      │
│                                                         │
│  Step 2: bitflik_verify_email                          │
│  ├─ Provide email                                      │
│  └─ OTP sent to email                                  │
│                                                         │
│  ↓                                                      │
│                                                         │
│  Step 3: bitflik_confirm_otp                           │
│  ├─ Enter OTP from email                               │
│  ├─ Account created                                    │
│  └─ Permanent API key issued                           │
│                                                         │
│  ✅ Ready to use BitFlik!                              │
│                                                         │
└─────────────────────────────────────────────────────────┘

💡 Why Only Onboarding?

Problem:

Exposing full API access via MCP would allow:

• Unlimited resource creation
• Bypassing payment/quota systems
• Potential abuse by LLMs
• No conversion tracking

Solution:

Restrict MCP to frictionless onboarding only:

• ✅ Resource limits enforced (10 → 100 calls)
• ✅ Proper user conversion funnel
• ✅ Email collection for marketing
• ✅ Backend enforces all quotas
• ✅ Safe for LLM integration

After Onboarding:

Users get a permanent API key and can:

• Use the full REST API directly
• Create projects and flags
• Integrate into their applications
• Upgrade to paid tiers ($1-5/month)

🎓 Example: AI Assistant Integration

When an AI assistant (like Cursor or Claude) helps a user:

User: "I want to add feature flags to my React app"

AI: "I'll set up BitFlik for you. Let me start..."

[Calls bitflik_start_frictionless]

AI: "✅ Got a temporary API key with 10 free calls! 
     Here's how to use it in your React app:
     
     [generates code example]
     
     After your first 10 calls, I can help you upgrade to 
     100 calls/month for free by verifying your email."

User: "Okay, I've used 8 calls. Can I get more?"

AI: "Sure! What's your email?"

User: "[email protected]"

[Calls bitflik_verify_email]

AI: "✅ Check your email for an OTP code!"

User: "Got it, it's 123456"

[Calls bitflik_confirm_otp]

AI: "🎉 Account created! You now have 100 calls/month.
     Here's your permanent API key: [key]
     
     You can now create projects and flags at bitflik.com"

⚙️ Configuration

Environment Variables:

• BITFLIK_API_URL - Backend API URL (default: http://localhost:8001)

MCP Configuration:

Add to your .mcp.json or MCP settings:

{
  "mcpServers": {
    "bitflik": {
      "command": "node",
      "args": ["/path/to/bitflik/packages/mcp-server/index.js"],
      "env": {
        "BITFLIK_API_URL": "https://api.bitflik.com"
      }
    }
  }
}

🧪 Testing

Test with curl (simulate MCP calls):

# Step 1: Start session
curl -X POST http://localhost:8001/api/llm/frictionless/start

# Step 2: Verify email
curl -X POST http://localhost:8001/api/llm/frictionless/verify-email \
  -H "Content-Type: application/json" \
  -d '{"session_id":"sess_123","email":"[email protected]"}'

# Step 3: Confirm OTP
curl -X POST http://localhost:8001/api/llm/frictionless/confirm-otp \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","otp":"123456"}'

🔐 Security Best Practices

For Production Deployment:

1. Rate Limiting: Backend already enforces quota limits
2. Email Verification: Real OTP emails in production
3. Monitoring: Track MCP usage via TIDs (Transaction IDs)
4. Abuse Prevention: Backend tracks IP, session, usage patterns
5. No Admin Access: MCP server has zero admin privileges

🚀 Usage Notes

• Focused on onboarding and flag/project operations.
• No admin endpoints are exposed via MCP.
• For advanced operations, use the BitFlik REST API with your API key.

🛠️ Development

Run in development:

npm start

Debug mode:

DEBUG=* npm start

Test with MCP Inspector:

npx @modelcontextprotocol/inspector node index.js

📝 License

MIT

🤝 Support

• Documentation: https://bitflik.com/docs
• API Reference: https://bitflik.com/api-playground
• Issues: https://github.com/bitflik/bitflik/issues

🎉 Summary

BitFlik MCP Server provides safe, resource-limited access to BitFlik's frictionless onboarding flow, enabling AI assistants to help users get started without compromising security or business model.

Key Points:

• 🔒 Only onboarding APIs exposed
• 📊 Resource limits enforced by backend
• ✅ Safe for LLM integration
• 🚀 Users get permanent API key after onboarding
• 💰 Proper conversion funnel maintained