# 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](04-mcp.md) 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](../01-oauth/07-dynamic-client-registration.md) and runs the [authorization code flow with PKCE](../01-oauth/01-authorization-flow.md), 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 category                                                     | Read                | Write                |
| ----------------------------------------------------------------- | ------------------- | -------------------- |
| Calendar                                                          | `calendar:read`     | `calendar:write`     |
| Listing, listing copy, photos, upsells, guidebook writes          | `listings:read`     | `listings:write`     |
| Group sites, domains, site templates, recovery                    | `sites:read`        | `sites:write`        |
| Reservations                                                      | `reservations:read` | `reservations:write` |
| Retargeting                                                       | `guests:read`       | `messaging:send`     |
| Guest chats                                                       | `messaging:read`    | —                    |
| Guidebook reads                                                   | `guidebook:read`    |                      |
| Integrations                                                      | `integrations:read` | not offered          |
| Account, profile, notifications, billing, memory, scheduled tasks | `account:read`      | not offered          |
| Discovery and help                                                | `account: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:

```json
{
  "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:

```json
{
  "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](../03-conventions/07-rate-limits.md).
