Travala MCP

MCP server for hotel search and booking via Travala.com. Enables AI agents to search hotels, compare room packages, and complete bookings — including payment — through natural language.

Tools

travala_search_hotel

Search for hotels by location and dates.

Inputs:

Parameter	Type	Required	Description
location	string	✓	City, region, or hotel name (e.g. "Paris", "Bali")
checkIn	string	✓	Check-in date in YYYY-MM-DD format
checkOut	string	✓	Check-out date in YYYY-MM-DD format
rooms	string[]	✓	Room occupancy strings (e.g. ["2"] = 1 room, 2 adults)
lat / lng	number	—	Coordinates for more precise results
minPrice / maxPrice	number	—	Price range per night in USD
filters	string[]	—	all_inclusive, free_breakfast, swimming_pool, ocean_view
response_format	string	—	markdown (default) or json

Returns: List of hotels with name, star rating, price, amenities, and a sessionId for subsequent calls.

---

travala_search_package

Get available room types and rate plans for a specific hotel.

Inputs:

Parameter	Type	Required	Description
hotelId	string	✓	Hotel ID from travala_search_hotel result
sessionId	string	—	Session ID from the same search flow
checkIn / checkOut	string	—	Dates (if not carried from session)
rooms	string[]	—	Room occupancy (if not carried from session)
filters	string[]	—	Same filter options as hotel search
response_format	string	—	markdown (default) or json

Returns: Room types, rate plans, meal inclusions, refund policies, and a packageId for booking.

---

travala_book

Book a hotel package and initiate payment.

Inputs:

Parameter	Type	Required	Description
packageId	string	✓	Package ID from travala_search_package
sessionId	string	✓	Session ID from travala_search_hotel
customer.firstName	string	✓	Guest first name
customer.lastName	string	✓	Guest last name
customer.email	string	✓	Guest email
customer.phone	string	✓	Guest phone with country code (e.g. +1...)

Returns: Booking confirmation with booking ID and payment instructions (x402 payment protocol).

---

travala_book_status

Recovery lookup for a travala_book call that errored, timed out, or returned a missing/garbled response. Use this before retrying — the booking may have already succeeded server-side, and a blind retry would double-charge the user.

Inputs:

Parameter	Type	Required	Description
packageId	string	✓	Same packageId sent to the failed travala_book
sessionId	string	✓	Same sessionId sent to the failed travala_book

Returns: An interpretation field and httpStatus that tell the agent how to proceed:

interpretation	httpStatus	Meaning
completed	200	Booking succeeded. body contains the confirmation — present as success, do NOT retry payment.
in_progress	202	Server still settling. Wait body.retry_after_ms, then poll again (cap ~6 polls).
not_found	404	Nothing happened server-side. Safe to retry travala_book.
invalid_request	400	Check packageId/sessionId; session may have expired.
server_error	5xx	Recovery endpoint down. Tell user to check email for confirmation; do not retry.

---

travala_manage_bookings

Look up details of an existing booking.

Inputs:

Parameter	Type	Required	Description
bookingId	string	✓	Booking ID (e.g. MN5V9DWQ)
lastName	string	✓	Last name used when booking

Returns: Booking status, hotel name, room, check-in/check-out dates, price, cancellation policy, and confirmation link.

---

travala_cancel_booking

Cancel an existing booking.

Inputs:

Parameter	Type	Required	Description
bookingId	string	✓	Booking ID
lastName	string	✓	Last name on the booking
email	string	✓	Email address on the booking

Returns: Cancellation status, refund amount, cancellation fee, and policy summary.

---

Agent Registration & Rewards

Every travala_book call sends an agentId and rewardWallet to attribute the booking and route cbBTC giveback to your agent.

The skill file skills/travala-booking-expert/SKILL.md ships with both values empty by default. To earn rewards under your own agent identity, open that file and fill in the two lines with your own values:

agentId      = "your-agentId-from-8004scan"
rewardWallet = "0xYourEvmAddressOnBase"

• agentId — self-register at 8004scan.io/agents to get an ID via the ERC-8004 registry. Travala does not issue these.
• rewardWallet — any EVM address on Base (EOA, multi-sig, treasury contract). Does not have to be the wallet that pays for the booking.
• Payout is made in cbBTC after the booking is marked completed (on or after guest check-in, subject to Travala's standard refund/cancellation window).

Without editing these values, bookings are attributed to the default agent and you earn nothing.

---

Typical flow

travala_search_hotel → travala_search_package → travala_book
                                                      ↓
                                          travala_manage_bookings
                                          travala_cancel_booking

                  (on book failure/timeout) → travala_book_status

Setup

Step 1 — Add Travala MCP

Claude Desktop

1. Open Claude Desktop → Customize → Connectors
2. Click + → Add custom connector
3. Fill in the popup:
   • Name: Travala MCP
   • Remote MCP Server URL: https://travel-mcp.travala.com/mcp
4. Click Add — done.

Claude Code

Claude Code supports remote MCP servers natively. Run:

claude mcp add --transport http travala-mcp https://travel-mcp.travala.com/mcp

Or add manually to ~/.claude.json (user scope) or .mcp.json (project scope):

{
  "mcpServers": {
    "travala-mcp": {
      "type": "http",
      "url": "https://travel-mcp.travala.com/mcp"
    }
  }
}

Verify with claude mcp list.

---

Step 2 — Install Coinbase Agentic Wallet MCP (required for payment)

travala_book returns an HTTP 402 with x402 payment details. To complete the payment, you need @coinbase/payments-mcp installed alongside this server.

Prerequisite — Install Node.js

The npx command ships with Node.js. If you don't already have it, install Node.js (which includes npm and npx) before running the command below:

• macOS / Linux / Windows: download the LTS installer from nodejs.org and follow the prompts.
• macOS (Homebrew): brew install node
• Verify installation: open a new terminal and run node -v and npx -v — both should print a version number.

Once Node.js is installed, run:

npx @coinbase/payments-mcp

When prompted, select your client (Claude for Desktop, Claude Code for CLI). The installer auto-configures the MCP entry. Restart your client after installation.

---

Step 3 — Install the booking skill

The travala-booking-expert skill ships rules and workflow logic. The agentId and rewardWallet fields are empty — fill them in if you want bookings attributed to your agent.

Before installing — fill in your values (optional, but required to earn rewards). Open skills/travala-booking-expert/SKILL.md and set agentId (from 8004scan) and rewardWallet (a standard EVM/ETH address on Base). See Agent Registration & Rewards above for the exact format.

Claude Desktop

Claude Desktop supports custom skills via .zip upload.

1. Enable Skills

• Open Claude Desktop → Settings
• Go to Capabilities (or Features) and toggle Skills on if not already enabled

2. Zip the skill folder

The zip must keep the folder name at the top level:

travala-booking-expert.zip
└── travala-booking-expert/
    ├── SKILL.md          (required — metadata + instructions)
    └── references/       (optional — auto-loaded on demand)

cd skills && zip -r travala-booking-expert.zip travala-booking-expert/

3. Upload

• Customize → Skills
• Click + → Create Skill → Upload a Skill
• Select travala-booking-expert.zip
• Toggle the skill on in the list

Claude Desktop reads the skill description and auto-activates it when it matches the user's intent (e.g. "find me a hotel in Tokyo").

Claude Code

Copy the skill folder into your skills directory:

# Project-scoped (only this project)
cp -r skills/travala-booking-expert .claude/skills/

# OR user-scoped (all projects)
cp -r skills/travala-booking-expert ~/.claude/skills/

Claude Code auto-loads skills on startup. The references/ files come along automatically — the agent reads them on demand.