> 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. Permission checks and validation apply unchanged — if a change would be rejected in the panel, it is rejected for the AI too.
* 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 an operator who is allowed to connect an AI client to this workspace. Being an [operator](file:///the-basics/workspace/operators.md) 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 operator 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. |
| **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**. |
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 same permissions. 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 operators 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.
Can I limit what the AI is allowed to change?
Not per connector. A connected client can use every tool listed above, and each call is checked against the same rules as the admin panel. If you want a read-only setup, ask the AI itself to only use `_list` and `_get` tools, and review what it proposes before letting it write.
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.
***
## 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.
