# Travala MCP

MCP server for hotel search and booking via [Travala.com](https://www.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](https://github.com/travala/travel-mcp/blob/main/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](https://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:

```bash
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):

```json
{
  "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`](https://github.com/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](https://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:

```bash
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](https://8004scan.io/agents)) and `rewardWallet` (a standard EVM/ETH address on Base). See [Agent Registration & Rewards](#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)
```

```bash
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:

```bash
# 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.