Assistant MCP endpoint

POST https://www.bookwithhaven.com/api/public/mcp/assistant

The Haven host assistant's own tools, over the Model Context Protocol. This is the set the assistant in the Haven dashboard offers a signed-in host — listings, calendars, rates, reservations, guests and messaging, websites and group sites, integrations, reports, the assistant's memory and scheduled tasks — resolved for the account your connection acts inside.

It is a second MCP server, deliberately separate from the MCP endpoint at /api/public/mcp. That server mirrors the public API: its tools are the REST operations, with reference codes and integer minor units. This one speaks the assistant's dialect: numeric row ids, amounts as the host says them, and a proposal card before every write. One server publishing both would show a client two schemas for the same idea, so there are two servers and two URLs.

Connecting

Point your client at the URL. Authorization is discovered from it.

An unauthenticated request answers 401 with:

WWW-Authenticate: Bearer realm="Haven", resource_metadata="https://www.bookwithhaven.com/.well-known/oauth-protected-resource/api/public/mcp/assistant"

From there the flow is the one every Haven endpoint uses: the protected-resource document names the authorization server, the client registers itself and runs the authorization code flow with PKCE, and a Haven host signs in and approves what the connection may read and change. The same hvat_ access token works on this endpoint, the first MCP endpoint and the REST API; this endpoint is its own protected resource, and RFC 8707 resource indicators naming it are accepted on the authorization and token requests.

Send the token as Authorization: Bearer … on every POST.

What the server supports

initialize, ping, tools/list and tools/call. Stateless, one JSON-RPC message per POST, notifications answered 202, batches refused, GET and DELETE answered 405 with Allow: POST, OPTIONS. Protocol revisions 2025-06-18, 2025-03-26 and 2024-11-05 are negotiated; MCP-Protocol-Version is echoed on every response; OPTIONS preflight and CORS are enabled. The transport is identical to the first MCP endpoint's.

The tool list

tools/list returns the assistant's tools for your connection's account, after four filters:

  • the tool is one the assistant exposes to MCP (its descriptor says so; conversation helpers such as think are never listed);
  • the host's Partner Program link, if they have one, allows it — the same rule the dashboard applies;
  • your grant holds the tool's scopes (below);
  • a connection held by a directory-listed client (Claude, Grok, Cursor) never lists a tool that moves money: approve_booking, adjust_booking_price, cancel_reservation, issue_booking_refund.

A tool that does not appear is one tools/call will answer with "no tool named …". Call tools/list again after any authorization change.

Scopes

The assistant's tools are declared by category, not by scope, so each category is placed under the public-API scopes whose consent line covers it. Reads need the read scope; writes need the write scope.

Tool categoryReadWrite
Calendarcalendar:readcalendar:write
Listing, listing copy, photos, upsells, guidebook writeslistings:readlistings:write
Group sites, domains, site templates, recoverysites:readsites:write
Reservationsreservations:readreservations:write
Retargetingguests:readmessaging:send
Guest chatsmessaging:read—
Guidebook readsguidebook:read
Integrationsintegrations:readnot offered
Account, profile, notifications, billing, memory, scheduled tasksaccount:readnot offered
Discovery and helpaccount:read—

Two refinements make the table tighter than it reads:

  • A tool that shares its name with a public-API operation takes that operation's scopes. block_dates needs calendar:write; create_price_override needs rates:write; cancel_reservation needs reservations:cancel; issue_booking_refund needs reservations:refund. The write is the same one the REST surface publishes, so the consent is the same too.
  • Generic entity tools take their entity's scopes. entity_property_* is listings, entity_property_group_* is sites, entity_promotion_* and entity_price_override_* are rates, entity_discount_code_* is discounts, the two min-stay entities are stay rules, entity_image_* and entity_property_tax_rule_* are listings.

"Not offered" means no grantable scope describes the write, so it is not on the list. Account-level writes (account settings, memory, scheduled tasks), integration changes, notification and billing writes stay in the Haven dashboard.

Arguments

Listings are addressed by their numeric id, as the assistant addresses them. Start with list_my_properties. Every listing-scoped tool requires propertyId; there is no open screen to default to.

Amounts are in the listing's own currency, as a number of that currency's units — 125.5 for $125.50 — the way the host says them to the assistant. This is the one place the two MCP endpoints disagree on purpose: the public API uses integer minor units. Every money field says so in its description.

Schemas are the assistant's own, projected as JSON Schema; an argument the schema does not name is a refusal that names it.

Reads

A read tool runs the assistant's own runtime for that tool and returns its result as a JSON text block and as structuredContent. Reads are charged the read budget.

Writes are two calls

Every tool that changes something proposes before it commits, exactly as the assistant in the dashboard shows a card before the host clicks Accept.

The first call proposes. Nothing is written. The result has isError: false and carries:

{
  "status": "proposed",
  "summary": { "title": "Block 2 nights on Cocoa Tea Villa", "lines": ["…"] },
  "proposedChange": { "type": "block_dates", "propertyId": 7594, "…": "…" },
  "confirmationToken": "…",
  "expiresInSeconds": 300,
  "nextStep": "Show this change to a person. To commit it, call \"block_dates\" again with the same arguments plus confirmationToken."
}

The token is also at _meta["haven/confirmationToken"]. Show the card to a person.

The second call commits. Same tool, same arguments, plus the token — as confirmationToken in the arguments or at params._meta["haven/confirmationToken"]. The token is an HMAC over your client, the grant, the tool, the arguments and the idempotency key, valid for five minutes and only for that exact call, so a proposal for one change cannot be committed as another. The commit runs through the same code path the dashboard's Accept runs — the change is re-authorized against the host and re-validated, and a connected property management system's locks are re-checked — and answers:

{
  "status": "committed",
  "summary": { "title": "…", "lines": ["…"] },
  "proposedChange": { "…": "…" },
  "commitResult": { "…": "…" },
  "changed": [{ "entity": "Property", "ids": [7594] }],
  "undo": { "kind": "undo", "change": { "type": "unblock_dates", "…": "…" } }
}

A proposal the assistant refuses to make (a PMS-owned domain, an invalid field) comes back as a result with isError: true and the structured refusal, on either call. A commit the host's account refuses (the listing is no longer theirs, the change is no longer legal) does the same with status: "refused".

Undo

_meta["haven/undo"] on every commit says how to put it back: { kind: "undo", change } is an ordinary proposal envelope — call the tool named by change.type with its fields as the arguments and it proposes and commits like any change — and { kind: "irreversible", reason } is the host-readable reason there is no undo. list_recent_changes and undo_change are on the tool list as well.

Idempotency

The commit claims an idempotency key. Supply one as idempotencyKey in the arguments or at params._meta["haven/idempotencyKey"]; supply none and one is derived from the tool, your grant and the arguments. Either way the token is bound to it, so two calls with identical arguments share one key: a second commit replays the first's answer (replayed: true) rather than writing twice. Pass an explicit key when you genuinely mean a second, separate change — and reuse it on the second call of the pair, because a new key invalidates the token.

Errors

The same two kinds as the first MCP endpoint. A refusal is a successful tools/call whose result carries isError: true, with the message in content and the detail in structuredContent — written to be acted on, so a model has to see it. JSON-RPC errors are reserved for messages never processed: a malformed envelope, an unknown method, a tool not on your list, an envelope value that cannot travel.

Rate limits and audit

tools/list and every read are charged the read budget; every proposal and commit is charged the write budget. The limiter fails closed. Every call is written to the same request log as the REST API, with the transport marked mcp and this path as the route. See Rate limits.