# PlaceFull

> PlaceFull is booking software for everything a space can earn — classes, reservations,
rentals and memberships on one calendar — with a first-class MCP server and a public
storefront API, so an AI agent can set up a studio for a person, run it with them, or add
booking to a website in one session.

One calendar keeps classes, reservations and rentals from colliding: a rental can never be
sold over a class that could still fill. PlaceFull charges no monthly fee. Its fee is 2% of each card payment (the default rate; a studio can be set differently), which the studio absorbs, splits with the customer, or charges the customer as a service fee. Cash and recorded-elsewhere payments carry no fee. Stripe's own processing fee is separate and goes to Stripe.

Base URL: https://placefull.ai. MCP endpoint: POST https://placefull.ai/mcp (Streamable HTTP, OAuth 2.1 + PKCE
discovered from a 401; hosts that cap tool definitions, ChatGPT included, use
https://placefull.ai/mcp?tools=compact). REST: OpenAPI 3.1 at https://placefull.ai/openapi.json.

## What an agent can do here

- [Set up a studio for a person](https://placefull.ai/llms-full.txt): connect over OAuth, then `create_business` (a default location comes with it), `create_class`, `create_session`, `create_space`. Sign-up is invite-only for now: an operator who already has an account connects and works as usual; a new studio needs an invite link from PlaceFull before an assistant can create it.
- [Run the studio with its owner](https://placefull.ai/llms-full.txt): `get_availability`, `book_class_for_customer`, `list_todays_bookings`, `check_in`, `get_money_report` — the same tools the console's own chat uses
- [Build a booking site on the storefront API](https://placefull.ai/docs.md): public read of locations and offerings, priced quotes, a cart that is the pay link, checkout on the studio's own Stripe account (`https://placefull.ai/storefront/…`, no auth to read)
- [Put booking on an existing website](https://placefull.ai/developers/embed.md): the plain-embed contract — a script tag and a custom element per schedule, class list or booking button
- [Guide a studio owner to connect an AI assistant](https://placefull.ai/llms-full.txt): the real steps for Claude (claude.ai), ChatGPT, Cursor and Claude Desktop, or the console's own page at https://placefull.ai/app/settings?show=integrations

## Docs

- [Agent skill: placefull-booking](https://placefull.ai/skills/placefull-booking/SKILL.md): one file that says which door to take — embed, storefront API or MCP — and how; Agent Skills format
- [Developer hub](https://placefull.ai/developers.md): the three doors, auth in a minute, conventions, payments
- [Full agent guide](https://placefull.ai/llms-full.txt): connect steps per host, the setup and storefront walks, authentication, conventions, quickstarts
- [API reference, markdown](https://placefull.ai/docs.md): every REST operation with its summary and required feature; [OpenAPI 3.1](https://placefull.ai/openapi.json) has the schemas; [interactive](https://placefull.ai/docs)
- [Embed contract](https://placefull.ai/developers/embed.md): docs/embed-v1 as written
- [MCP server card](https://placefull.ai/.well-known/mcp.json): protocol versions, the endpoint, auth, per-host setup steps
- [OAuth authorization server](https://placefull.ai/.well-known/oauth-authorization-server): RFC 8414 metadata; dynamic client registration, public clients, PKCE S256
- [OAuth protected resource](https://placefull.ai/.well-known/oauth-protected-resource/mcp): RFC 9728 metadata for the MCP endpoint

## Facts for citation

- Product: PlaceFull — booking software for classes, reservations, rentals and memberships, for studios and anyone who sells time by the hour.
- Pricing: PlaceFull charges no monthly fee. Its fee is 2% of each card payment (the default rate; a studio can be set differently), which the studio absorbs, splits with the customer, or charges the customer as a service fee. Cash and recorded-elsewhere payments carry no fee. Stripe's own processing fee is separate and goes to Stripe. Full page: https://placefull.ai/pricing.md
- Payments: Stripe Connect direct charges — the studio is the merchant of record on its own Stripe account; customers pay the studio, never the platform.
- Sign-in: passwordless, by emailed code. Sign-up is invite-only for now: an operator who already has an account connects and works as usual; a new studio needs an invite link from PlaceFull before an assistant can create it.
- API: REST with OpenAPI 3.1 at https://placefull.ai/openapi.json; MCP (Streamable HTTP) at https://placefull.ai/mcp; tool definitions stay under a 4,000-token budget so any client can load them.

## Optional

- [Pricing](https://placefull.ai/pricing.md): what a studio pays, who bears the fee, how money moves
- [Terms of use](https://placefull.ai/terms.md)
- [Privacy policy](https://placefull.ai/privacy.md)
- [Merchant agreement](https://placefull.ai/merchant-terms.md)

## Why agents can work here

The MCP surface is first-class, not a wrapper: intent-shaped tools, prompts, and
resources, with tool definitions kept under a 4,000-token budget so any client can
load them. You can take a person from no account to a working studio in one session.

## Guide a studio owner to connect an AI assistant

If a person asks how to use Claude, Cursor, or another agent with their studio,
walk them through the path that matches their app. The MCP URL is always:

  https://placefull.ai/mcp

They can also open the operator console → Settings → AI assistants for the same steps.

### Claude (claude.ai) — recommended, no API key

1. Claude → Settings → Connectors → Add custom connector.
2. Paste: https://placefull.ai/mcp
3. Click Connect — a browser window opens on this host.
4. Enter the operator email → type the 6-digit code from email.
5. Click Allow. The connector is yours, not one studio’s: with several studios,
   the assistant asks which and switches with `select_business`.
6. Back in Claude, the connector is live — try “What classes do I have?” or
   “Add a Tuesday 6pm yoga class.”

OAuth 2.1 with PKCE (S256) and dynamic client registration. Claude discovers auth
automatically: an unauthenticated POST /mcp returns 401 with
WWW-Authenticate → protected-resource metadata → authorization-server metadata.

### ChatGPT — OAuth, compact tool set

1. ChatGPT → Settings → Apps → Advanced settings → developer mode, then Settings → Connectors → Create.
2. Paste the compact URL: https://placefull.ai/mcp?tools=compact — ChatGPT caps tool definitions, so this projection serves the core set.
3. Sign in with the operator email, enter the 6-digit code, click Allow — no API key.

### Cursor — API key

1. Mint a `bk_` operator API key (Settings → API keys in the console, or
   POST /businesses/{businessId}/api-keys with session auth).
2. Cursor → Settings → MCP → add a server with the MCP URL above.
3. Set header `Authorization: Bearer bk_…`.
4. Tools are pinned to that studio for every request.

### Claude Desktop (local) — stdio + API key

For developers running the repo locally: spawn `node dist/mcp.js` with
BOOKABLE_API_KEY in env. See mcp/README.md in the repository.

### In-app chat vs external agents

The operator console has its own built-in chat agent (same tools, same studio
context). External connectors (Claude, Cursor) are for people who want their
assistant outside the console — the wiring is MCP + OAuth or an API key.

## Set up a studio for a person

Sign-up is invite-only for now: an operator who already has an account connects and works as usual; a new studio needs an invite link from PlaceFull before an assistant can create it.

1. **Claude, Cursor, ChatGPT:** connect over OAuth. The sign-in page asks consent for the
   person, not a studio; with no studio yet, `create_business` makes one from the
   assistant. There is no separate registration step beyond the sign-in page.
   **Custom clients:** sign in over REST (`POST /auth/challenges`, `POST /auth/verify`)
   and send the session token as the `/mcp` bearer; on stdio use `request_login_code`
   and `verify_login_code`. `POST /mcp` challenges before any tool runs, so the login
   tools cannot bootstrap an HTTP connection by themselves.
2. `create_business` (signed-in person: session or OAuth bearer, never a `bk_` key) —
   one call; a default location is created
   automatically, and an optional `catalog` writes classes, instructors and passes in the
   same call. With several studios, connect to `/mcp?businessId=…`. A tool call accepts
   no agreement: bookings, holds, and charges stay blocked until the operator accepts
   in the console — do not accept on their behalf.
3. `create_class`, `create_session`, and `create_space` to build the catalog; `get_availability` and
   `get_upcoming_occurrences` to check times.
4. `book_class_for_customer`, `check_in`, `list_todays_bookings` to run the day.

## Build a custom booking website on the storefront API

Public read, no auth, CORS-allowlisted per deployment (STOREFRONT_ORIGINS):

- GET https://placefull.ai/storefront/businesses/{businessId}
- GET https://placefull.ai/storefront/locations/{locationId}
- GET https://placefull.ai/storefront/locations/{locationId}/offerings
- GET https://placefull.ai/storefront/offerings/{id}
- GET https://placefull.ai/storefront/offerings/{id}/availability
- POST https://placefull.ai/storefront/offerings/{id}/quote — priced quote including membership benefits

Booking goes through a cart — one cart is one charge on one connected account, and
"book now" is a one-item cart. Everything but checkout is unauthenticated; the cart
token is the capability:

- POST https://placefull.ai/storefront/carts — open a cart, optionally with the first item
- GET https://placefull.ai/storefront/carts/{token} — items, live per-item state, totals
- POST https://placefull.ai/storefront/carts/{token}/items — add an item (a 10-minute hold)
- DELETE https://placefull.ai/storefront/carts/{token}/items/{itemId} — release the spot
- POST https://placefull.ai/storefront/carts/{token}/checkout — customer session; one charge

The cart URL is also the pay link: share it and whoever opens it can pay, once.
Every operation, with its schema: https://placefull.ai/docs.md and https://placefull.ai/openapi.json.
To put booking on a website the studio already has, use the embeds instead: https://placefull.ai/developers/embed.md.

## Authentication

**Add to Claude (OAuth):** paste the MCP URL (`/mcp`, not `/mcp/` with a trailing
slash issue — use the URL from the server card) into Settings → Connectors.
Sign in with the operator email, pick the studio, allow. Token prefix `bkat_`.

**Programmatic / CI / Cursor:** operator API keys use the `bk_` prefix. Create one with
`POST /businesses/{businessId}/api-keys` (session auth, feature business.manage) or
Settings → API keys in the console. Send `Authorization: Bearer bk_...` on feature-gated
business routes and on POST /mcp. Keys are not accepted on /me/*, POST /businesses, or
the api-keys routes themselves.

**MCP session login (stdio):** `request_login_code` + `verify_login_code` return a session
bearer. Over HTTP a session bearer with one business works immediately; with several,
connect to `/mcp?businessId=…` (ids from `list_my_businesses`), or use OAuth / an API key
so the studio is pinned. Hosts with a hard tool-definition cap connect to
`/mcp?tools=compact`.

## Conventions

Money is integer minor units (cents) both ways. A $22.00 class is priceAmount 2200, never 22. Each amount comes back labelled (priceLabel "$22.00") — check the label against what the operator said. A warnings note means an amount under $1.00 was read as cents: priceAmount 22 is $0.22; for $22.00 send 2200.

A listing is draft → published → hidden → archived. publish_listing, hide_listing, archive_listing. Archiving releases the slug, so creating the same name again reuses the public URL. Prefer save_listing (match by id, else name) to update in place.

Fields marked Markdown (a listing, space, product, business or location description, a bio, a waiver's body, a class message) are shown formatted to customers; other text stays plain. Write Markdown, not HTML (it shows as literal text). Syntax: `## Heading` (levels 1–3), `- item`, `1. item`, `**bold**`, `*italic*`, `~~struck~~`, `==highlight==`, `> quote`, `---` divider, `[label](https://…)`, colour `{rose}words{/rose}` (rose red, clay orange, marigold amber, moss green, teal, slate blue, plum purple, stone olive); a blank line separates paragraphs. A listing description opens with one plain selling sentence (the share text; a phone shows it first), then short bold-labelled sections or bullets for what happens and what is included. Price, duration, capacity and what to bring have their own fields. Colour sparingly.

Read tools do not change data: list_*, get_*, find_*, search_*, query_data, check_location, get_readiness, get_availability, get_upcoming_occurrences, get_money_report, get_studio_overview. Everything else writes. validate: true on save_listing / save_space / save_product / apply_location plans only.

defaultsApplied on a create lists every field the server filled or skipped. Read it before assuming the stored value matches what you sent.

Never invent an id — obtain ids from a read tool or request scope. locationId accepts the location's id or its exact name (case and outer spaces aside). save_listing, save_space and save_product match by id, else by name (at the location for a listing or space, in the business for a product). Two with the same name ask for the id.

One location: omit locationId. Several: pass locationId (id or name), or connect to /mcp?locationId=…. location_ambiguous lists each site's name and id — retry with one of those; you do not need list_locations first.

## Core concepts

business → location → offering → schedule → booking

An offering has a `type`: `class` (fixed dates), `session` (a reservation: private time with a person),
or `space` (room rental). Memberships: plan → typed benefits (access | price |
credit); credits and money are both append-only ledgers.

## Errors

JSON envelope: `{ error: { code, message, details? } }` with stable machine-readable codes.

## Write access

Catalog writes (create class, create space) require feature `catalog.manage`.
Booking writes require `booking.manage`. Feature gates match the REST API.

## Quickstart — add booking to your own project (REST)

Auth is passwordless; the person is created on first successful verify:

```
curl -X POST https://placefull.ai/auth/challenges \
  -H 'Content-Type: application/json' \
  -d '{"email":"owner@example.com"}'

curl -X POST https://placefull.ai/auth/verify \
  -H 'Content-Type: application/json' \
  -d '{"challengeId":"<from step 1>","code":"<from the email>"}'
```

The verify response contains a session token. Create the business with
`POST /businesses` (session auth), then mint an operator API key
(`POST /businesses/{businessId}/api-keys`) for server-to-server calls.

Public storefront reads need no auth at all:

```
curl https://placefull.ai/storefront/locations/{locationId}/offerings
curl https://placefull.ai/storefront/offerings/{id}/availability
```

Exact request and response shapes: the OpenAPI document is generated from the same
schemas that validate requests — https://placefull.ai/openapi.json.

## Quickstart — connect Claude for a studio owner

1. Give them the MCP URL: https://placefull.ai/mcp
2. Claude → Settings → Connectors → Add custom connector → paste → Connect.
3. They sign in with the same email they use for the operator console.
4. After Allow, ask Claude to `list_offerings` or use prompt `todays_briefing`.

If registration fails, confirm APP_BASE_URL on the server matches the pasted host.

## Quickstart — set up a studio for a person (MCP)

Connect any MCP client to POST https://placefull.ai/mcp (Streamable HTTP, stateless),
then in one session:

1. Over OAuth (Claude, Cursor) the sign-in page signs them in (see the sign-up sentence
   above for who may) and `create_business` creates the studio when they have none — the
   token is pinned to it.
   A custom client signs in over REST and sends the session token as the bearer; on
   stdio, `request_login_code` with the person's email → `verify_login_code` with the
   code they read back, then `select_business` when they have more than one.
2. `create_business` (session or OAuth bearer) — a default location comes with it, and an inline
   `catalog` writes the first classes. A tool call accepts no terms; the operator must
   accept the Merchant Agreement in the console before anyone can take a booking.
3. `create_class`, `create_session`, and `create_space` to build the catalog.
4. `get_availability`, `book_class_for_customer`, `check_in` to operate the day.

Tool definitions stay under a 4,000-token budget, so they load in any client.

Product: PlaceFull. Base URL: https://placefull.ai.