Hosperly MCP Connector
Run your rates, availability, fees and channel pricing from a Claude or ChatGPT conversation.
Hosperly is a property management system for short-term rental and hotel hosts, with a built-in channel manager for Airbnb, Booking.com, Expedia and other sales channels. The Hosperly connector uses the Model Context Protocol (MCP) to let an AI assistant read and, with your permission, change data on your own Hosperly account.
What it does
- Check bookings by status, property or date range, and see nightly availability and rates.
- Open or close dates (stop-sell) across every connected sales channel at once, and add private calendar notes.
- Set an exact nightly rate, apply a percent or fixed markup, and set minimum stay, maximum stay and closed-to-arrival/departure restrictions over any date range.
- Set one rate across all units of a room type in a multi-unit property.
- Preview the fully resolved price for a date, including rules, fees, taxes and what each connected channel would show.
- Manage per-channel price uplifts and custom prices for one channel on one property.
- Create and edit calendar pricing rules (weekends, seasons) and booking-time discounts (early-bird, non-refundable, long-stay, returning-guest).
- Manage fees and taxes added on top of bookings.
You refer to properties by name ("Sunset Villa"). The assistant looks up the matching property for you before it acts.
Requirements
- A Hosperly account with at least one property. Sign up at app.hosperly.com.
- A Hosperly user with the owner or manager role. Only these roles can approve a connection.
- Claude or ChatGPT with support for custom MCP connectors.
- Connected sales channels are optional. Calendar and pricing tools work without them.
Connect from Claude
Connector URL:
https://api.hosperly.com/api/mcp
- In Claude (desktop app or browser), open Settings → Connectors and choose Add custom connector.
- Name it Hosperly and paste the connector URL above.
- Leave authentication on Sign in and the OAuth client on Register automatically. No API key is needed.
- Claude opens the Hosperly sign-in page. Sign in as you normally do.
- Review the permissions on the Allow page. You can untick any of them, but you cannot add more than the app asked for. Click Allow.
- Back in Claude, the Hosperly connector shows its tools. Start a chat and ask, for example, "What bookings arrive this week?"
Connect from ChatGPT
- In ChatGPT, open Settings → Plugins (or Apps) and add Hosperly from the directory. To add it manually, enable Developer mode, then create an MCP app.
- For a manual setup, paste the connector URL
https://api.hosperly.com/api/mcpunder Connection and leave authentication on OAuth. - Sign in to Hosperly when asked, review the permissions on the Allow page and click Allow.
- Start a chat, enable Hosperly for it if asked, and try a prompt from Example prompts.
Sign-in only for ChatGPT. ChatGPT connects through the OAuth sign-in flow. API keys
are not supported there. Developers using Claude Code or the MCP Inspector can also use an API
key created under Settings → API Keys in Hosperly and sent in the
x-api-key header.
Permissions
Every tool needs one permission. On the Allow page you choose which permissions to grant, so you can give an assistant read-only access, or read and write. A tool called without its permission returns an error naming the permission that is missing.
| Permission | Allows | Tools |
|---|---|---|
bookings:read | View bookings | list_bookings |
properties:read | View account, properties and connected channels | get_account, list_properties, list_channels |
calendar:read | View availability, restrictions and calendar notes | get_calendar_availability |
calendar:write | Open/close dates, add or remove calendar notes | set_availability, set_calendar_note, delete_calendar_note |
rates:read | View rates, rules, fees and channel pricing | get_price_simulation, get_channel_pricing, list_rate_plan_channel_mappings, list_pricing_rules, list_pricing_charges |
rates:write | Change rates, rules, fees and channel pricing | set_pricing, set_room_type_rate, set_channel_pricing, set_rate_plan_channel_mapping, delete_rate_plan_channel_mapping, create_pricing_rule, update_pricing_rule, delete_pricing_rule, create_pricing_charge, update_pricing_charge, delete_pricing_charge |
Tools
The connector exposes 24 tools. Money amounts in tool results and inputs are integers in the
currency's minor units (for example 150.00 USD is 15000; JPY has no decimals, so 150 JPY is
150). Each result includes minor_unit_digits so the amount is read correctly; the
assistant does the conversion for you. Write tools marked dry run can preview the affected days and
properties without changing anything.
Account, properties and bookings
| Tool | Type | What it does |
|---|---|---|
get_account | Read | Account profile: name, contact email, phone, address, country, locale, currency and timezone. Never returns credentials or billing information. |
list_properties | Read | Properties and units (paginated): type, active status, capacity, bedrooms, bathrooms, base price, country. Never returns Wi-Fi passwords or access codes. |
list_bookings | Read | Bookings (paginated), filterable by property, date range and status (pending, confirmed, canceled): guest name, property, stay dates, nights, guest counts, source channel and amount. Does not return guest email, phone, tax ID, nationality or payment-provider details. |
Calendar and availability
| Tool | Type | What it does |
|---|---|---|
get_calendar_availability | Read | Nightly availability and base rate per property over a date range (up to 92 days), with minimum/maximum stay, closed-to-arrival/departure and any private note on that night. |
list_channels | Read | Connected sales channels (Airbnb, Booking.com and others) and the property each is connected to. |
set_availability | Write | Open or close dates (stop-sell) for one or more properties over one or more date ranges, applied to every connected channel at once. Optional day-of-week filter and dry run. |
set_calendar_note | Write | Add or edit a private note on a date range or a booking. Visible only inside Hosperly, never sent to guests or sales channels. |
delete_calendar_note | Write | Delete a private calendar note. Cannot be undone. |
Rates and channel pricing
| Tool | Type | What it does |
|---|---|---|
set_pricing | Write | Set an exact rate, apply a percent or fixed markup, or set minimum stay, maximum stay and closed-to-arrival/departure, for one or more properties over one or more date ranges. Optional dry run. |
set_room_type_rate | Write | Set one exact nightly rate across every unit sharing a room type in a multi-unit property. Optional dry run. |
get_price_simulation | Read | The fully resolved price for one property on one date: winning pricing rule, fees and taxes, and what each connected channel would show. |
get_channel_pricing | Read | The account's default uplift or markdown percentage for each sales channel. |
set_channel_pricing | Write | Set the default uplift or markdown percentage for one channel (for example Airbnb +8%, Direct −5%). |
list_rate_plan_channel_mappings | Read | Per-channel price status for a property: standard rate, pending, applied or failed. |
set_rate_plan_channel_mapping | Write | Give one channel a different price on one property: standard rate, a percent/fixed markup, or a flat custom price. Applied asynchronously. |
delete_rate_plan_channel_mapping | Write | Permanently remove a property's custom price override for one channel. Refused if the channel is live and selling through it. Cannot be undone. |
Pricing rules
| Tool | Type | What it does |
|---|---|---|
list_pricing_rules | Read | Pricing rules (paginated): calendar rate adjustments and booking-time discounts, with schedule, adjustment, priority and the properties they apply to. |
create_pricing_rule | Write | Create a calendar rule (weekday or season) or a booking-time discount (early-bird, non-refundable, long-stay, returning-guest) for a set of properties. |
update_pricing_rule | Write | Change an existing rule. Only the fields provided change. |
delete_pricing_rule | Write | Delete a rule. Affected properties are recalculated without it. Cannot be undone. |
Fees and taxes
| Tool | Type | What it does |
|---|---|---|
list_pricing_charges | Read | Fees and taxes added on top of bookings (paginated): type, flat or percent amount, property scope and whether enabled. |
create_pricing_charge | Write | Create a fee or tax, flat or a percent of the base price, for one property or account-wide. |
update_pricing_charge | Write | Change an existing fee or tax. Only the fields provided change. |
delete_pricing_charge | Write | Delete a fee or tax. It stops being added to bookings immediately. Cannot be undone. |
Example prompts
Read
- "Show me confirmed bookings arriving in the next 30 days."
- "Is Sunset Villa free from December 24 to 28, and what's the rate?"
- "Which sales channels are connected, and to which properties?"
- "What would a guest actually pay for Seaside Loft on July 4th, all in?"
- "What fees and taxes do I have set up?"
Change
- "How many nights would be affected if I closed everything for Christmas week? Don't change anything yet." (dry run)
- "Close Seaside Loft from Oct 12 to Oct 15 and add a note that the boiler is being replaced."
- "Raise Sunset Villa 10% for New Year's Eve, then show me what a guest would pay with taxes."
- "Set a 3-night minimum stay at Sunset Villa for July."
- "Add a 5% uplift on Booking.com."
- "Add a 15% weekend rule on Fridays and Saturdays, and a flat cleaning fee of 30 to Sunset Villa."
Safety and data
- Your account only. A connection can only reach the Hosperly account of the user who approved it.
- You control access. Grant read-only or read and write on the Allow page. Only owners and managers can approve.
- Dry runs. Availability and rate changes can be previewed before anything is written. Ask the assistant for a preview first.
- Everything is logged. Every change made through the connector appears in the Hosperly change log as an MCP entry named after the connected app.
- Minimal data. Tool results contain only the fields needed for the task. They do not include internal IDs, payment details, credentials, or sensitive guest data such as email, phone, tax ID or nationality.
- Customer-visible changes. Rate and availability changes are pushed to your connected sales channels (Airbnb, Booking.com and others) and are visible to guests there. Review what the assistant proposes before approving a change.
- Privacy. See our Privacy Policy and Terms of Service.
Limits
- Rate limits are per account: 300 requests per minute overall and 30 write-tool calls per minute. Above that the server answers HTTP
429; wait a minute and retry. - A single availability or pricing call covers up to 92 days per date range, 100 date ranges, 200 properties and 2,000 property-days.
- List tools are paginated; the assistant fetches further pages with the returned cursor.
- Closing or repricing applies to all connected channels together, except where a tool explicitly targets one channel (
set_channel_pricing,set_rate_plan_channel_mapping).
Disconnect
In Hosperly, open Settings → MCP → Connected apps and revoke the connection. The next tool call from that app fails immediately. You can also remove the connector inside Claude or ChatGPT.
Troubleshooting
| Problem | Fix |
|---|---|
| The Allow page says I cannot approve | Only owners and managers can approve a connection. Ask an owner or manager of the account. |
| A tool returns a "missing permission" error | The permission was unticked on the Allow page. Disconnect, then connect again and keep it ticked. |
| Connection fails or asks for an API key | Make sure authentication is set to Sign in / OAuth with automatic client registration. API keys are not used with the directory connector. |
| HTTP 429 | The per-account rate limit was reached. Wait a minute and retry. |
| A channel price shows as "pending" | Per-channel prices are applied asynchronously. Ask the assistant to check list_rate_plan_channel_mappings again shortly. |
| The assistant quotes a price you did not expect | Rates vary per day. Ask it to check get_price_simulation or get_calendar_availability for the exact dates. |
Technical details
| Server URL | https://api.hosperly.com/api/mcp |
|---|---|
| Transport | Streamable HTTP, stateless. POST only; GET and DELETE return 405. |
| Authentication | OAuth 2.1 authorization code with PKCE (S256) and dynamic client registration; resource-bound access tokens and rotating refresh tokens. |
| Protected resource metadata | https://api.hosperly.com/.well-known/oauth-protected-resource/api/mcp |
| Authorization server metadata | https://api.hosperly.com/oauth/.well-known/openid-configuration |
| Tool annotations | Every tool declares a title, readOnlyHint, destructiveHint and openWorldHint. |
| Interface | Text only. The connector shows no UI. |
Support
Questions, bug reports or connection problems: support@hosperly.com. Include the assistant you used (Claude or ChatGPT), the time of the problem, and the tool name if you know it.