Scopes & permissions
The hejGuide MCP server exposes 30 OAuth scopes. Each scope maps to a hejGuide plan module — the consent screen filters out scopes that the host's plan doesn't support, so tokens are minted only for what's actually usable.
Scope catalog
| Scope | Display name | What it unlocks | Plan module | Flags |
|---|---|---|---|---|
reports:read | View reports | Read revenue, occupancy and other KPIs | bookings | |
bookings:read | Read bookings | Read details of upcoming and existing bookings | bookings | |
listings:read | Read listings | Read property details and amenities | mcp_access | |
rates:read | Read rates | Read daily rates and min-stay restrictions | rates | |
messages:read | Read messages | Read inbox and threads | messages | |
messages:write_draft | Create message drafts | Create draft messages (never auto-sends) | messages | WRITE |
reviews:read | Read reviews | Read guest reviews and host replies | channels | |
reviews:write_draft | Create review drafts | Create draft review replies (never auto-publishes) | channels | WRITE |
tasks:read | Read tasks | Read operational and housekeeping tasks | tasks | |
tasks:write | Edit tasks | Add notes, update status, report issues | tasks | WRITE |
guidebook:read | Read guidebook | Read pages and welcome content of the guidebook | guidebooks | |
guidebook:write | Edit guidebook | Create and edit guidebook pages | guidebooks | WRITE |
places:read | Read places | Read tips and recommendations in the local guide | guidebooks | |
places:write | Edit places | Create and edit places in the local guide | guidebooks | WRITE |
team:read | Read team chat | Read internal messages between you and your team | messages | |
team:write_message | Send team chat | Send internal messages to team members (instant, no draft) | messages | WRITE |
guests:read | Read guest info (masked) | Read first name and last initial of guests | bookings | |
guests:read_pii | View guest PII | Read guest email and phone — limited 50/day | bookings | PII |
automations:read | Read automated messages | See which journey messages are on, their timing, content, and what's queued | emails | |
bookings:write_import | Import bookings | Import past/manual bookings into hejGuide | bookings | WRITE |
housekeeping:read | Read cleaning checklists | See cleaning checklist templates: name, type, listing and item counts | tasks | |
housekeeping:write | Manage cleaning checklists | Create and delete cleaning checklist templates with sections and items | tasks | WRITE |
locks:read | Read smart locks | See connected locks, battery/online status and door-code status (without the code itself) | smart_locks | |
locks:read_codes | Reveal door codes | Retrieve the actual door code for a booking; every reveal is audited | smart_locks | PII |
products:read | Read products | See your product/extras catalogue with prices and channel settings | products | |
products:write | Add products to bookings | Put catalogue products on a booking's bill (no payment, nothing sent to the guest) | products | WRITE |
reports:write | Mark smart insights as done | Mark AI tips as done or not relevant so they don't resurface | bookings | WRITE |
website:read | Read booking website | See your booking sites' and collections' settings and copy, including domain diagnostics | direct_booking | |
website:write | Propose website copy | Propose new booking-site copy; you review every proposal in the editor before it goes live | direct_booking | WRITE |
help:read | Search help articles | Search help.hejguide.com | mcp_access |
The PII gate
Scopes flagged PII reveal raw guest email / phone / full name on demand. Even when the host has granted the scope, every individual call to a PII-revealing tool requires:
include_pii: truein the tool arguments- A
reasonfrom a fixed enum:phone_check,email_check,invoice,address_check,investigation,other - When
reason='other', an additionalreason_detailof ≥10 characters
Every unmask is sync-audited with the reason, the client name, and the resolved guest hash. Hard cap: 50 unmasks per account per UTC day. When the budget is reached, the tool throws rate_limit and the host can either wait until midnight UTC or contact support.
locks:read_codes is a separate reveal-path with the same flag: the actual door code is never returned by the list tools — a client must pass include_code: true to get it, and every reveal is sync-audited to the lock audit log (the PIN is stored as a SHA-256 hash, never in plaintext). It does not consume from the 50/day guest-unmask budget.
Plan-module gating
A scope is only usable if the host's active plan includes its module key (or has the * wildcard). At consent time we show requested scopes the plan doesn't support under "Not available on your current plan", but we never grant them — even if the AI client asked for them.
Default state on consent
The consent screen renders scope toggles with GDPR-friendly defaults — PII-sensitive scopes start in the off position so the host has to deliberately opt in. Non-PII writes (drafts, task edits) default on since draft content never leaves hejGuide until the host clicks Send.
A note on writes to guest-facing content
guidebook:write and places:write are different from messages:write_draft / reviews:write_draft / tasks:write. Guidebook pages and places with is_published=true are immediately visible to guests on the guest portal — there's no separate "send" step. The AI can also unpublish (is_published=false) to hide a page from guests without deleting it. Hosts should grant these scopes only to clients they trust with the published-to-guests surface.
A note on team-chat writes
team:write_message also has no draft step — calling team.send_message delivers an internal message to your team members instantly, just like clicking Send in the dashboard's team-chat panel. There is no team:write_draft scope. If you want a preview step before sending, ask the AI to read the body back to you first and then explicitly approve the send.