MCP Integration

trvl is an MCP server (protocol version 2025-11-25) for any MCP-compatible AI assistant.

One smart tool, not sixty-six

Here's the trick most MCP servers miss: advertising 66 tools burns ~33,500 tokens of your assistant's context before it does anything. trvl advertises one tool — travel — for about 378 tokens. That's a 98.9% smaller footprint, and those ~33K tokens go back to your assistant for actual thinking.

The 66 compatibility tool names still work — they route through travel via the intent field, so nothing breaks. Need the full classic surface advertised? Set TRVL_MCP_TOOL_MODE=legacy.

Setup

Claude Code

claude mcp add trvl --transport stdio -- trvl mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "trvl": {
      "command": "trvl",
      "args": ["mcp"]
    }
  }
}

Cursor / Windsurf / Other MCP clients

Add to your MCP configuration file:

{
  "mcpServers": {
    "trvl": {
      "command": "trvl",
      "args": ["mcp"]
    }
  }
}

mcp-gateway

backends:
  trvl:
    transport: stdio
    command: trvl mcp

Secure remote mode (HTTP + OAuth 2.1)

Local stdio is the default and the most private option. When you want trvl reachable over the network, it runs as an OAuth 2.1 resource server with read/write scopes:

trvl mcp --http --host 0.0.0.0 --port 8080 \
  --oauth-introspection-url https://YOUR-IDP/oauth2/introspect \
  --oauth-audience trvl-mcp

What that buys you:

• Deny by default. Binding to a non-loopback host with no auth configured refuses to start. No accidental open server. Localhost stays key-free for convenience.
• Scoped tokens. A read-only token can search. It cannot touch anything that writes your profile, watches, or trips; those need a write scope, and the call is rejected without one.
• Bring your own identity provider. trvl validates tokens; your IdP issues them (Authorization Code + PKCE on the client side).

Simpler setups can skip OAuth and use a static bearer token via TRVL_MCP_TOKEN, with scoped TRVL_MCP_READ_TOKEN and TRVL_MCP_WRITE_TOKEN available. Full deployment guide: docs/REMOTE-MCP-OAUTH.md.

MCP protocol features

Feature	Details
Structured content	Typed JSON (structuredContent) alongside human-readable summaries
Content annotations	audience: ["user"] for summaries, audience: ["assistant"] for data
Output schemas	Full JSON Schema validation for the travel router and every alias response
Prompts	plan-trip, find-cheapest-dates, compare-hotels, where-should-i-go
Resources	Airport codes (50 major hubs), flight/hotel usage guides, price-watch subscriptions
Tool description orchestration	find_trip_window instructs the LLM to fetch calendar data first
Progress notifications	Long-running searches stream progress tokens to the client
Resource subscriptions	Price-watch resources notify subscribers on price changes
Booking links	Direct flight, hotel, and provider handoff links when a source exposes them

Optional: Claude Code skill

The repo includes a Claude Code skill file that teaches Claude how to use trvl optimally:

mkdir -p ~/.claude/skills
curl -fsSL "https://raw.githubusercontent.com/MikkoParkkola/trvl/main/.claude/skills/trvl.md" \
  -o "$HOME/.claude/skills/trvl.md"

What the travel router covers

The common capabilities below are reachable through the single travel tool (put the family or the classic name in intent). The old tool names also still work directly as compatibility aliases; the complete 66-capability reference lives in docs/MCP-TOOLS-REFERENCE.md.

Tool	Purpose
search_flights	Search flights on a specific date
search_dates	Find cheapest day to fly across a date range
search_accommodations	Traveller-first room/apartment search with criteria-matched room-level offers
search_hotels	Search hotels in any city
hotel_prices	Compare hotel prices from Google
hotel_reviews	Get reviews for a specific hotel
hotel_rooms	Room-level availability, board, and cancellation details
destination_info	Travel intelligence for any city
calculate_trip_cost	Estimate total trip cost (flights + hotel)
weekend_getaway	Find cheap weekend destinations
suggest_dates	Smart date suggestions around a target date
optimize_multi_city	Find cheapest routing for multi-city trips
nearby_places	Points of interest near a location
travel_guide	Wikivoyage travel guide for a city
local_events	Events during trip dates
search_ground	Buses, trains and ferries (22 providers)
search_airport_transfers	Airport-to-hotel ground transport + taxi estimates
search_cars	Rental car search (Skyscanner, opt-in)
search_restaurants	Restaurants near a location
search_deals	Travel deals from 4 RSS feeds
plan_trip	Complete trip: flights + hotel in one parallel search
search_route	Multi-modal routing combining flights, trains, buses and ferries
get_weather	Weather forecast (Open-Meteo, up to 14 days)
get_preferences	Read user travel preferences
detect_travel_hacks	Run 36 parallel detectors for savings
detect_accommodation_hacks	Hotel split savings
search_natural	Natural language search dispatching to the right tool
find_trip_window	Optimal travel windows intersecting price calendars with busy intervals
list_trips	List saved trips
get_trip	Get trip details
create_trip	Create a new trip record
add_trip_leg	Add a leg to a saved trip
mark_trip_booked	Mark a trip leg as booked
get_baggage_rules	Airline baggage allowances

v1.21 hotel evidence

Hotel seller rows preserve cancellation terms, explicit refundability, and the upstream official property-site flag when a source supplies them. Missing data remains unknown. It is not guessed, and it does not silently change price ordering.

hotel_prices can declare a source-level caution ceiling when its feed lacks seller cancellation terms. Room-level paths such as hotel_rooms can return ready when exact room identity, a durable seller URL, and explicit refundability are present.