# AutoSync MCP — Quick-Start Guide **For:** Customers connecting Claude Desktop, ChatGPT, Cursor, or any AI agent that speaks the Model Context Protocol (MCP) to their AutoSync account. **You'll learn how to:** - Mint an AutoSync API key - Add AutoSync as an MCP server in Claude Desktop, ChatGPT, or Cursor - Use the 10 built-in tools (booking, availability, services, classes, staff, rooms) - Diagnose common errors **Time to first booking:** ~10 minutes. --- ## What is MCP — and what does AutoSync's MCP do? The **Model Context Protocol** (MCP) is an open standard from Anthropic that lets AI assistants connect to external tools and data with a single config block. Once you connect AutoSync to your AI client, the assistant can: - **Look up bookable services**, classes, staff, and rooms - **Check live availability** for any service or staff member - **Create, reschedule, and cancel bookings** on Mindbody, Booker, or HighLevel - **Resolve contacts** by email, phone, or contact ID You point your AI client at one URL with one bearer token, and it talks to whichever booking platform your AutoSync account is connected to. No platform-specific glue code — AutoSync handles the routing, calendar mapping, contact lookup, and dual-write. The same key also works against the **REST API** at `https://autosync.io/api/v1/*` if you'd rather build a custom integration. See [`/api/v1/docs`](https://autosync.io/api/v1/docs) for the OpenAPI explorer. --- ## Prerequisites Before you start: 1. **An active AutoSync subscription** with API access enabled. You'll see "API & AI Access" in the AutoSync menu inside HighLevel; opening that page should show your key list (not the upsell card). If you see the upsell card, click **Enable API Access** and complete the $49/mo Stripe checkout — or contact `support@autosync.io` if you've been promised a comp account. 2. **Your AutoSync platform connected.** If you installed *AutoSync for Mindbody*, Mindbody must be authorized; same for Booker. *AutoSync API* installs (HighLevel-only) work too — bookings happen on your HighLevel calendars. 3. **An AI client that speaks MCP.** Today: Claude Desktop, Cursor, ChatGPT (via OpenAI Connectors), Anthropic SDK apps, or any HTTP MCP client. (Web ChatGPT and the Claude web app don't currently support custom MCP servers — you need Desktop, Cursor, or your own client.) --- ## Step 1 — Mint an API key 1. Open AutoSync inside HighLevel (the **API & AI Access** page). 2. Click **+ New Key**. 3. Give the key a name. Use something specific — `claude-desktop-laptop`, `chatgpt-receptionist`, `staging-bot`. The name shows up in the key list and the usage chart so you can audit which key is doing what. 4. Pick scopes. The default `*` (full access) is fine for a personal AI assistant. Tighten scopes if you're handing the key to a third-party integration: - `services.read` — list services / classes / staff / rooms - `availability.read` — query availability slots - `bookings.read` — read individual bookings - `bookings.write` — create / update / cancel bookings - `contacts.read`, `contacts.write` — contact data 5. Click **Create**. **Copy the plaintext key now** — it starts with `asyk_live_…` and is shown ONCE. AutoSync stores only a hash; you cannot recover the plaintext later. 6. Treat it like a password. Anyone with this key can book on your behalf. Revoke and re-mint if it leaks. --- ## Step 2 — Configure your AI client ### Option A — Claude Desktop (Mac / Windows) 1. Open the Claude Desktop config file: - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` 2. Add the AutoSync server to the `mcpServers` block (create the block if it doesn't exist): ```json { "mcpServers": { "autosync": { "url": "https://autosync.io/mcp", "transport": "streamable-http", "headers": { "Authorization": "Bearer asyk_live_PASTE_YOUR_KEY_HERE" } } } } ``` 3. Save the file and **fully quit + relaunch Claude Desktop** (the config is read once at startup). 4. Open a new conversation. Click the tools icon (the small slider / wrench glyph next to the prompt box) — you should see `autosync` listed with 10 tools available. If Claude Desktop reports "MCP server failed to connect," see the [Troubleshooting](#troubleshooting) section. ### Option B — Cursor 1. Open **Cursor Settings → Features → Model Context Protocol**. 2. Click **+ Add new MCP server**. 3. Fill in: - **Name:** `autosync` - **Type:** `streamable-http` - **URL:** `https://autosync.io/mcp` - **Header:** `Authorization` = `Bearer asyk_live_…` 4. Save. Cursor will probe the server and list its tools in the panel. ### Option C — ChatGPT (Custom GPT with Connectors) 1. Sign in to ChatGPT (Plus / Team / Enterprise). 2. Go to **My GPTs → Create** (or open an existing GPT in editor mode). 3. Under **Configure → Capabilities → Connectors**, click **Add new connector**. 4. Fill in: - **Server type:** `Streamable HTTP` - **URL:** `https://autosync.io/mcp` - **Authentication:** Bearer token, paste `asyk_live_…` 5. Save and publish the GPT. Now any conversation with that GPT can call AutoSync tools. (ChatGPT's MCP / Connectors UI has been evolving — if your menu paths differ, look for "Custom Action," "External Tools," or "MCP" under the GPT builder. The transport URL and bearer token stay the same.) ### Option D — Programmatic (Anthropic SDK / custom HTTP) The MCP server speaks **JSON-RPC 2.0 over HTTP** at `POST https://autosync.io/mcp`. Send `Content-Type: application/json` and `Accept: application/json, text/event-stream`. Example with `curl`: ```bash curl -X POST https://autosync.io/mcp \ -H "Authorization: Bearer asyk_live_…" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }' ``` You should get back a JSON-RPC response listing the 10 tools. --- ## Step 3 — Try it Drop one of these into your AI client's chat box. The exact wording isn't important; you just need to mention what you want. **Smoke test:** > Use the AutoSync `whoami` tool and tell me what location and platform are connected. **Listing services:** > Show me the bookable services in AutoSync. Group them by program. **Checking availability:** > What slots does Sarah have open on the Reformer Pilates service next Tuesday between 10am and 4pm? **Booking:** > Book Jane Doe (jane@example.com) into Sarah's 11am Reformer Pilates next Tuesday. If she's not in our system, create a contact record. **Reading and rescheduling:** > Find the appointment ID we created and move it to 2pm the same day. **Cancelling:** > Cancel that 2pm appointment with the reason "client illness." The AI will pick the right tool, call it, and report the result. If a tool fails, it'll surface the error — usually a missing field or a scope problem (see [Troubleshooting](#troubleshooting)). --- ## Available tools Ten tools are always available (the AI doesn't have to know about all of them; it'll discover what's relevant from your prompt). | Tool | What it does | |---|---| | `whoami` | Echoes the authenticated location, platform, tier, and key info. Use to confirm everything is wired up. | | `list_services` | Returns the bookable services / sale-side service types from your platform. | | `list_classes` | Returns class descriptions. **Mindbody only** — Booker has no class concept; HighLevel calendars are exposed via `list_services`. | | `list_staff` | Returns staff members / instructors / providers. | | `list_resources` | Returns rooms / equipment / treatment beds. | | `get_availability` | Returns free slots for a service or class within a date window (≤ 31 days). For Booker / Mindbody, the slot source depends on the **`bot_booking_mode`** setting (Settings → Allow Bot/MCP Bookings). `Online Only` (default) returns only services flagged bookable online on the platform — the same set a public website widget would show. `All Available` returns slots for every service mapped to a HighLevel calendar, regardless of the platform's bookable-online flag — slots are read from HighLevel's free-slots feed (which already reflects both platforms' bookings via calendar sync). Booking creation is unchanged in either mode. See "Why am I not seeing slots for service X?" in Troubleshooting. | | `create_booking` | Books a slot. Resolves the contact across email / phone / IDs; creates one if `autoCreateContact: true` and no match found. Dual-writes to HighLevel. | | `get_booking` | Returns a normalized booking record by platform-side ID. | | `update_booking` | Reschedules — change start/end time, staff, room, or notes. | | `cancel_booking` | Cancels the booking. Mirrors the cancel to the linked HighLevel calendar event. | For full request / response shapes, see the OpenAPI spec at [`https://autosync.io/api/v1/openapi.json`](https://autosync.io/api/v1/openapi.json) or the rendered docs at [`https://autosync.io/api/v1/docs`](https://autosync.io/api/v1/docs). --- ## Common workflows ### Book a new client into a service The AI typically does this in two passes: 1. `list_services` → find the right service ID 2. `get_availability` → find an open slot 3. `create_booking` with `contact: { email, firstName, lastName }` and `autoCreateContact: true` If the contact already exists in HighLevel or your booking platform, AutoSync will match by email or phone and use the existing record. If not, it creates a new one and links the IDs. ### Reschedule a class registration (Mindbody) Class registrations have a platform-side ID just like 1:1 appointments. The AI can call `get_booking` with that ID, then `update_booking` with a new `startDateTime`. AutoSync handles the platform-specific reschedule logic and updates the HighLevel calendar event. ### Cancel and refund handling The DELETE endpoint cancels — it doesn't process refunds. Late-cancel detection is **not yet** in v1 (the `lateCancel` parameter is accepted as a forward-compat flag but doesn't currently alter platform behavior). For now, your AI agent should not promise refunds — surface the cancellation and direct the customer to your front desk for fee questions. ### Bot-driving multiple platforms from one key If your account is on the *AutoSync API* listing (HighLevel only), all booking calls go through your HighLevel calendars. If you're on *AutoSync for Mindbody* or *AutoSync for Booker*, calls route to that platform — the AI doesn't need to know which. --- ## Rate limits, idempotency, and reliability - **Rate limit:** 60 requests / minute per key. The MCP server passes this through transparently — if you hit it the AI will see a `ratelimit.exceeded` error with a retry-after value. - **Idempotency:** the underlying REST API supports `Idempotency-Key` headers, but MCP tool calls don't expose this directly today. If your AI agent retries a booking after a transient error, you may end up with a duplicate booking — design your prompts to confirm before re-trying. - **Circuit breaker:** if the underlying booking platform has 5+ server errors in 60 seconds, AutoSync opens a per-platform breaker for 5 minutes. During that window, calls return `platform.circuit_open` (503). The AI will see the error and should wait — don't let it loop on retries. - **Usage chart:** every call lands in your AutoSync usage log. Open the API Access page to see which key is being used, top endpoints, and any error codes — useful for debugging your AI agent's behavior. --- ## Troubleshooting | Symptom | Likely cause | Fix | |---|---|---| | `auth.invalid_key` / "API key invalid, revoked, or expired" | Key is wrong, was revoked, or you copied the prefix instead of the plaintext | Re-mint and re-copy the full `asyk_live_…` token. The plaintext is shown ONCE at creation. | | `auth.insufficient_scope` | Key was minted with limited scopes; the tool needs one you didn't grant | Re-mint with broader scopes (or `*`) and update your AI client config. | | `auth.api_access_disabled` | Your AutoSync subscription's API access isn't active | Open the API Access page → Subscribe (or contact support if you have a comp account that's been disabled). | | `ratelimit.exceeded` (429) | More than 60 requests in a minute on this key | Wait the `retryAfterSec` window. If you legitimately need more, contact support to raise the limit. | | `platform.mismatch` (403) | The MCP tool call targeted a platform that's not the one configured for your location (e.g. Booker on a Mindbody-only account) | Use `whoami` first to confirm which platform is connected. | | `platform.circuit_open` (503) | The underlying platform is throwing 5xx errors | Wait the indicated `retryAfterSec`. Auto-recovers. | | `validation.failed` with `issues[]` | Required field missing / wrong shape (e.g. `contact` without an identifier) | The error body lists which fields are wrong. Adjust the AI prompt to provide them. | | Claude Desktop "MCP server failed to connect" | Bad config JSON, wrong URL, or Claude Desktop wasn't fully restarted | Validate the JSON (run it through `jsonlint`). Confirm the URL is `https://autosync.io/mcp` (no trailing `/`). Quit Claude Desktop completely and relaunch. | | Tool calls return immediately with `mcp:unknown` errors | JSON-RPC envelope shape wrong (custom client) | Confirm `method` is one of `tools/list`, `tools/call`, `initialize`, etc. For tool calls, set `params.name` to the tool name and `params.arguments` to the inputs. | | `get_availability` returns 0 slots for a service that should have openings (Booker / Mindbody) | Service isn't flagged bookable online on the platform AND your `bot_booking_mode` is `Online Only` | Either flip the service's "Allow Customers To Book Online" / equivalent flag in your platform admin, or switch `bot_booking_mode` to `All Available` in AutoSync Settings. The latter pulls slots from your HighLevel calendar (which reflects merged platform + HL bookings) so any mapped service is reachable. | If none of those fit, email `support@autosync.io` with: - Your AutoSync location ID (visible on the API Access page) - The error message verbatim - A timestamp of when the call happened (so support can find it in the request log) --- ## REST API as an alternative If you'd rather call AutoSync directly from custom code (instead of through an AI agent), the **REST API** at `https://autosync.io/api/v1/*` exposes the same operations as the MCP tools. Same bearer token, same scopes, same rate limits. - **API catalog:** [`https://autosync.io/api/v1/`](https://autosync.io/api/v1/) - **OpenAPI spec:** [`https://autosync.io/api/v1/openapi.json`](https://autosync.io/api/v1/openapi.json) - **Interactive docs (Scalar UI):** [`https://autosync.io/api/v1/docs`](https://autosync.io/api/v1/docs) You can paste the OpenAPI spec URL into ChatGPT and ask it to write a client for you in any language. Or feed it to an SDK generator like Speakeasy / Stainless / openapi-typescript. --- ## Security best practices - **Never paste your API key in a chat message** to the AI — it doesn't need to see it; it's already in the headers config you set up in Step 2. - **Use a unique key per integration.** If your laptop's Claude Desktop and your office ChatGPT both use AutoSync, mint two separate keys named accordingly. That way if one leaks, you revoke just the one. - **Rotate keys when staff leave.** Revoke old keys via the API Access page → "Revoke" in the key list. - **Watch the usage chart.** Unusual spikes or 4xx clusters often mean a bot is misbehaving or a key has been compromised. --- ## Getting help - **Support:** `support@autosync.io` - **AutoSync website:** [https://autosync.io](https://autosync.io) - **Service status:** check the API Access page's usage chart for recent errors; if the chart shows a 5xx spike, AutoSync may be having an incident. Last updated: 2026-05-05.