MCP Tool Contract - Viator Experiences

This document defines the behavior, field requirements, invocation rules, and expected specifications for the Viator search_experiences and get_experience_details MCP tools. These instructions guide the model on when and how to use each tool, what inputs are required, and how to manage ambiguity.

Table of Contents

• Access
• Base URL & Setup
• Tools
  • search_experiences
  • get_experience_details
• Error & Ambiguity Handling
• Rate Limiting
• End-to-end example

Access

To use the MCP server, your client IP address must be added to an IP whitelist - no API keys or tokens are required. Once your IP address is whitelisted, all requests from that IP are accepted without further authentication.

To request access, reach out to the Viator Experiences team via partnerapi@tripadvisor.com with your client IP address. Requests are typically processed within one business day.

If you receive a 403 Forbidden response, your IP has not yet been whitelisted or the request is coming from an unexpected address.

Base URL & Setup

The MCP server is available at:

https://exp-app-mcp.prod.ep.viator.com/mcp

Configure this as the server URL in your MCP client. Once your IP is whitelisted, no additional setup is required.

Tools

search_experiences

Retrieves a curated list of Viator experiences based on required trip context and travel dates.

Supports both low-intent ("things to do in London this weekend") and high-intent ("kid-friendly cooking classes in Rome in July") queries.

The model may re-issue refined search calls when the user adds additional criteria.

When to Use

Invoke this tool whenever the user is asking for activities, experiences, or things to do in a destination and enough context is available or can be clarified.

Examples that should invoke the tool:

• "What should I do in Barcelona in May?"
• "Find kid-friendly tours in Rome."
• "Show me things to do in London for under $50 this weekend."

When NOT to Use

Do NOT invoke the tool when the user:

• Asks about logistics (visas, weather, transportation),
• Requests hotel, restaurant, or flight recommendations,
• Asks about Viator booking support (refunds, cancellations),
• Refers to a landmark (Eiffel Tower) instead of a destination (Paris).

The model should ask clarifying questions when query or dates are missing or ambiguous.

Required Behavior Rules

• Pass the user's full query string as-is in searchTerm: destination, category, and preferences can all be expressed there.
• startDate and endDate must be ISO-8601. Convert natural language ("next weekend", "early April") to concrete dates before calling.
• limit should never be used to interpret user intent. It affects output volume, not query meaning.

Request Fields

Request example

{
  "searchTerm": "kid-friendly things to do in Paris",
  "startDate": "2025-06-01",
  "endDate": "2025-06-07",
  "limit": 5,
  "sessionId": "550e8400-e29b-41d4-a716-446655440000"
}

Response Fields

The tool returns a JSON object with:

Response example

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "experiences": [
    {
      "title": "Example Walking Tour",
      "code": "12345P7",
      "thumbnail": "https://example.com/image.jpg",
      "rating": 4.8,
      "reviewCount": 1200,
      "freeCancellation": true,
      "fromPrice": 49.0,
      "fromPriceBeforeDiscount": 59.0,
      "clickOffToLander": "https://example.com/lander",
      "duration": {
        "fixedDurationInMinutes": 120,
        "variableDurationFromMinutes": null,
        "variableDurationToMinutes": null
      },
      "keyAttributes": {
        "features": ["KID_FRIENDLY"],
        "mainCategory": "Walking Tours"
      }
    }
  ]
}

get_experience_details

Retrieves enriched details for a specific Viator product, including description, highlights, images, inclusions/exclusions, insider tips, pricing, and booking URL.

Used when the user selects a product or explicitly asks for more information about one previously shown.

When to Use

Invoke this tool when the user:

• Clicks "See more" (or equivalent) in UI
• Says "Tell me more about..." or similar
• Explicitly asks for details on a previously shown experience

If the user's reference is ambiguous (e.g. "the museum tour" after showing several), ask which one they mean before calling.

When NOT to Use

• Discovering new products - use search_experiences for that
• Any product not previously returned by a search. code must come from previous search results. Never invent or guess IDs.

Request Fields

Request example

{
  "code": "12345P7",
  "locale": "en-US",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000"
}

Response Fields

The tool returns a JSON object with:

Response example

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "experienceDetails": {
    "code": "12345P7",
    "title": "Example Walking Tour",
    "description": "Explore the city with a local expert guide.",
    "insiderTips": "Wear comfortable shoes.",
    "thumbnail": "https://example.com/image.jpg",
    "rating": 4.8,
    "reviewCount": 1200,
    "freeCancellation": true,
    "clickOffToPDP": "https://example.com/pdp"
  }
}

Error & Ambiguity Handling

Error Handling Rules

• Most errors will be shown as regular MCP errors (inside of a HTTP 200 response), with the standard "isError: true" and the text field being the human readable error message for which the MCP Client must react appropriately
• The only exceptions are the 403 Forbidden responses if your IP address is not whitelisted.

Empty results behaviour

If the tool returns zero results, the model must proactively guide the user toward a successful refinement. It should review the parameters used in the failed request and recommend the most appropriate based on the proposed logic below:

• If the query requests a specific feature (eg private tour), suggest removing this constraint. Eg: "Private tours may be limited in this area, would you like to consider group options too?"
• If duration provided, suggest trying a shorter or longer duration.
• If price constraint was applied, suggest widening (or removing) price limits.
• Else, suggest a broader location search. Eg: "Nothing matches central Siena, should we try Tuscany or nearby towns?"

Rate Limiting

The API enforces rate limits to ensure reliable service across all consumers. Limits are generous and designed to accommodate standard conversational usage patterns, most integrations won't need to think about this at all.

If you do hit a limit, the server responds with the error message “Rate limit exceeded. Please retry after X seconds." Exponential backoff is also a safe default strategy.

If your use case involves unusually high call volumes, please reach out to the team before going live.

End-to-end example

Here's a complete flow from a user message through to a detail request:

User: "Find me kid-friendly things to do in Paris next weekend."

Step 1: Model resolves the date (assuming today is 2025-05-28): "next weekend" = startDate: 2025-06-07, endDate: 2025-06-08.

Step 2: Call search_experiences

{
  "searchTerm": "kid-friendly things to do in Paris next weekend",
  "startDate": "2025-06-07",
  "endDate": "2025-06-08",
  "limit": 5
}

Step 3: Server returns results including (among others):

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "experiences": [
    {
      "title": "Paris Catacombs Skip-the-Line Tour for Families",
      "code": "12345P7",
      "rating": 4.8,
      "reviewCount": 1200,
      "freeCancellation": true,
      "fromPrice": 49.0,
      "clickOffToLander": "https://viator.com/..."
    }
  ]
}

User: "Tell me more about the Catacombs tour."

Step 4: Call get_experience_details

{
  "code": "12345P7",
  "locale": "en-US",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000"
}

Step 5: Server returns enriched product detail, which the model uses to present highlights, inclusions, pricing, and a booking link to the user.