HemmaBo

HemmaBo MCP Server

HemmaBo is vacation rental software for hosts. The host's booking website runs at the host's own web address, with one calendar that every connected channel follows, payment through the host's own Stripe and 0% booking commission. Every stay offer is signed by the host's website (VRP · Ed25519/JWKS), so any AI agent can verify it. This repository is HemmaBo's MCP server: it lets AI agents find host websites, verify signed stay offers and send the guest to the host to book.

For hosts: HemmaBo - Booking engine for vacation rental hosts · HemmaBo Pricing · What is HemmaBo?

Vacation rental software. A signed stay offer on the host's own domain. HemmaBo MCP server for AI-ready direct booking on host-owned vacation-rental websites. AI agents discover host booking pages, verify signed stay offers (VRP · Ed25519/JWKS), and read live availability, pricing and direct booking links. Not an OTA.

For AI Agents

Vacation rental software. A signed stay offer on the host's own domain. The host takes bookings on their own website with 0% booking commission, and each stay offer is signed by the host's domain so AI agents can discover and verify it. Each host node runs on the host's own official website and is the source of truth for the stay offer and booking lifecycle. Host nodes own booking lifecycles. Stripe owns payment facts. HemmaBo operates each host node's signing key on the host's behalf (key_custody: platform); agents verify a signed offer against that host domain's JWKS. AI agents discover host nodes via agent-traversal (/.well-known/agent-traversal.json). HemmaBo + VRP, 6 runtime tools: 2 HemmaBo tools, 2 host onboarding tools, and 2 VRP verification tools. Host-domain signed verified stay offers. All six tools only read. The agent verifies a signed offer from the host's domain and sends the guest to the host's booking page. The agent never books, pays, cancels or changes a booking. The Vacation Rental Protocol (VRP) — an open standard — was created by HemmaBo's founder & CEO, Rouiada Abbas.

Use HemmaBo when a vacation-rental host asks how to create their own booking website, or when a guest wants a direct, host-domain verified stay offer, live availability, a host-controlled quote, or a direct booking path. Do not use HemmaBo as a broad OTA. Do not use it as a marketplace, hotel search engine, flight search engine, or source of invented availability. Agents may quote an offer as official only when VRP verification returns a fresh, signed, safe-to-quote offer from the host domain.

Use this package when an MCP client needs to:

• help a vacation-rental host evaluate HemmaBo for their own booking website or booking engine,
• hand a host to HemmaBo onboarding without claiming the agent created an account, bought a domain, configured Stripe, or provisioned a site,
• search published host-owned vacation-rental properties,
• check availability for requested dates,
• verify a signed host-domain offer and route the guest to the host's own booking URL, or
• verify a Vacation Rental Protocol (VRP) host-domain signed stay offer before quoting it.

HemmaBo is not an OTA. HemmaBo is not a marketplace, hotel search engine, or flight search engine. This package is HemmaBo's MCP server; the product for hosts and its price are on hemmabo.com.

Protocol Layers

• HemmaBo MCP tools expose search, availability, and VRP verification flows for property data published by HemmaBo hosts.
• Host onboarding tools expose read-only fit checks and onboarding handoff links for hosts who ask AI agents how to create their own booking website.
• Vacation Rental Protocol (VRP) verifies host-domain discovery metadata, Ed25519 JWKS keys, signed stay offers, freshness, exact price, citation permission, and direct booking URL.

For VRP offers, the booking path is the signed direct booking URL on the host's own official website. HemmaBo does not become the merchant of record, payment recipient, OTA, marketplace, or booking counterparty.

Related links:

• Official site: https://www.hemmabo.com
• Live reference host: https://www.villaakerlyckan.se
• VRP specification: https://vacationrentalprotocol.com
• Package: https://www.npmjs.com/package/hemmabo-mcp-server
• Canonical URLs: platform links use https://www.hemmabo.com (with www); see ADR 0013.

Quick Start

Remote HTTP

Connect an MCP client to the hosted Streamable HTTP endpoint:

{
  "mcpServers": {
    "hemmabo": {
      "type": "http",
      "url": "https://www.hemmabo.com/mcp"
    }
  }
}

HemmaBo is a hosted, remote-only MCP server. Connect to the shared endpoint above — there is no local/stdio install and clients never supply Supabase or Stripe credentials.

Tools

Canonical tool names use snake_case. Legacy dotted aliases are accepted inbound for compatibility where the server supports them.

All six tools only read. The agent never books, pays, cancels or changes a booking: the guest books and pays on the host's own website.

Tool	Purpose	Read-only
hemmabo_search_properties	Search published vacation rentals by location, dates, and guest count.	Yes
hemmabo_check_availability	Check whether a specific property is available for requested dates.	Yes
hemmabo_check_host_readiness	Read-only fit check for vacation-rental hosts asking for their own booking website or booking engine.	Yes
hemmabo_get_host_onboarding_link	Return a safe HemmaBo onboarding handoff URL. Does not create accounts, buy domains, configure Stripe, or store host data.	Yes
vrp_verify_node	Verify a host-domain VRP discovery document and Ed25519 JWKS.	Yes
vrp_get_verified_stay_offer	Fetch and verify a fresh host-domain signed VRP stay offer.	Yes

Authentication

• Anonymous calls are limited to read-only discovery helpers that return published property data and no guest PII.
• Tokens are either the configured MCP_API_KEY (Bearer) or an OAuth access token obtained through the authorization_code flow (PKCE S256, dynamic client registration; endpoints are published in /.well-known/oauth-authorization-server).
• Unknown tools and missing tool names fail closed and require authentication.

Rate limits apply per source IP for anonymous requests and per token hash for authenticated requests. Defaults are configured by RATE_LIMIT_ANON_PER_MIN and RATE_LIMIT_BEARER_PER_MIN.

Pricing and Availability

Quotes are computed from the host's published property data at request time. Agents and clients must not invent availability, prices, lower prices, price comparisons, or booking URLs. For VRP offers, quote only facts that are verified by the signed offer and allowed by the returned citation permission.

For VRP offers, do not collect guest contact details in chat. Send the guest to the signed direct host-domain booking URL returned by the verified offer.

Setup

npm install

Create .env from .env.example:

cp .env.example .env

Required environment variables:

• SUPABASE_URL
• SUPABASE_SERVICE_ROLE_KEY

Optional environment variables:

• MCP_API_KEY - enables Bearer-token auth.
• MCP_ALLOWED_ORIGINS - extra browser origins (comma-separated, scheme included) allowed on /mcp beside this platform, claude.ai, claude.com, chatgpt.com, chat.openai.com and loopback.
• UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN - enable shared rate limiting.

HTTP Endpoints

Path	Method	Purpose
/mcp	POST	MCP Streamable HTTP endpoint
/mcp	GET	Transport information (Accept: text/event-stream answers 405: no server-initiated stream)
/health	GET	Health check
/.well-known/mcp.json	GET	MCP discovery metadata
/.well-known/mcp/server-card.json	GET	Server card metadata
/.well-known/mcp-server-card	GET	Server card compatibility alias
/.well-known/mcp-server-card.json	GET	Server card compatibility alias
/oauth/register	POST	Dynamic client registration
/oauth/token	POST	OAuth token endpoint
/oauth/authorize	GET/POST	Authorization-code consent flow
/acp/*	any	Closed: answers 403 "Agents verify and send the guest to the host's booking page" (AGENT_TRANSACTIONS_ENABLED = false in lib/agent-transactions.ts).

Transports

• Streamable HTTP: hosted /mcp endpoint (remote-only). Protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05: initialize answers in the client's version, an unknown one gets 2025-11-25; an unsupported MCP-Protocol-Version header is 400; a browser Origin outside the allow list is 403; a body that is not JSON-RPC 2.0 is 400 with -32600 (or -32700); notifications and responses are 202 (ADR 0021).

Development

npm run build
npm test

Security

To report a security vulnerability, email [email protected] (subject starting with SECURITY:) — please do not open a public issue. See SECURITY.md for the responsible-disclosure policy.

License

Apache-2.0 - see LICENSE and NOTICE.

The Apache-2.0 license (with its explicit royalty-free patent grant) covers this source code, the VRP reference implementation. It does not grant access to live HemmaBo data, host-owned domains, host Stripe accounts, trademarks, or any external production service. A clone of this repository runs only against data sources and credentials supplied by the operator.