# Simply Booking MCP: agent setup guide

This guide is for an AI agent connecting a merchant's **Booking Lite / Simply Booking** workspace, or any other FavCRM workspace whose owner or administrator wants a booking-scoped assistant, through the dedicated MCP OAuth resources. Those resources expose booking and customer-profile tools only; they are not the general FavCRM tool catalog. Use the host's supported capabilities to do the setup; ask the merchant to act only when necessary. A remote MCP URL is added to the AI application, not opened as a login page.

The connection-key section of this guide is Booking Lite specific. A workspace whose settings do not include Booking Lite's AI assistants screen uses OAuth sign-in.

## 商戶摘要

- Booking Lite 工作區可在「設定 → AI 助理」複製提示；其他 FavCRM 工作區可在「設定 → 已連接應用」複製提示。將提示貼給你信任的 AI 助理；助理可操作時應自行設定，不能操作時應清楚說明需要你做的步驟。
- 只有該工作區的有效**擁有人或管理員**可以授權；平台管理員身份本身並不足夠。你本人登入 FavCRM、選擇工作區，並在確認應用程式、回呼網址及權限後決定是否批准。批准前可在同意畫面取消「寫入預約」權限，即使使用「管理」連結，授權亦可只餘唯讀。
- 這些資源只涵蓋預約及現有客戶資料，並非完整 CRM 工具目錄。「管理」連結代表權限上限，而非必然授予全部權限。「僅供查看」權限可讀取預約相關資訊及現有客戶資料；如你保留寫入權限，助理可修改或取消預約。取消已付款預約可能觸發退款，而且伺服器不會逐項要求批准。
- 不要在對話中貼上密碼、驗證碼、金鑰、權杖或授權碼。連接後，請助理核實可用工具及可確認的權限；若結果不完整，應清楚說明。
- 撤銷連接：在商戶後台**設定 → 已連接應用**撤銷授權；Booking Lite 亦可在**設定 → AI 助理 → 進階設定 → 已登入的 AI 應用程式**查看同一批授權並撤銷連接金鑰。撤銷後下一個請求即生效。

## Connection choices

| Method | Server URL | Permission ceiling |
| --- | --- | --- |
| OAuth sign-in (default) | `https://api.favcrm.io/mcp/oauth/manage` | `bookings:read`, `contacts:read`, plus `bookings:write` as a ceiling |
| OAuth sign-in, read-only | `https://api.favcrm.io/mcp/oauth/view` | `bookings:read`, `contacts:read` |
| Connection key (Booking Lite only) | `https://api.favcrm.io/mcp` | Scope selected when the workspace key is created |

Point a client at the **manage** URL by default: it is the permission **ceiling**, not the grant. The consent screen lists the scopes the client actually requested, all selected initially, and the merchant may clear the booking-write permission before approving — so a manage connection can end up read-only. The **view** URL stays strictly read-only, for clients that must never be able to write. The OAuth URL never proves what was granted: a token may carry less than the ceiling or less than the client asked for.

The OAuth resources serve Booking Lite and any other FavCRM workspace where the signing-in user holds an active owner or administrator membership. Eligibility is re-derived from live membership, not from the URL or from any role claim in a token, and global platform-admin status alone does not authorize a workspace the user does not own or administer. The connection-key row applies only where the workspace offers Booking Lite's AI assistants settings.

The workspace plan and the member's permissions can further restrict tools. The general FavCRM `/mcp` server and its legacy API keys are separate from the dedicated OAuth resources; see the [FavCRM MCP README](https://github.com/favcrm/mcp) for general setup.

### What these resources expose

The view and manage resources serve a fixed booking-scoped catalog, not a narrower cut of the general `/mcp` catalog:

- **View** (`bookings:read`, `contacts:read`) — booking and availability reads, service, staff and resource lists, and lookup of existing customer profiles.
- **Manage ceiling** (adds `bookings:write`) — `create_booking`, `confirm_booking`, `reschedule_booking`, `complete_booking`, `mark_no_show`, `cancel_booking`. If the merchant clears the write permission at consent, no booking-write tools are available; other unchecked permissions can further restrict reads.

Booking writes are real changes with no separate approval step. `cancel_booking` can cancel a paid booking and start a refund; normal booking, actor-permission, outlet and refund checks still apply. Nothing outside bookings and existing customer profiles — money, campaigns, WhatsApp, platform operations — is reachable through these resources, even for an owner or a platform administrator. Plan modules and the member's own permissions can remove tools from this list; `tools/list` is the authority.

## Agent procedure

1. **Check the existing connection.** Inspect the host's available tools or configuration. Reuse a working connection only when the workspace and requested access are confirmed to match. Do not silently create duplicate grants or use another workspace; if identity or permissions cannot be confirmed, say so.
2. **Determine what the host can do.** Use its supported MCP configuration, UI or extension API. Preserve existing configuration. If it cannot mount tools but can run a supported MCP SDK with a secure, user-accessible OAuth callback, use a session-scoped SDK client as described below. If neither path is available, explain the smallest verified manual step; do not invent host capabilities or instructions.
3. **Connect.** Point the host at the manage URL by default so the merchant sees the full permission ceiling; use the view URL when the merchant requests a strictly read-only connection. Add the exact URL as a remote MCP server using Streamable HTTP. If the host lets you choose scopes, request the available booking and customer-profile scopes by default; omit write if the merchant requests read-only. A grant can never exceed what the client requests. Start sign-in through the host. The merchant signs in, selects the workspace, reviews the application, callback and requested scopes, and approves or denies access; they may clear any permission before approving. The consent screen lists workspaces where that user is an active owner or administrator. Never enter their credentials or approve on their behalf.
4. **Verify.** A URL in a config file is not proof of connection. Check that `tools/list` and an authorised read succeed. Report the workspace and the scopes actually granted — which may be narrower than the requested ceiling — only when a reliable response or consent record confirms them; otherwise say they are unknown. The available tools reflect the grant, plan and member permissions, but do not reveal the complete grant by themselves. Expect only booking and customer-profile tools; the absence of other FavCRM features is by design, not a failed connection.
5. **Complete the request.** Use the available tool schemas, show real results, and disclose missing tools, failed calls or incomplete lists. Never invent data or claim a connection succeeded before an authenticated read.

Never ask for, echo, print or log passwords, one-time codes, connection keys, access tokens, refresh tokens or authorization codes in chat. Do not bypass a denied permission. Confirm every booking change with the merchant before calling a write tool; this is agent guidance, **not** an approval step enforced by the server.

## Host-specific starting points

These are vendor-documented procedures, not proof that a particular account, plan or FavCRM workspace has been tested end to end. If the host UI differs, consult its current documentation rather than guessing.

### Claude

For an individual account, Claude documents **Customize → Connectors → Add custom connector**. Enter a name and the selected OAuth URL, review its authentication settings, and connect. Team and Enterprise organisations may require an owner or administrator to add the connector first. See [Claude's custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).

### Cursor

Cursor documents remote MCP in project `.cursor/mcp.json` or global `~/.cursor/mcp.json`. Merge the following entry into the existing `mcpServers` object; do not overwrite unrelated configuration:

```json
{
  "mcpServers": {
    "simply-booking": {
      "url": "https://api.favcrm.io/mcp/oauth/manage"
    }
  }
}
```

The manage URL is the setup target and permission ceiling: the merchant can clear the booking-write scope on the consent screen, so the resulting grant may be read-only. Use the view URL only when the connection must never be able to write. Start the host's sign-in flow and let the merchant approve it. Cursor documents OAuth discovery and PKCE; see its [MCP guide](https://cursor.com/docs/mcp.md) for current settings and callbacks.

### ChatGPT and other hosts

Availability and administration depend on the host and plan. Consult [OpenAI's custom MCP server guide](https://help.openai.com/en/articles/12584461-developer-mode-and-custom-apps-in-chatgpt) or the host's own documentation. Do not claim a provider is supported merely because it supports MCP in general.

### Standalone SDK for a code-capable agent

If the host cannot add MCP tools, an agent may use an available MCP SDK with Streamable HTTP and OAuth to perform the approved task in its own process. This is a session client, not a newly installed host integration.

1. Use the SDK's protected-resource discovery. An initial `401` with `WWW-Authenticate` and `resource_metadata` is expected. The view metadata is `https://api.favcrm.io/.well-known/oauth-protected-resource/mcp/oauth/view`; the manage resource has its own corresponding metadata. Use the selected resource's advertised scopes, not the authorization server's union of view and manage scopes.
2. Follow the discovered authorization server. The MCP authorization server advertises PKCE S256, client ID metadata documents and dynamic client registration. Preserve the exact resource URL in the authorization and token requests; do not assume a static client is available.
3. Use a securely bound OAuth state and PKCE verifier. Open the authorization URL for the merchant and let them sign in and approve. A loopback callback works only when the merchant's browser can reach the client process on that same loopback interface. Otherwise use a secure host-supported callback, the host connector steps above, or explain that the SDK client must run on the merchant's machine. Never ask the merchant to paste an authorization code into chat. The OAuth server currently advertises English, so some sign-in or consent text may appear in English.
4. After the callback, validate state and complete the SDK's token exchange. Keep credentials in process memory or a supported secure credential store, never in logs or chat. Initialize the client, list tools, and perform only the merchant's authorised read. Respect host restrictions and do not claim a native host connector was installed.

FavCRM advertises the MCP authorization metadata at `https://api.favcrm.io/.well-known/oauth-authorization-server/oauth/mcp`. Clients should follow discovery rather than guessing the legacy root issuer. Full completion still requires the merchant's browser approval.

## Booking Lite connection-key method (optional)

Only workspaces that show Booking Lite's AI assistants settings offer this path. When the chosen host supports a custom bearer header, the merchant can create a workspace-bound key under **Settings → AI assistants → Advanced settings → Connection key**. The key is shown once. Have the merchant enter it directly into the host's secure settings; never ask for it in chat or copy it into a repository. Use the `/mcp` URL in the table above. Keys and OAuth grants may count towards the workspace's connection quota; limits can vary by plan or override. In a workspace without that screen, use OAuth sign-in instead — or the general `/mcp` API-key setup covered in the [FavCRM MCP README](https://github.com/favcrm/mcp) if the merchant needs the full catalog.

## Show bookings for the next seven days

Depending on permissions, the advertised read tools can include `list_bookings`, `get_booking_detail`, `get_available_slots`, `list_services`, `list_staff` and `search_members`. Inspect `tools/list` and its schemas rather than assuming any tool is available.

- Determine the workspace timezone from a reliable source; ask the merchant if it is unknown. Use the current time in that timezone, not the host's local clock.
- Call `list_bookings` for the relevant date range. Its `dateFrom` and `dateTo` are inclusive calendar dates; filter the returned times to the requested seven-day window. Preserve booking statuses and do not expose customer contact details unless needed.
- The tool defaults to **20** records and returns `items` and `total`; it has no page argument. If `total` exceeds the returned count, narrow the date range or use an appropriate limit and check again. If results remain truncated, say they are partial. An empty successful result is not an authentication failure.
- Do not claim the workspace, granted scopes or a complete list unless the available evidence supports it.

## Troubleshooting and revocation

- An unauthenticated `401` challenge starts OAuth discovery; a persistent `401` after approval requires checking the host's connection or signing in again.
- `invalid_target` can mean a token was issued for a different resource; re-authorize the intended URL. Missing tools can reflect scope, plan or member permissions; do not try another endpoint to bypass them.
- If the workspace is absent from the consent screen, check that the signing-in user is an active owner or administrator of that workspace. The picker only lists workspaces the user owns or administers, and platform-admin status alone is not sufficient. Use **Sign in with another account** if the correct account is different.
- A missing non-booking tool is expected: these resources never expose the general CRM catalog, so do not probe another endpoint for it.
- If the host cannot run a remote OAuth MCP client or a safe SDK callback, report that limitation and provide a verified host-specific next step.
- Revoke an OAuth grant under **Settings → Connected apps** in the merchant portal. Booking Lite also lists the same grants, plus connection keys, under **Settings → AI assistants → Advanced settings → Signed-in AI apps**. View and manage grants are separate, and revocation takes effect on the next request.
- Approving fewer permissions for the same app and workspace invalidates its earlier access and refresh tokens. Other sessions using that grant must sign in again; unchanged or broader approvals keep existing sessions.