Connect an agent to your hotel

Who this is for: Owner, and the developer an Owner account is opened for — minting a key requires integration.apikey.manage and connecting an agent requires integration.mcp.connect. Of the default roles only Owner carries either. Where: Integrations

By the end of this an AI agent can operate your hotel through a credential you scoped, seeing only the jobs and tools that credential allows, with every call written to the same log a person's actions land in.

The walkthrough is short because there is no separate agent permission model to build. An agent is not a new kind of user. It authenticates with an ordinary API key, carries the permissions you ticked, and is audited exactly as you are — which is the position Open Hotel Protocols is built on.

Understand what you are connecting to#

1. Read the contract before deciding what the agent may do — Open Hotel Protocols. Schema-first payloads, idempotent writes, and every mutation naming its actor are what make the rest of this safe to hand to a model.

Turn the surface on#

2. Install the Integration Hub for the property — installing and enabling apps for a property. It is off on every new property, and an app that is not installed does not merely hide its menu: its permissions stop resolving, for an Owner too. This is the single most common reason a developer is told "it's in Integrations" and finds no Integrations. Installing is self-service from Integrations → App Directory — do it before the sprint that needs it, since your plan may still need a look if the Hub sits behind a paywall for your organisation.
3. It is needed once per property. Installation is per property, and so is a key — a group with two hotels connects an agent twice.

Size the key before you mint it#

4. Mint a fifteen-minute scratch key and run the calls — the playground. Tick only what you are testing, then run down the endpoint list: the ones that answer 200 are what you are about to grant. Call the MCP tools by hand from the same page, including a sensitive one, so the confirmation prompt is not a surprise in an agent transcript. Submit a job from the same page too, and refresh its handle once.

Mẹo

This step is the whole reason the playground exists. Deciding a partner's scopes by reasoning about permission names, and deciding them by watching a narrow key answer 200 and 403, are not the same exercise.

Mint the key#

5. Create the real key with integration.mcp.connect, integration.job.run, plus the permission behind each job or tool the agent should reach — API keys. integration.mcp.connect is checked at the door, before the endpoint looks at anything else, so a key carrying only tool permissions never even learns which tools exist.
6. Copy the token when it is shown. It is shown once; Nerve keeps only a hash. Leaving that panel costs you a new key and a redeployment of whatever was going to use it.
7. Read the scopes back off the created key. A key can never out-scope its creator — anything you do not hold is dropped silently, so the list on the key is the truth, not the boxes you ticked.

Point the agent at it#

8. Send the key as a bearer credential to POST /api/mcp — MCP agents. Single-shot JSON-RPC; no session to hold open.
9. Call tools/list once and read what comes back. The list is filtered, not merely enforced: a tool the key cannot use is not in it, and calling it returns unknown tool rather than a permission error. The agent reasons about what it can do from that list, which is why the guidance is scope the key, not the prompt — an instruction not to touch guest data is a request, a key without frontdesk.guest.read is a fact. Jobs come first in that list — prefer them: a job is one declared intent the platform sequences for you, where a per-endpoint tool is a fragment your client has to orchestrate. The original five per-endpoint tools are deprecated and stop answering external calls on 1 March 2027; each response inside that window names the job that replaces it.
10. Confirm a sensitive call once by hand. Something that changes state answers with a prompt to re-call with "confirm": true. It is a speed bump between "the model decided to" and "the hotel did" — and on a job it sits on the whole decision ("check this guest in") rather than on each write beneath it, which is the version a person can actually agree to. Not a substitute for step 5.

Ghi chú

Every job and every tool is bound to the key's property. There is no argument for choosing a hotel and no way to reach another one, so an agent scoped to one property cannot read across a group.

Have your side told rather than polling#

11. Subscribe a receiver to the events the agent should react to — webhooks, retries and replay. Deliveries are signed, retried six times and replayable, and a replay carries the same event id — so a consumer that dedupes on id can be replayed at without double-acting. Read the warning there about booking.new covering channel bookings only.

Watch what it does#

12. Read the mcp rows in the audit log — the audit log. Calls appear as ordinary rows with the key prefix as the actor — a job as one row naming the intent, with the primitives beneath it; a per-endpoint tool as itself. There is no separate AI log to go and find, which is what makes "who did this" answerable at all.
13. Treat a run of denied rows as evidence, not noise. It is the record of the permission model refusing something — usually an agent scoped for a job somebody assumed it had.
14. Revoke first, investigate second — API keys. Revocation is immediate, there is no un-revoke, and a revoked key, a wrong token and an expired key all fail identically from outside.

Ghi chú

Escalation is the other half of this question and a different one: it challenges a person at a money action. What bounds an agent is the scope of its key and the per-call confirmation above.

You're done when…#

tools/list from the agent's key returns exactly the jobs and tools you intended and nothing else, one sensitive call has been confirmed and taken effect, and both calls are in Settings → Audit Log on the mcp channel with that key's prefix as the actor.

What's next#

• MCP agents — the job surface, the filtering and the confirmation contract
• API keys — the credential everything here hangs off
• Open Hotel Protocols — why the agent surface and the human surface are the same surface