5-Minute Setup

MCP Quick Start Guide

Get started with BuildStability's MCP server in 5 minutes

Prerequisites

A BuildStability account (sign up)
A Supabase JWT access token (obtained after login)
A tool that supports JSON-RPC 2.0 (Claude Desktop, ChatGPT, Gemini, custom scripts, etc.)

Step 1: Get Your Access Token

Easiest: Copy Token

When API access is enabled, go to Business → Business Settings → API & Integrations and click Copy Token. The JWT is copied to your clipboard. Use it as Authorization: Bearer <token>.

Alternatively, via browser DevTools:

Sign up or log in to BuildStability
Open DevTools (F12) → Application → Local Storage
Find sb-<project-id>-auth-token
Copy the access_token value

Or use the Supabase client in your code:

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  'https://your-project.supabase.co',
  'your-anon-key'
);

const { data: { session } } = await supabase.auth.getSession();
const accessToken = session?.access_token;

Step 2: Test the Connection

Use curl or your preferred HTTP client:

curl -X POST https://api.buildstability.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Expected response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "buildstability/get_client_summary",
        "description": "Get a summary of a specific client...",
        "inputSchema": { ... }
      }
    ]
  }
}

Step 3: Make Your First Tool Call

Check for clients at risk of churning:

curl -X POST https://api.buildstability.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "buildstability/check_churn_risk",
    "params": {
      "threshold": 40
    }
  }'

Step 4: Integrate with Claude Desktop

Open Claude Desktop settings
Navigate to "Developer" or "MCP Servers"
Add a new server:

{
  "mcpServers": {
    "buildstability": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-fetch",
        "https://api.buildstability.com/api/mcp"
      ],
      "env": {
        "BUILDSTABILITY_TOKEN": "YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Example Prompts

Once connected to Claude, ChatGPT, or another AI assistant, try these real-world prompts:

"Show me clients who haven't trained in 2 weeks"

Uses check_churn_risk + list_clients

"What's my revenue this month vs last month?"

Uses get_revenue_summary

"Send a check-in message to clients at risk of canceling"

Uses check_churn_risk + send_client_message

"What are my busiest class times this week?"

Uses get_popular_times + get_attendance_stats

"Give me a progress summary for Sarah Johnson"

Uses get_client_summary + get_client_workout_history

"What's my schedule for tomorrow?"

Uses get_schedule

What Can I Build?

The MCP API opens up powerful integration possibilities. Here are 5 ideas to get you started:

1. AI Coaching Assistant

Build a chatbot for your clients to ask about their program, log workouts via conversation, and get personalized motivation. Deploy on your website or in a mobile app.

2. Automated Retention Alerts

A cron job that checks check_churn_risk daily and automatically sends personalized re-engagement messages or Slack/email alerts to you.

3. Smart Scheduling Bot

Help clients find and book available slots via natural language. "Find me a morning PT slot next week" → uses get_available_slots and shows options.

4. Custom Revenue Dashboard

Pull real-time revenue and attendance stats into your own dashboard or BI tool. Great for multi-location studios wanting a unified view.

5. Voice Assistant Integration

"Hey Siri, what's my schedule today?" — Connect MCP to Shortcuts, Alexa Skills, or Google Actions for hands-free business queries.

Common Patterns

Get Client Summary

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "buildstability/get_client_summary",
  "params": {
    "client_id": "uuid-here"
  }
}

List Active Programs

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "buildstability/list_active_programs",
  "params": {
    "limit": 20
  }
}

Get Business Stats

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "buildstability/get_business_stats",
  "params": {}
}

Error Handling

All errors follow JSON-RPC 2.0 standard:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "client_id is required"
  }
}

Common error codes:

-32600: Invalid Request
-32601: Method not found
-32602: Invalid params
-32001: Business context required (not authenticated)
-32603: Internal error

View Raw Markdown Developer Portal