MCP AI Assistants

AI assistants (MCP)

FewohBee includes a server for the Model Context Protocol (MCP). AI assistants such as Claude Code, Cursor, VS Code, n8n or your own agents connect to it and can then evaluate your data, write operations reports, check availability and prices and – if you allow it – create reservations.

Table of contents

• How it works
• Enabling MCP
• Creating an access token
• Connecting a client
• Tools and permissions
• Security model
• HTTPS in the local network
• Troubleshooting

How it works

• Endpoint: https://<your-host>/mcp (Streamable HTTP; both the stateless 2026-07-28 revision and the older session-based revisions are supported). Responses are plain JSON, no long-lived streams.
• Authentication: a personal access token (fwb_…) created with the use AI assistant (MCP), sent as Authorization: Bearer fwb_…. HTTP Basic is not accepted on /mcp. AI tokens do not work with the REST API, and REST tokens do not work with /mcp.
• A token can never do more than its owner: every permission additionally requires the matching user role.
• OAuth-based connectors (claude.ai web, ChatGPT, the connector dialog of Claude Desktop) are not supported yet.

Enabling MCP

MCP is off by default and needs two switches:

1. Operator – environment variables (.env of fewohbee-dockerized):

   Variable	Default	Meaning
   MCP_ENABLED	false	Makes the feature available at all.
   MCP_ALLOW_INSECURE_HTTP	false	/mcp requires HTTPS except from loopback. Set to true only in a trusted LAN without TLS.

2. Administrator – Settings → AI assistants: switch on Allow AI assistants and, if wanted, AI assistants may create reservations. Both switches apply to all users; each user then chooses per access what the AI may read and whether it may create reservations (only offered while the second switch is on). Under Addresses of this FewohBee installation the administrator lists the host names FewohBee is reached under – the host of the endpoint URL, not the address of the AI client (one per line, e.g. fewohbee.example.com; a pasted URL is reduced to its host). Requests for other hosts get 403 (DNS rebinding protection). localhost, 127.0.0.1 and [::1] are always allowed. When nothing is configured yet, the field suggests the host the settings page is opened with. The page also warns about a missing host entry or missing HTTPS, lists all AI access tokens of all users (with revoke) and all tool calls of the last 90 days, newest first (paginated).

Switching MCP on for the first time adds the system workflow Show AI assistant reservations in the notification window (Settings → Automations).

Creating an access token

Profile → API access → Create API access. The choice Use only appears while MCP is switched on.

• Use: AI assistant (MCP) – makes the token an AI token (internally the scope mcp:access). It is only accepted at /mcp, must expire (30 days, 90 days or 1 year) and is marked AI assistant in the token list.
• Below the token list the profile shows the endpoint URL (with copy button), a Claude Code example and a link to this page while MCP is switched on.
• For an AI token the form asks three questions. Permissions the user's roles do not back are greyed out with the reason; the info icon next to a permission lists the tools it unlocks; below the questions the form sums up in one sentence what the AI will be allowed to do (the token list and Settings → AI assistants show the same summary).
  • What may the AI see? – reservations and availability, prices, statistics and forecast, invoices, tourist tax, operations (room plan, housekeeping; operations:read, needs the operations role).
  • Which personal data goes to the AI? – Guest data (guests:read): names, contact details and remarks. Without it, guests only appear as a customer reference.
  • What may the AI change?
    • Create reservations – preview_reservation / create_reservation. Only while AI assistants may create reservations is switched on in the settings.
    • Set day prices and event prices (prices:write) – preview_day_prices / set_day_prices and preview_event_rule / create_event_rule. Administrators only; there is no separate switch in the settings.
    • Prepare bank statements (bank-import:write) – the bank import tools. Needs the cash journal role. Counterparty names and purposes of the transactions go to the AI (IBANs shortened to country code and last four digits).
• A REST token only offers what the REST API evaluates (including calendars and branches, which no AI tool uses).

Connecting a client

Claude Code

claude mcp add --transport http fewohbee https://fewohbee.example.com/mcp \
  --header "Authorization: Bearer fwb_..."

Cursor / VS Code (mcp.json)

{
  "servers": {
    "fewohbee": {
      "type": "http",
      "url": "https://fewohbee.example.com/mcp",
      "headers": { "Authorization": "Bearer fwb_..." }
    }
  }
}

Claude Desktop (claude_desktop_config.json, via the mcp-remote bridge)

{
  "mcpServers": {
    "fewohbee": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://fewohbee.example.com/mcp", "--header", "Authorization:${AUTH}"],
      "env": { "AUTH": "Bearer fwb_..." }
    }
  }
}

n8n – node MCP Client Tool, transport HTTP Streamable, authentication Header Auth with name Authorization and value Bearer fwb_....

Testing – npx @modelcontextprotocol/inspector lists the tools and lets you call them.

Tools and permissions

Tool	Needs	Purpose
get_property_overview	Read reservations	Properties, rooms, categories, guest categories, statuses, origins with ids
search_reservations, get_reservation	Read reservations	Reservations in a range (≤ 180 days) / by id; linked invoices with Read invoices
check_availability	Read reservations	Free rooms for a stay
get_occupancy_forecast	Read reservations	Booked, blocked and free rooms per night (≤ 366 nights) with totals and occupancy
get_price_quote	Read prices	Price of a stay; tourist tax with Read tourist tax
get_rate_calendar	Read prices	Rate per night and occupancy for a room category in a branch (≤ 366 nights): price list, price rules or day price; identical nights are merged into periods
get_price_list	Read prices	The configured price rows (room prices and extras with periods, weekdays, origins, categories)
get_price_rules	Read prices	The price rules (percentage changes) with their limits and rounding
get_occupancy_statistics, get_turnover, get_monthly_metrics	Read statistics	Utilization, turnover, monthly key figures
get_revenue_forecast	Read statistics	Expected gross revenue of the existing reservations per month of departure (≤ 36 months), valued like the prefilled invoice (room price, surcharges/discounts, booked extras, tourist tax); reservations with and without invoice separately
get_booking_pace	Read statistics	Room nights booked for a period by a cut-off day, compared with the previous year at the same day and with its final result (canceled reservations are not counted)
get_tourist_tax_report	Read tourist tax	Tourist tax per month
list_invoices, get_invoice	Read invoices	Invoices with totals and VAT; recipient only with Share guest data
search_guests	Share guest data	Find returning guests
get_operations_report	Read operations	Room plan per day (≤ 14 days): occupancy per room, guest count, housekeeping status, room blocks and the reservations involved with their extras; staff and guest names, notes and block reasons only with Share guest data
preview_reservation, create_reservation	Create reservations + admin switch	Book one room (see below)
preview_day_prices, set_day_prices	Set day prices and event prices (administrators only)	Day prices for single nights (see below)
preview_event_rule, create_event_rule	Set day prices and event prices (administrators only)	Price rule for the nights of an event (see below)
list_bank_import_drafts, get_bank_import_lines, get_bank_import_context, update_bank_import_lines	Prepare bank statements	Fill in accounts, tax rates and remarks of the user's own uncommitted bank imports (see below)

The prompts monthly_operations_report, daily_operations_briefing and price_review guide an assistant through a monthly report, a daily briefing for front desk, housekeeping and breakfast, and a price review with suggestions for event price rules and day prices (the assistant changes prices only after a confirmed preview).

Booking flow: preview_reservation checks availability, beds and the "at least one adult" rule, calculates the price including the booked extras and returns a previewToken (valid 10 minutes, bound to the access token and the exact arguments). create_reservation only books with that token and identical arguments; repeating the call returns the same reservation. Extras (breakfast, dog, final cleaning, …) are the misc prices that apply to the stay, as in the back-office form: pass their ids in extras; without it the prices marked active by default when creating a reservation are booked, [] books none. Conflicts with other reservations or room blocks always refuse the booking. An existing guest (matched by email) is linked, never modified. Every assistant booking triggers the workflow New reservation by AI assistant and appears in the notification window.

Price changes: a day price sets the room price of one night for a room category in a branch, stated for a number of guests; other occupancies and origins change in proportion, and the price rules do not apply on that night. preview_day_prices takes up to 366 nights (amount: null removes a day price), shows the current and the new price per night and skips past nights, nights without a price and day prices set by hand (replaced only with overwriteManual: true). Day prices from an assistant are held within the limits of the price rules; the price calendar shows them with the token name. preview_event_rule checks a percentage rule for the nights of an event, optionally limited to branches, room categories and weekdays, and shows on how many nights it applies, an example price and the other rules in the period. Lasting rules (weekends, last minute, occupancy) are set in FewohBee. Both previews return a previewToken (valid 10 minutes, bound to the access token, the arguments and – for day prices – the current day prices); set_day_prices and create_event_rule save only with it, and repeating the call returns the saved result. Existing reservations keep the price they were booked at.

Bank statements: uploading and committing stay in FewohBee (Journal → Bank import). Uploaded imports are drafts stored per user in the database (table bank_import_drafts, deleted after 2 days without changes and by app:purge-logs); an assistant only sees the drafts of its token owner. get_bank_import_lines returns the lines by status, get_bank_import_context the chart of accounts of the bank account, the valid tax rates and the active import rules, update_bank_import_lines sets debit/credit account, tax rate, remark, invoice number or ignored for up to 100 lines (ids are checked against the chart of accounts; duplicates are read-only). Drafts are locked while being changed, so the web page and the assistant can work at the same time. The draft rows are not written to the change log.

Security model

• Tool output is sent to the AI provider. Guest data leaves the installation only with Share guest data – except counterparty names and purposes of bank transactions under Prepare bank statements; free text is marked as untrusted_text so the model treats it as data (prompt injection).
• An assistant is only offered the tools its token may call (tools/list is filtered by the token's permissions); calls are checked again on execution.
• There are no tools that delete data, send emails, change settings or edit templates. The one exception are day prices and event price rules, behind prices:write (administrators only) and a confirmed preview.
• Limits: 120 requests per minute, 20 created reservations and 20 price changes per hour per token (plus the ingress limits on the hosted platform).
• Every tool call is logged (Settings → AI assistants, table mcp_tool_call_log, purged with app:purge-logs). Entity changes made through MCP carry the channel mcp and the token prefix in the change log.
• Admins can revoke any AI access token; deactivating a user disables all their tokens.

HTTPS in the local network

The token travels with every request, so /mcp requires HTTPS. AI clients (Node.js based) reject the self-signed default certificate of fewohbee-dockerized. Options:

1. Let's Encrypt with the DNS challenge (LETSENCRYPT=true, e.g. desec.io) – works without opening ports.
2. A reverse proxy with a valid certificate; set TRUSTED_PROXIES so FewohBee detects HTTPS.
3. Trust your own CA on the client: NODE_EXTRA_CA_CERTS=/path/to/ca.pem.
4. Last resort in a trusted LAN: MCP_ALLOW_INSECURE_HTTP=true.

Troubleshooting

Response	Cause
404	MCP_ENABLED is not true or the administrator switch is off.
403 Host not allowed.	The host name is missing under Addresses of this FewohBee installation (or a browser sent a foreign Origin).
403 The MCP endpoint requires HTTPS.	Plain HTTP from a non-loopback client; see above.
401	Token unknown, expired or owner inactive, or it is not an AI token (use REST API and calendar clients).
Tool error "lacks the permission …"	The token lacks the listed permission or its owner the matching role.
Tool error "switched off"	AI assistants may create reservations is off.