All pages
MCP server
craving runs a remote Model Context Protocol server at /mcp on this site. An AI agent connected to it acts on behalf of one signed-in person: it can discover Residents, quote and buy offers, chat, and, when that person is a Resident, run their studio (Homes, Visitors, chats, Library, offers, craving AI, payouts and apps). Every tool sees only what that person is allowed to see.
Connect
Connect craving to your AI has setup steps for Claude, ChatGPT, Cursor, Codex and VS Code, plus a starter prompt.
- Endpoint:
POST /mcpusing Streamable HTTP, one JSON-RPC message per request (no batch arrays, no server-sent stream). - Discovery:
/.well-known/ai-catalog.json, the server card at/mcp/server-card, and/llms.txt. - First steps: read the
craving://guideresource (or callonboard_mcp, which returns the same guide), then callwhoami. Readcraving://placesfor the list of relative studio page paths (studio_link).
Without a bearer token, the public discovery tools are available (30 calls per minute per IP address): explore_trending, explore_search, resident_profile, resident_offers, resident_booking_slots, offer_quote and onboard_mcp.
Sign in
Authentication uses OAuth 2.1. Calling a signed-in tool without a token returns 401 with a WWW-Authenticate header pointing to /.well-known/oauth-protected-resource/mcp, which names the authorization server. Anonymous tool lists also include whoami for that purpose: call it to start sign-in. After the person signs in and approves your client, your bearer token acts as them and tools/list returns every tool their role and Resident plan include. If they call become_resident, call tools/list again to load the studio tools (listChanged is false).
Registering an agent for revenue share
In craving Apps under Agents, approved developers can register up to 20 OAuth clients (confidential clients with a one-time secret, or public PKCE clients). When a Visitor buys a Resident’s offer through offer_purchase using a registered agent’s OAuth client, the purchase is attributed to your agent: you earn 10% of the sale out of the Resident’s AI fee, transferred to your connected Stripe account.
Approvals
Tools marked as needing confirmation (purchases, deletes, messages sent in the person’s name, and edits Visitors see right away) do not execute on the first call:
- The first call returns
confirmation_requiredwithconfirmation_id,summary,approve_urlandexpires_at(valid for 30 minutes). Clients that declare URL elicitation receive anelicitation/createrequest carrying the sameapprove_url. - Send the person to
approve_url(/app/approvals/<id>) to review and approve on craving. An agent can never approve on their behalf. - Once approved, call the same tool again with the exact same arguments plus
confirmation_id(orrequestStateon 2026-07-28 URL elicitation). - If they decline, the retry returns
declined. Do not retry unless they ask again; calling withoutconfirmation_idopens a fresh request markedpreviously_declined.
On the approval page, a person can also grant standing trust to your client for changes or purchases up to a cap they choose; trusted calls run immediately (auto_approved).
Purchases (offer_purchase) require your own idempotency_key so retries never double-charge. On the 18+ site, offer_purchase returns age_verification_required with a verify_url if the buyer has not verified their age yet, and action_required with a continue_url if their bank requires a security check (poll purchase_status afterwards). Card numbers never pass through MCP; new cards are added on the web via my_payment_method_add_link.
Limits
| Caller | Limit |
|---|---|
| Signed-in session, read tools | 60 / minute |
| Signed-in session, write and confirm tools | 10 / minute |
| Anonymous discovery calls, per IP address | 30 / minute |
Each tool call times out after 15 seconds (timeout); because a timed-out write may still finish in the background, read the state before retrying. Paged list tools return at most 50 rows per page.
Errors
Failed tool calls return isError: true with { error, message }:
error | What to do |
|---|---|
unknown_tool | Check the tool name against tools/list |
unauthorized | Sign the person in with OAuth 2.1 |
invalid_arguments | Fix the arguments listed in issues |
rate_limited | Wait retry_after_seconds before calling again |
timeout | Outcome is unknown; read current state before retrying a write |
not_available | Studio tool called for a non-Resident; call become_resident first |
plan_required | Their Resident plan does not include feature |
scope_denied, forbidden | This token is not allowed to perform the action |
not_found, invalid_value | The referenced ID or value is invalid; re-read state |
confirmation_unavailable | Could not open the approval request; check arguments and retry |
declined | They declined the confirmation; stop unless they ask again |
failed, unavailable | Server-side failure; read state, then retry once |