# HQBeds MCP > HQBeds gives you total control over hostel and hotel operations through your AI client. Manage reservations, check room availability, track guest profiles, and update occupancy status all in one chat interface. Stop juggling dashboards; get full PMS power instantly. ## Overview - **Category:** erp-operations - **Price:** Free - **Tags:** reservation-management, hostel-management, occupancy-tracking, channel-distribution, guest-communication, pms ## Description You connect this MCP to any of your preferred AI clients and treat it like a dedicated property management architect. Instead of logging into multiple systems, you simply ask your agent what you need done—whether that's checking if Room 205 is free next week or pulling up the payment history for John Smith. It handles everything from listing every current reservation to creating new bookings with just conversation. This capability makes it a central piece in any large Vinkius-powered catalog, letting your AI client manage real-world logistics and guest communications without you ever leaving your workspace. ## Tools ### check_hqbeds_status Tests whether the API connection to HQBeds is working correctly. ### create_reservation Makes a new booking for a guest in a specific room. ### get_account Retrieves general account information from HQBeds. ### get_guest Pulls up the full profile and history for a single guest. ### get_reservation Gets detailed information about one specific reservation. ### get_room Retrieves all the technical details for a particular room unit. ### list_availability Checks which rooms are free between two specific dates you provide. ### list_guests Shows a list of all guests recorded in the system. ### list_reservations Retrieves a summary list of all current and past bookings. ### list_rooms Lists every room available in the property, regardless of its status. ## Prompt Examples **Prompt:** ``` List all reservations checking in today. ``` **Response:** ``` You have 5 arrivals today. The first is John Smith in Room 101 (2 nights, paid). Would you like to see guest details or payment status for any of them? ``` **Prompt:** ``` Show room availability for this weekend. ``` **Response:** ``` This weekend you have 85% occupancy. 3 rooms are still available: Room 205 (double), Room 308 (single), and Room 412 (suite). Would you like to create a reservation? ``` **Prompt:** ``` Create a reservation for Maria Silva, Room 205, checking in May 10 and out May 12. ``` **Response:** ``` Done! Reservation created for Maria Silva in Room 205, May 10-12 (2 nights). Confirmation ID: RSV-4821. Would you like to send a confirmation email to the guest? ``` ## Capabilities ### Check Property Status Verify the API connection to HQBeds or pull up details for a specific account. ### Manage Room Inventory List all available rooms and check current availability based on dates you provide. ### Handle Reservations View, retrieve details for, or create entirely new guest reservations. ### Track Guest Data Pull up complete profiles and check-in histories for specific guests or list all registered users. ## Use Cases ### Handling a Group Block Booking A sales rep asks: 'I need 10 rooms for the corporate retreat next month.' Your agent runs `list_availability` for those dates, shows which room types are available, and then you use that data to suggest specific rooms and run `create_reservation` for each one. ### Checking a Client's Account Status A developer needs to know if the booking system is connected. They ask: 'What's the status?' The agent runs `check_hqbeds_status`, confirming API connectivity immediately, which saves hours of troubleshooting. ### Investigating a Missing Guest Profile The front desk lead knows a guest stayed but can't find them. They ask the agent to check `list_guests`. If found, they use `get_guest` to pull up the full profile and payment details for verification. ### Managing Day-to-Day Operations The manager needs a report on today's activity. They prompt: 'Show me all check-ins.' The agent runs `list_reservations`, providing an instant, accurate rundown of arrivals and departures. ## Benefits - Instant Occupancy Reporting: Instead of manually compiling check-in/check-out lists, you can ask your agent to list all reservations checking in today using `list_reservations`. This gives immediate operational oversight. - Fast Guest Lookup: Need a guest's history? Use `get_guest` to pull up complete profiles and payment data instantly. You don't need to navigate multiple internal CRM tabs. - Zero Downtime Booking: When a group needs last-minute rooms, you can check availability with `list_availability` and immediately follow up by creating the booking using `create_reservation`, all in one prompt sequence. - Room Intelligence: Use `get_room` to understand specific room attributes (like bedding or size) before suggesting it during a new reservation. This makes your recommendations accurate every time. - System Health Check: Before relying on this MCP for mission-critical tasks, run `check_hqbeds_status`. This confirms the connection is live and ready, saving you from unexpected failures. - Inventory Mapping: Need to know what rooms exist? Run `list_rooms` first. Then, use that list in combination with `get_room` to build a precise internal map of your whole property. ## How It Works The bottom line is you talk to your agent like a front-desk coordinator, and it executes the necessary booking steps across HQBeds for you. 1. First, subscribe to this MCP in Vinkius. 2. Next, grab your API Token from your HQBeds dashboard under Settings > Integrations. 3. Finally, connect it within your AI client (like Claude or Cursor) and start asking questions about bookings or availability. ## Frequently Asked Questions **How do I check room availability using the list_availability tool?** You must provide date ranges in ISO 8601 format (YYYY-MM-DD). The agent uses this data to confirm exactly which rooms are free for your specified dates. **Can I use get_guest to see past payment records?** Yes, `get_guest` pulls up the complete profile. This includes check-in history and details about previous payments made by that guest. **What's the difference between list_reservations and get_reservation?** `list_reservations` gives you a summary of many bookings (a roster). Use `get_reservation` when you know the specific ID and need all the detailed information for just that one booking. **Do I have to use get_account before creating a reservation?** No. While running `get_account` confirms your credentials, it isn't required for daily operations like making a booking using `create_reservation`. **What should I do if my connection fails when calling check_hqbeds_status?** The first step is always verifying your API credentials. If check_hqbeds_status reports an error, it means the token isn't recognized or has expired. Double-check that you retrieved the correct token from your HQBeds dashboard. **How do I get a full list of all available rooms using list_rooms?** list_rooms returns the complete directory of every room type and ID. After listing them, use get_room on a specific ID if you need details like amenities or capacity for that single unit. **If I want to check multiple guest records, should I use list_guests?** Yes, list_guests provides the directory of all current guests. You can then pick a specific name from that list and run get_guest to see their full profile details. **What happens if my attempt to create_reservation fails?** If the reservation fails, your agent will return an explicit error message explaining the issue. Common failures include trying to book a room that's already occupied or using invalid check-in dates. **How do I find my HQBeds API key?** Log in to your HQBeds dashboard, navigate to **Settings > Integrations**, and copy your API key from the credentials section. **Can my AI agent check room availability?** Absolutely. Use the `list_availability` tool to retrieve real-time availability across all rooms for any date range. **How do I create a new reservation?** Use the `create_reservation` tool with guest name, room ID, check-in and check-out dates. Your agent handles the rest automatically.