TicketLens Experiences

TicketLens Experiences MCP

Official remote MCP server and REST API for discovering tours, tickets, attractions, and activities with TicketLens.

TicketLens provides a public hosted remote MCP server at https://mcp.ticketlens.com/ and a versioned REST API at https://api.ticketlens.com/v1 for AI travel planners, destination discovery flows, and custom integrations. The same hosted inventory covers guided tours, attraction tickets, hop-on hop-off buses, sports tickets, and other event tickets.

Main website: www.ticketlens.com/en

What TicketLens is

• The official TicketLens remote MCP + REST surface for destination experiences.
• A developer-facing search surface for destination experiences.
• Available as both MCP and REST on the same hosted inventory.
• Designed for AI assistants, travel planning tools, destination discovery flows, and custom integrations.

Why it fits AI agents

• Hosted remote MCP server with a public URL for quick connector setup and evaluation.
• Public REST fallback on the same inventory for clients that are not using MCP yet.
• Broad destination-experiences coverage across tours, attraction tickets, hop-on hop-off buses, sports tickets, and events.

What the current API/MCP returns

The public tour-named tools and endpoints return a broader destination-experiences catalog, not just guided tours.

search_tours and POST /v1/search/tours can return:

• guided tours
• attraction and museum tickets
• hop-on hop-off bus products
• sports tickets
• event and admission products

Current public MCP tools (contract 2.2.0):

• search_experiences — preferred search tool for new integrations
• get_poi
• search_tours
• search_pois
• get_tour
• health_check
• submit_feedback

Read the ticketlens://capabilities MCP resource for the current contract version, supported filters, limits, and examples. tools/list publishes tool input schemas and available output schemas. Existing tools remain available; search_tours is a compatibility adapter with no scheduled removal date.

Current public REST endpoints:

• POST /v1/search/tours
• GET /v1/tours/{tour_id}
• POST /v1/search/pois
• GET /v1/pois/{poi_id}
• GET /v1/livez
• GET /v1/readyz
• GET /v1/health
• GET /v1/openapi.json
• GET /v1/docs
• GET /v1/redoc

Hosted MCP quickstart

Hosted MCP URLs:

• Base URL: https://mcp.ticketlens.com/
• Canonical server card: https://mcp.ticketlens.com/.well-known/mcp/server-card.json
• Compatibility alias: https://mcp.ticketlens.com/.well-known/mcp.json

First MCP search

After connecting with an MCP client, inspect tools/list, read ticketlens://capabilities with resources/read, and use search_experiences for new searches. Search, POI, detail, and feedback inputs belong inside arguments.payload; health_check takes no arguments.

This object is the params value for an MCP tools/call request:

{
  "name": "search_experiences",
  "arguments": {
    "payload": {
      "query": "museum tickets",
      "destination": {"city": "Paris", "country": "France"},
      "language": "en",
      "currency": "EUR",
      "page_size": 5
    }
  }
}

Handle the returned status: ok, needs_disambiguation, no_results, or error. For ambiguous places, use the selected candidate's supplied retry. For a result with selection_ref, pass it unchanged with that result's id to get_tour to retrieve the same selected price and date context.

Price and rating sorting apply within each returned page. Counts describe matching catalog records, so they are not a count of unique experiences across the entire search. Availability and prices must still be confirmed when booking.

See the MCP contract guide for filters, price selection, pagination recovery, error handling, and compatibility. Copyable tools/call parameter examples:

• Search experiences
• Look up a POI

Codex

Add the hosted server from the CLI:

codex mcp add ticketlens-experiences --url https://mcp.ticketlens.com/

If you manage Codex MCP servers through config files, start from examples/mcp/codex-config.toml.

Cursor

Add the hosted MCP URL to your Cursor MCP config. A ready-to-copy example is in examples/mcp/cursor-mcp.json.

Claude

Claude remote MCP connectors are added from the UI, not through claude_desktop_config.json. Use the hosted URL https://mcp.ticketlens.com/ in Settings > Connectors, or follow the short guide in examples/mcp/claude-connector.md.

OpenClaw

OpenClaw users can integrate TicketLens quickly by adding a workspace skill that calls the public TicketLens REST API. Start from examples/openclaw/skills/ticketlens-api/SKILL.md.

See examples/openclaw/README.md for the recommended API path and notes about the more advanced MCP route.

Hosted API quickstart

Hosted API URLs:

• Base URL: https://api.ticketlens.com/v1
• OpenAPI JSON: https://api.ticketlens.com/v1/openapi.json
• Swagger UI: https://api.ticketlens.com/v1/docs
• ReDoc: https://api.ticketlens.com/v1/redoc
• Committed artifact: openapi/ticketlens-tour-search-api.v1.json

The hosted examples below use the public HTTPS endpoints directly and do not require extra headers in the current public setup.

Step 1: resolve the Eiffel Tower to a canonical TicketLens POI:

curl -sS https://api.ticketlens.com/v1/search/pois \
  -H 'content-type: application/json' \
  -d '{
    "query": "Eiffel Tower",
    "city": "Paris",
    "language": "en",
    "limit": 5
  }'

Step 2: search for Eiffel Tower tickets using the POI from step 1:

curl -sS https://api.ticketlens.com/v1/search/tours \
  -H 'content-type: application/json' \
  -d '{
    "query": "ticket",
    "poi": {
      "id": "660851",
      "match_mode": "exact"
    },
    "city": "Paris",
    "languages": ["en"],
    "per_page": 5
  }'

For destination-specific ticketing flows like the Eiffel Tower, this is useful for agents because TicketLens can surface inventory from the official Eiffel Tower site, including hard-to-find high-season availability when it exists, alongside second-market ticket options in the same search flow.

To filter for travel dates, add a dates object with ISO YYYY-MM-DD values:

curl -sS https://api.ticketlens.com/v1/search/tours \
  -H 'content-type: application/json' \
  -d '{
    "query": "ticket",
    "poi": {
      "id": "660851",
      "match_mode": "exact"
    },
    "city": "Paris",
    "dates": {
      "from_date": "2026-05-15",
      "to_date": "2026-05-17"
    },
    "languages": ["en"],
    "per_page": 5
  }'

Date filtering notes:

• Use dates.from_date for a single-day search.
• Use both dates.from_date and dates.to_date for a date range.
• Dates must use ISO YYYY-MM-DD.
• dates.flexible_days exists in the schema but is not implemented in the current public version.

MCP tool reference

Tool	What it does
search_experiences	Preferred typed search with effective filters, compact results, place disambiguation, and recovery suggestions.
get_poi	Fetch a canonical POI by poi_id and content language.
search_tours	Compatibility search for existing integrations, with its existing request and response shape.
search_pois	Resolve landmark names and aliases to POI IDs.
get_tour	Fetch experience detail by tour_id; pass a search result's selection_ref to preserve its selected price and dates.
health_check	Return a passive service health snapshot.
submit_feedback	Share structured MCP feedback when behavior is broken, unclear, missing capabilities, or worth improving.

The ticketlens://capabilities resource describes the MCP contract. MCP tool names and fields are separate from REST endpoints and their OpenAPI document.

MCP feedback

submit_feedback is available on the hosted MCP server only. It is not part of the public REST API or the OpenAPI document.

Use submit_feedback when an agent encounters:

• broken behavior
• confusing or incomplete results
• missing capabilities
• documentation gaps
• clear product or tool improvements

Supported fields:

• required: category, message
• optional: suggestion, related_tool_name, related_request_id, expected_behavior, actual_behavior, reproduction_summary

Supported categories:

• bug_report
• improvement
• missing_capability
• documentation_gap
• other

The examples below are payload objects. Invoke them with {"name":"submit_feedback","arguments":{"payload":{...}}} as the tools/call parameters.

Example improvement suggestion:

{
  "category": "improvement",
  "message": "Add clearer filter explanations when date constraints remove all results.",
  "related_tool_name": "search_tours",
  "suggestion": "Return a short hint explaining which filter removed the result set."
}

Example documentation-gap report:

{
  "category": "documentation_gap",
  "message": "The MCP docs should explain when search_pois is recommended before search_tours.",
  "related_tool_name": "search_pois",
  "suggestion": "Add a short POI-first workflow example to the MCP quickstart."
}

Example bug report payload:

{
  "category": "bug_report",
  "message": "The tool rejected a valid POI filter after resolving the POI successfully.",
  "related_tool_name": "search_tours",
  "related_request_id": "req-123",
  "expected_behavior": "The search should accept the resolved POI and return matching experiences.",
  "actual_behavior": "The tool returned an invalid argument error.",
  "reproduction_summary": "Resolve a POI with search_pois, then pass the returned POI id into search_tours."
}

API endpoint reference

Method	Path	Purpose
POST	/v1/search/tours	Search destination experiences, including tours, attraction tickets, hop-on hop-off buses, sports tickets, event tickets, and other activities.
GET	/v1/tours/{tour_id}	Fetch detail for an experience returned by /v1/search/tours.
POST	/v1/search/pois	Resolve points of interest before filtering search.
GET	/v1/pois/{poi_id}	Fetch a canonical POI record by ID.
GET	/v1/livez	Process liveness check.
GET	/v1/readyz	Local readiness check for required configuration and service initialization.
GET	/v1/health	Richer human-facing diagnostic health using recent search backend activity.

Examples by experience type

Ready-to-run curl examples:

• Eiffel Tower ticket discovery

• hop-on hop-off bus discovery

• football ticket discovery

• classic guided tour discovery

• examples/api/curl/eiffel-tower-ticket-search.sh

• examples/api/curl/hop-on-hop-off-search.sh

• examples/api/curl/football-ticket-search.sh

• examples/api/curl/guided-tour-search.sh

• examples/api/curl/poi-search.sh

General API client examples:

• examples/api/javascript/search_experiences.mjs
• examples/api/python/search_experiences.py

FAQ

Why is the endpoint called tours if it returns tickets too?

The public tour-named tools and endpoints cover destination experiences more broadly, so search_tours and POST /v1/search/tours can return guided tours, attraction tickets, hop-on hop-off buses, sports tickets, event tickets, and other bookable activities.

Access, limits, and support

• The hosted MCP and API are public and intended for developer evaluation and integration.
• Fair-use and abuse-protection limits may apply.
• MCP clients must inspect tool errors even when the HTTP response is 200. Respect returned retry timing; a non-retryable service configuration error requires operator action. See error handling and usage limits.
• MCP clients can use submit_feedback for runtime issues, confusing behavior, missing capabilities, and improvement suggestions.
• Open a GitHub issue for broken examples, stale docs, or integration gaps.

Maintenance

This repository is a curated public mirror of documentation, examples, and exported API artifacts. Runtime source remains internal and public-facing artifacts are refreshed from the private source of truth.