> For the complete documentation index, see [llms.txt](https://support.holidayhero.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.holidayhero.com/api/mcp.md).
# MCP
The connected guest experience.
#### What is MCP?
**MCP** (Model Context Protocol) lets you connect an AI client — such as Claude Desktop, Claude on the web or Cursor — directly to your HolidayHero workspace. Once connected, the AI can read and write your listings, reservations, check-ins, conversations, tasks, amenities, guidebooks, experiences and more, exactly as an operator would from the admin panel.
A few things are true of every connection:
* It is scoped to **one workspace**. A client connected to workspace A cannot see workspace B, even if the same operator belongs to both.
* The AI works through the same rules as the admin panel. Validation applies unchanged — if a change would be rejected in the panel, it is rejected for the AI too.
* When the connected user is an **operator** of the workspace, their permissions are honoured on every tool call. A user who is **not** an operator has full access — see Who can do what.
* Every tool call is written to an audit trail, so nothing happens invisibly.
* Access can be revoked at any time, per user or per client.
Open it from `/mcp` in your admin panel. The page has three parts: **Connection**, **Users** and **Connectors**.
#### Connection
This is the on/off switch for the whole workspace.
1. Go to the **MCP** page.
2. Click **Enable**.
The card now shows your **Endpoint URL** — the address an AI client connects to. Use the copy icon next to it. The URL contains an opaque, per-workspace code rather than your workspace ID.
Below it, **OAuth discovery document** links to the `.well-known` metadata for clients that configure themselves automatically. Most operators never need it.
To switch MCP off again, click **Disable** and confirm. Every connected client stops working immediately. Enabling again later reactivates the same endpoint URL.
#### Users
An MCP **user** is someone who is allowed to connect an AI client to this workspace. Usually that is one of your operators — but being an operator is not enough on its own; they must also be listed here.
There are two ways to add users:
* **Invite by email** — enter an address and click **Send invite**. The person receives an email with a magic link. Opening it confirms the invite and marks them **Active**. The link is valid for **one hour**.
* **Import existing operators** — adds every current operator of the workspace in one go, each receiving their own invite email.
| Column | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Email** | The address the invite was sent to. |
| **Name** | The operator's name, when known. |
| **Access** | **Operator permissions** when the address belongs to an operator of this workspace — click it to open that operator and review their permissions. **Full access** when it does not (see Who can do what). |
| **Status** | Invited until the magic link is opened, Active afterwards, **Revoked** once access has been withdrawn. |
| **Last login** | When this user's AI client last connected, or **Never**. |
**Who can do what**
There are two kinds of MCP user, and the **Access** column tells you which one you are looking at:
| Access | Who | What the AI may do |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Operator permissions** | The invited address belongs to an [operator](file:///the-basics/workspace/operators.md) of this workspace. | Exactly what that operator may do in the admin panel. Every tool call is checked against their **Read** / **Write** [permissions](file:///the-basics/workspace/operators/operator-details.md) — an operator with only *Amenities → Read* cannot update a reservation or message a guest over MCP either. Workspace **owners** have unrestricted access, as in the panel. |
| **Full access** | The invited address does **not** belong to an operator of this workspace — typically HolidayHero staff helping with onboarding or support. | Every tool, with no per-resource limits. There is no operator role to mirror. |
A refused call is not an error you need to fix: the AI receives a clear `permission_denied` reply naming the missing permission, the call is logged in the [Activity](file:///the-basics/workspace/mcp/activity.md) tab, and the AI is told to report it to you rather than retry. A workspace owner can grant the permission on the operator's detail page, after which the next call succeeds.
{% hint style="warning" %}
Because a non-operator gets full access, only invite addresses you trust with the whole workspace. To give a colleague *limited* AI access, add them as an [operator](file:///the-basics/workspace/operators.md) with the right permissions first, then invite that same address here — their role is picked up automatically, even if they became an operator after the invite was sent.
{% endhint %}
From the `⋮` menu on a row you can **Resend invite** (issues a fresh one-hour link) or **Revoke access**.
{% hint style="warning" %}
Revoking a user also revokes every connector they created and every token those connectors issued. Any AI client they set up stops working straight away. Revocation is permanent — to let them back in, invite them again.
{% endhint %}
#### Connectors
A **connector** is the credential for one AI client on one device — "Claude Desktop on my laptop", "Cursor at the office". Creating one gives you a **Client ID** and a **Client secret** the AI client uses to prove who it is.
1. Enter a **New connector name** that tells you which client and device it is for.
2. Click **Create connector**.
3. A yellow banner appears with the **Client ID** and **Client secret**. Copy both now.
{% hint style="warning" %}
The client secret is shown **exactly once**. HolidayHero keeps only a fingerprint of it, so it cannot be displayed again. If you lose it, revoke the connector and create a new one.
{% endhint %}
| Column | Description |
| --------------------------- | ------------------------------------------------------------------------------ |
| **Name** | The name you gave the connector. |
| **Client ID** | Starts with `mcp_`. Click it to copy. |
| **User** | The MCP user who created it. |
| **Created** / **Last used** | When the connector was made, and when its AI client last called the workspace. |
Click **Revoke** at the end of a row to cut off that one client without touching anything else.
#### Connecting Claude
The steps below are for Claude Desktop and Claude on the web; other MCP-capable clients follow the same shape.
1. **Enable** MCP and copy the **Endpoint URL**.
2. Create a connector and copy its **Client ID** and **Client secret**.
3. In Claude, open **Settings → Connectors** and add a **custom connector** with the endpoint URL.
4. When Claude asks you to authenticate, enter the client ID and secret.
Claude now lists the HolidayHero tools and can act on your workspace in conversation. The connection stays live until you revoke the connector or user, or disable MCP.
{% hint style="info" %}
Claude is currently the only AI client whose sign-in callback is allow-listed. Other clients can connect when their callback matches Claude's; if yours does not, contact support.
{% endhint %}
#### What the AI can do
The AI works through a fixed set of **tools**. Each tool maps onto one thing you can already do in the admin panel — under the connected operator's permissions, or without limits for a user who is not an operator (see Who can do what). Tools are named `resource_action`: `_list` and `_get` read, `_create` / `_update` / `_delete` write. A write that is rejected returns the reason instead of failing silently.
Everything is identified by a HolidayHero ID of the form `gid://holidayhero/Reservation/42` — the AI reads these from a `_list` or `_get` call before writing.
| Area | Tools |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Listings** | `listing_list`, `listing_get`, `listing_create`, `listing_update`, `listing_attach_amenities`, `listing_attach_guidebooks`, `listing_attach_experiences`, `listing_attach_announcements`, `listing_attach_smart_devices`, `listing_section_update` (the **Contact** and **Directions** blocks), plus image and document tools (see below) and `listing_section_*_images`. |
| **Reservations** | `reservation_list`, `reservation_get`, `reservation_create`, `reservation_update`, plus document tools. |
| **Check-ins** | `checkin_list`, `checkin_get`, `checkin_update`, `checkin_mark_no_show`, `checkin_unmark_no_show`. |
| **Guest invitations** | `invitation_list`, `invitation_get`, `invitation_create`, `invitation_update`, `invitation_delete`. |
| **Conversations** | `conversation_list`, `conversation_get` (a thread with its recent messages), `conversation_message_send`, `conversation_update` (change the status to `FOLLOW_UP`, `PENDING` or `RESOLVED`, or hand a thread from the AI to a human). |
| **Tasks** | `task_list`, `task_get`, `task_create`, `task_update`, `task_note_create`. |
| **Amenities** | `amenity_list`, `amenity_get`, `amenity_create`, `amenity_update`, `amenity_delete`, plus image and document tools. |
| **Guidebooks** | `guidebook_list`, `guidebook_get`, `guidebook_create`, `guidebook_update`, `guidebook_delete`, plus image and document tools. |
| **Announcements** | `announcement_list`, `announcement_get`, `announcement_create`, `announcement_update`, `announcement_delete`. |
| **Calendar events** | `calendar_event_list`, `calendar_event_get`, `calendar_event_create`, `calendar_event_update`, `calendar_event_delete`, plus image and document tools. |
| **Experiences** | `experience_list`, `experience_get`, `experience_create`, `experience_update`, `experience_delete`, `experience_host_note_create`, plus image and document tools. |
| **Experience products (upsells)** | `experience_product_create`, `experience_product_update`, `experience_product_delete`, `experience_products_reorder`, `experience_product_field_create`, `experience_product_field_update`, `experience_product_field_delete`, `vat_rate_list`. |
| **Places** | `places_search`, `place_get` — look up a real business on Google Places before creating an experience for it. |
| **Brands** | `brand_list`, `brand_get`, `brand_create`, `brand_update`, `brand_delete`, `brand_art_direction_detect`. |
| **Uploads** | `upload_target_create` — a one-hour upload slot for a file that has no public URL. |
**Image and document tools** follow one pattern for every resource that has them: `_create_images`, `_update_images`, `_delete_images`, `_reorder_images`, and the same four with `_documents`. Images and documents are given as URLs; HolidayHero downloads and stores them. Uploading the same file twice is harmless — duplicates are recognised and skipped.
A few tools deserve a note:
* **`experience_host_note_create`** is the only write allowed on an experience that is backed by a Google Place. Its name, address, contact details and pricing come from the shared partner copy and cannot be edited; a host note is how you add your own information for guests.
* **`vat_rate_list`** returns the selectable EU VAT rates. The AI is told to pick from this list rather than compose a rate itself, because a wrong rate is charged to real guests.
* **`brand_art_direction_detect`** reads a brand's website and writes an art-direction brief onto the brand. It runs in the background and overwrites any existing brief.
* **`conversation_message_send`** sends a real message to a guest. Ask the AI to show you the draft first if you want to review it.
#### Frequently Asked Questions Do I need MCP to use HolidayHero's built-in AI?
No. The AI assistant in the inbox and the workspace agents run inside HolidayHero without any setup here. MCP is only for connecting an **external** AI client — one you already use, like Claude or Cursor — to your workspace.
Who should I add as a user?
Only people who will personally connect an AI client. Each user creates their own connectors and every action is traceable back to them. Do not share one connector between colleagues — create one per person and device so you can revoke exactly the right one later. Prefer inviting operators: their workspace permissions then apply to the AI as well. Anyone who is not an operator gets full access.
Can I limit what the AI is allowed to change?
Yes — through the operator's permissions. When the connected user is an operator of this workspace, every tool call is checked against their **Read** / **Write** permissions, so the AI can do no more than they can in the admin panel. Open the operator's detail page to adjust them; the change applies to their AI client immediately.
There is no per-connector setting, and a user who is **not** an operator has full access. If you need a limited setup for such a person, make them an operator first with the permissions you want, then invite that address.
I lost the client secret — can I see it again?
No. The secret is shown once, at creation, and cannot be recovered afterwards. Revoke the connector and create a new one, then update the AI client with the new credentials.
The invite link says it has expired.
Magic links are valid for one hour. Open the `⋮` menu on the user's row and click **Resend invite** to issue a fresh one.
My AI client stopped working — why?
In order of likelihood: the connector was revoked, the user was revoked (which revokes all of their connectors), or MCP was disabled for the workspace. Check the **Connectors** and **Users** tables and the **Connection** card. HolidayHero staff who were given access for onboarding or support are also revoked automatically every night, so a staff connection is expected to stop working the next day.
Does the AI see my other workspaces?
No. The endpoint URL and its connectors belong to exactly one workspace. To use the AI with another workspace, enable MCP there and add it to your AI client as a separate connector.
Is there a record of what the AI did?
Yes. Every tool call — successful or not — is logged with the tool, the user's connector, its input and how long it took. This log is not yet visible in the admin panel; contact support if \
you need to review it.
The AI says a tool was refused with permission_denied — what now?
The connected operator's workspace role does not include that permission. Check the **Access** column in the **Users** table: it links to the operator, where a workspace owner can tick the missing **Read** or **Write** permission and save. The AI can then call the tool again — there is nothing to reconnect. The refusal is also visible in the Activity tab as an errored call.
***
## Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://support.holidayhero.com/the-basics/workspace/mcp.md?ask=
```
The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
