# MCP Quick Start Guide

Get started with BuildStability's MCP server in 5 minutes.

## Prerequisites

- A BuildStability account (sign up at https://buildstability.com/signup)
- A Supabase JWT access token (obtained after login)
- A tool that supports JSON-RPC 2.0 (Claude Desktop, custom scripts, etc.)

## Step 1: Get Your Access Token

**Easiest:** 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:**

1. Sign up or log in to BuildStability
2. Open your browser's developer console (F12) → Application > Local Storage
3. Find the key `sb-<project-id>-auth-token`
4. Copy the `access_token` value from the JSON

Or use the Supabase client in your code:

```typescript
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:

```bash
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:

```json
{
  "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:

```bash
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

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

```json
{
  "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:

| Prompt | Tools Used |
|--------|-----------|
| "Show me clients who haven't trained in 2 weeks" | `check_churn_risk`, `list_clients` |
| "What's my revenue this month vs last month?" | `get_revenue_summary` |
| "Send a check-in message to clients at risk of canceling" | `check_churn_risk`, `send_client_message` |
| "What are my busiest class times this week?" | `get_popular_times`, `get_attendance_stats` |
| "Give me a progress summary for Sarah Johnson" | `get_client_summary`, `get_client_workout_history` |
| "What's my schedule for tomorrow?" | `get_schedule` |

## What Can I Build?

The MCP API opens up powerful integration possibilities. Here are 5 ideas:

### 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

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

### List Active Programs

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

### Get Business Stats

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

## Error Handling

All errors follow JSON-RPC 2.0 standard:

```json
{
  "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

## Next Steps

- Read the full [Agent Integration Guide](/agents.md)
- Check out [Code Examples](/code-examples.md)
- Review the [OpenAPI Specification](/buildstability-openapi.json)