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 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. Switch the Integration Hub on for the property — integrations overview. It is off on every new property, and a disabled app 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.
3. Do it once per property. Enablement 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.

提示

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 plus the permission behind each 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.
10. Confirm a sensitive call once by hand. A tool that changes something answers with a prompt to re-call with "confirm": true. It is a speed bump between "the model decided to" and "the hotel did", per call — not a substitute for step 5.

注意

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. Tool calls appear as ordinary rows, named by the tool, with the key prefix as the actor. 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.

注意

Step-up security 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 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 tool catalog, 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