MCP tools reference

Hostelworld MCP tools

15 tools for Hostelworld on the Cotlet MCP server. Your agent picks them from tools/list.

MCP server
https://cotlet.dev/mcp/v1
Connects with
Your own Hostelworld Inbox (property) account; PayNow tools need a Manager user
Integration page
Hostelworld
Hostelworld Endpoints
Endpoint Access Description
hostelworld_list_new_bookings read Bookings in the New Bookings tab that you have not acknowledged yet.
hostelworld_search_bookings read Advanced Search by arrival or booked date, or by reference, guest name or email.
hostelworld_get_booking read Booking details: guest, dates, rooms or beds, rate type, deposit paid, balance due and status. No card data.
hostelworld_list_reviews read Reviews from Reports > Customer Ratings, with ratings, text, booking reference and whether you replied.
hostelworld_list_chats read Guest chats in the Inbox, newest first, with booking reference and unread flag.
hostelworld_get_chat read All messages in one guest chat, and whether it is still open or read-only after checkout.
hostelworld_list_payouts read PayNow payouts from Property Setup > Finance > Pay Now: date, status, amount, masked bank account, plus balance and next payout date. Manager users only.
hostelworld_get_payout read One payout: timeline, Payout Trace ID, charges, refunds, adjustments, fees, net amount and every payment it includes.
hostelworld_export_guest_payments read Guest Payments export as a CSV download link, with booking IDs for reconciliation. Manager users only.
hostelworld_acknowledge_booking write Click "I have read this booking" so the booking leaves the New Bookings tab and Hostelworld knows you picked it up.
hostelworld_reply_to_review write Public reply under a review. Hostelworld checks it before publishing and it cannot be edited after.
hostelworld_query_review write Send a review to a Hostelworld moderator when you believe it breaks the review guidelines.
hostelworld_send_chat_message write Reply to a guest in Property Chat, or start a chat from a booking when the Chat option is available.
hostelworld_report_payment_issue write Report Payment Issue on a booking: the guest gets an email asking them to pay.
hostelworld_mark_no_show write Cancel a booking as a no-show and email the guest. Available from the check-in date, not for Pay Now.

List new bookings

read

MCP tool hostelworld_list_new_bookings

Returns the bookings waiting in the New Bookings tab, with the booking reference, guest name, arrival date and booked date. A booking leaves the list once you acknowledge it. With a channel manager the list is usually empty, because bookings are acknowledged there. Pass booking_ref to get_booking for full details.

Parameters

Parameters: list_new_bookings
NameTypeDescription
limit integer 1 to 100. Default: 50.
cursor string Next page cursor from the previous call.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_list_new_bookings",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "bookings": [
      {
        "booking_ref": "412-305871264",
        "guest": "Jan Kowalski",
        "arrival": "2026-10-18",
        "nights": 2,
        "booked_at": "2026-10-10T21:14:00Z"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}

Search bookings

read

MCP tool hostelworld_search_bookings

Searches acknowledged and new bookings the way the Inbox search bar and Advanced Search do. Use a date range with date_type, or query for a booking reference, guest name or email. Results show reference, guest, arrival date and status. Pass booking_ref to get_booking for the details.

Parameters

Parameters: search_bookings
NameTypeDescription
date_type enum arrival or booked. Default: arrival.
from date Start of the date range.
to date End of the date range.
query string Booking reference, guest name or email instead of dates.
cursor string Next page cursor from the previous call.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_search_bookings",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "bookings": [
      {
        "booking_ref": "412-305871264",
        "guest": "Jan Kowalski",
        "arrival": "2026-10-10",
        "nights": 1,
        "status": "confirmed"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}

Get booking

read

MCP tool hostelworld_get_booking

Returns one booking as the booking page shows it: guest, arrival date, nights, room type and number of people, rate type, deposit paid, balance due and status. Card information is never returned. Use it before mark_no_show or report_payment_issue to check the status and the rate type.

Parameters

Parameters: get_booking
NameTypeDescription
booking_ref required string Hostelworld booking reference from search_bookings or list_new_bookings.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_get_booking",
    "arguments": {
      "booking_ref": "booking ref"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_ref": "412-305871264",
    "status": "confirmed",
    "guest": "Jan Kowalski",
    "arrival": "2026-10-10",
    "nights": 1,
    "room": "6-bed mixed dorm",
    "guests": 1,
    "rate_type": "flexible",
    "currency": "EUR",
    "total": 24,
    "deposit_paid": 2.4,
    "balance_due": 21.6
  },
  "isError": false
}

List reviews

read

MCP tool hostelworld_list_reviews

Returns the reviews that came in during the date range, the same list as Reports > Customer Ratings. Hostelworld allows a range of up to one year at a time. Set unanswered_only to skip reviews you replied to. Pass booking_ref to reply_to_review or query_review.

Parameters

Parameters: list_reviews
NameTypeDescription
from required date Start date. The range can be up to one year.
to required date End date.
unanswered_only boolean Skip reviews you already replied to.
cursor string Next page cursor from the previous call.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_list_reviews",
    "arguments": {
      "from": "2026-10-01",
      "to": "2026-10-01"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "reviews": [
      {
        "booking_ref": "412-305871264",
        "rating": 7.1,
        "text": "Great location, but no hot water in the morning.",
        "language": "en",
        "replied": false,
        "reviewed_at": "2026-10-05T09:30:00Z"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}

List guest chats

read

MCP tool hostelworld_list_chats

Lists Property Chat conversations, newest first, with the guest name, booking reference and whether there are unread messages. Property Chat must be switched on in Inbox first. Pass chat_id to get_chat.

Parameters

Parameters: list_chats
NameTypeDescription
unread_only boolean Only chats with unread guest messages.
limit integer 1 to 100. Default: 50.
cursor string Next page cursor from the previous call.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_list_chats",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "chats": [
      {
        "chat_id": "ch_77a2",
        "booking_ref": "412-305871264",
        "guest": "Jan Kowalski",
        "unread": true,
        "last_message": "What time can I check in?",
        "updated_at": "2026-10-09T15:02:00Z"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}

Get chat

read

MCP tool hostelworld_get_chat

Returns the messages of one chat, oldest first, as text. Chats are open from the confirmed booking until the guest checks out and read-only after that. Images and files are not part of Property Chat.

Parameters

Parameters: get_chat
NameTypeDescription
chat_id required string Chat ID from list_chats.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_get_chat",
    "arguments": {
      "chat_id": "chat_8c41d2"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "chat_id": "ch_77a2",
    "booking_ref": "412-305871264",
    "open": true,
    "messages": [
      {
        "from": "guest",
        "body": "What time can I check in?",
        "sent_at": "2026-10-09T15:02:00Z"
      }
    ]
  },
  "isError": false
}

List payouts

read

MCP tool hostelworld_list_payouts

Returns the Payouts tab: total balance, estimated next payout date and each payout with date, status, masked destination and amount. Status is initiated, in transit or completed. Only Manager user accounts in Inbox can view PayNow. Pass payout_id to get_payout.

Parameters

Parameters: list_payouts
NameTypeDescription
status enum all, initiated, in_transit or completed. Default: all.
from date Payouts on or after this date.
to date Payouts on or before this date.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_list_payouts",
    "arguments": {}
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "balance": {
      "amount": 464.4,
      "currency": "EUR"
    },
    "next_payout_date": "2026-10-14",
    "payouts": [
      {
        "payout_id": "po_2026_10_07",
        "date": "2026-10-07",
        "status": "completed",
        "destination": "Bank account ****4821",
        "amount": 464.4,
        "currency": "EUR"
      }
    ]
  },
  "isError": false
}

Get payout

read

MCP tool hostelworld_get_payout

Returns the payout side panel: status timeline, destination, Payout Trace ID, a summary of charges, refunds, adjustments and fees with gross and net, and every payment in the payout. Give the trace ID to your bank if a completed payout has not arrived after 5 business days. Manager users only.

Parameters

Parameters: get_payout
NameTypeDescription
payout_id required string Payout ID from list_payouts.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_get_payout",
    "arguments": {
      "payout_id": "po_2026_10_07"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "payout_id": "po_2026_10_07",
    "status": "completed",
    "trace_id": "tr_9F21K0Q4",
    "summary": {
      "charges": 520,
      "refunds": 40,
      "adjustments": 0,
      "fees": 15.6,
      "net": 464.4,
      "currency": "EUR"
    },
    "transactions": [
      {
        "booking_ref": "412-305871264",
        "amount": 200,
        "status": "succeeded"
      },
      {
        "booking_ref": "412-305871377",
        "amount": 180,
        "status": "succeeded"
      },
      {
        "booking_ref": "412-305871402",
        "amount": 140,
        "status": "refunded",
        "refunded": 40
      }
    ]
  },
  "isError": false
}

Export guest payments

read

MCP tool hostelworld_export_guest_payments

Generates the Guest Payments CSV for a date range and returns a download link. The file includes the booking ID, which matches your Hostelworld booking reference. Manager users only.

Parameters

Parameters: export_guest_payments
NameTypeDescription
from required date Start date.
to required date End date.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_export_guest_payments",
    "arguments": {
      "from": "2026-10-01",
      "to": "2026-10-01"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "url": "https://files.cotlet.example/exports/guest-payments-2026-09-30_2026-10-06.csv",
    "rows": 3,
    "from": "2026-09-30",
    "to": "2026-10-06"
  },
  "isError": false
}

Acknowledge booking

write Confirm

MCP tool hostelworld_acknowledge_booking

Marks one new booking as read. It leaves the New Bookings tab, stays in Inbox and stays searchable. Hostelworld asks you to do this for every booking. It cannot be undone with a tool. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: acknowledge_booking
NameTypeDescription
booking_ref required string Hostelworld booking reference from search_bookings or list_new_bookings.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_acknowledge_booking",
    "arguments": {
      "booking_ref": "booking ref"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_ref": "412-305871264",
    "status": "acknowledged"
  },
  "isError": false
}

Reply to review

write Confirm

MCP tool hostelworld_reply_to_review

Submits an owner's reply to one review. Write it in the language of the review or in English, and leave out the guest's name. Hostelworld checks the reply against its guidelines before it is published, and you cannot edit it after you submit it. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: reply_to_review
NameTypeDescription
booking_ref required string Hostelworld booking reference from search_bookings or list_new_bookings.
body required string Reply in the review's language or English. Do not use the guest's name.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_reply_to_review",
    "arguments": {
      "booking_ref": "412-305871264",
      "body": "Thanks for staying with us! We have fixed the hot water in dorm 3 since your visit. Hope to see you again."
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_ref": "412-305871264",
    "status": "pending_moderation",
    "submitted_at": "2026-10-11T14:22:05+02:00",
    "editable": false
  },
  "isError": false
}

Query review

write Confirm

MCP tool hostelworld_query_review

Sends your comments about one review to a Hostelworld moderator, who reviews it and replies to you. Hostelworld does not remove a genuine unfavorable review without sufficient evidence of a breach of its Review Guidelines, so include the evidence. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: query_review
NameTypeDescription
booking_ref required string Hostelworld booking reference from search_bookings or list_new_bookings.
reason required string Why the review breaks the guidelines, with evidence.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_query_review",
    "arguments": {
      "booking_ref": "booking ref",
      "reason": "reason"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_ref": "412-305871264",
    "status": "sent_to_moderator"
  },
  "isError": false
}

Send chat message

write Confirm

MCP tool hostelworld_send_chat_message

Sends a text message to a guest in Property Chat. Use chat_id to reply, or booking_ref to message from a booking when Hostelworld shows the Chat option for it. Chat supports text only and is read-only after the guest checks out. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: send_chat_message
NameTypeDescription
chat_id string Chat ID from list_chats. Use this or booking_ref.
booking_ref string Start a new chat from this booking.
body required string Message text.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_send_chat_message",
    "arguments": {
      "chat_id": "ch_77a2",
      "body": "Hi! Check-in opens at 14:00. You can leave your bag in our luggage room from 08:00. After 22:00, ring the bell at the side door."
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "chat_id": "ch_77a2",
    "status": "sent",
    "sent_at": "2026-10-09T15:10:00+02:00"
  },
  "isError": false
}

Report payment issue

write Confirm

MCP tool hostelworld_report_payment_issue

Triggers Hostelworld's automatic payment request email to the guest. Use it only when the payment deadline in your policy has expired and your terms were visible at booking. If the guest does not pay within 24 hours, you can ask Hostelworld support to cancel the booking. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: report_payment_issue
NameTypeDescription
booking_ref required string Hostelworld booking reference from search_bookings or list_new_bookings.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_report_payment_issue",
    "arguments": {
      "booking_ref": "booking ref"
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_ref": "412-305871264",
    "status": "payment_request_sent"
  },
  "isError": false
}

Mark as no-show

write Confirm

MCP tool hostelworld_mark_no_show

Marks the booking as a no-show, which cancels it and emails the guest. It works from the check-in date until 23:59 on that date for a one-night booking, or 48 hours after check-in for a longer stay. It does not apply to Pay Now rates or to a group where only one guest is missing. Your comment goes to Hostelworld support, not to the guest. By default you confirm each call; you can switch that off for this tool.

Parameters

Parameters: mark_no_show
NameTypeDescription
booking_ref required string Hostelworld booking reference from search_bookings or list_new_bookings.
comment string Note for Hostelworld support, not shown to the guest.

tools/call

JSON-RPC 

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_mark_no_show",
    "arguments": {
      "booking_ref": "412-306110482",
      "comment": "Guest did not arrive by 22:30 and sent no message."
    }
  }
}

Example response

{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_ref": "412-305871264",
    "status": "cancelled_no_show"
  },
  "isError": false
}