TicketLens Experiences MCP

Servidor MCP remoto hospedado para experiências de destino com endpoint público e resolução de POI.

Documentação

TicketLens Experiences MCP

Servidor MCP remoto oficial e API REST para descobrir tours, ingressos, atrações e atividades com o TicketLens.

O TicketLens oferece um servidor MCP remoto hospedado público em https://mcp.ticketlens.com/ e uma API REST versionada em https://api.ticketlens.com/v1 para planejadores de viagem com IA, fluxos de descoberta de destinos e integrações personalizadas. O mesmo inventário hospedado cobre tours guiados, ingressos de atrações, ônibus hop-on hop-off, ingressos esportivos e outros ingressos de eventos.

Site principal: www.ticketlens.com/en

O que é o TicketLens

A superfície MCP + REST remota oficial do TicketLens para experiências de destino.
Uma superfície de busca voltada a desenvolvedores para experiências de destino.
Disponível como MCP e REST no mesmo inventário hospedado.
Projetado para assistentes de IA, ferramentas de planejamento de viagem, fluxos de descoberta de destinos e integrações personalizadas.

Por que se encaixa em agentes de IA

Servidor MCP remoto hospedado com URL pública para configuração e avaliação rápidas do conector.
Fallback REST público no mesmo inventário para clientes que ainda não usam MCP.
Ampla cobertura de experiências de destino em tours, ingressos de atrações, ônibus hop-on hop-off, esportes e eventos.

O que a API/MCP atual retorna

As ferramentas e endpoints públicos chamados tour retornam um catálogo mais amplo de experiências de destino, não apenas tours guiados.

search_tours e POST /v1/search/tours podem retornar:

tours guiados
ingressos de atrações e museus
produtos de ônibus hop-on hop-off
ingressos esportivos
produtos de eventos e admissão

Ferramentas MCP públicas atuais:

search_tours
search_pois
get_tour
health_check
submit_feedback

Endpoints REST públicos atuais:

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

Guia rápido do MCP hospedado

URLs do MCP hospedado:

URL base: https://mcp.ticketlens.com/
Cartão de servidor canônico: https://mcp.ticketlens.com/.well-known/mcp/server-card.json
Alias de compatibilidade: https://mcp.ticketlens.com/.well-known/mcp.json

Codex

Adicione o servidor hospedado pela CLI:

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

Se você gerencia servidores MCP do Codex por meio de arquivos de configuração, comece por examples/mcp/codex-config.toml.

Cursor

Adicione a URL do MCP hospedado à configuração MCP do Cursor. Um exemplo pronto para copiar está em examples/mcp/cursor-mcp.json.

Claude

Os conectores MCP remotos do Claude são adicionados pela interface, não por meio de claude_desktop_config.json. Use a URL hospedada https://mcp.ticketlens.com/ em Settings > Connectors, ou siga o guia rápido em examples/mcp/claude-connector.md.

OpenClaw

Usuários do OpenClaw podem integrar o TicketLens rapidamente adicionando uma skill de workspace que chama a API REST pública do TicketLens. Comece por examples/openclaw/skills/ticketlens-api/SKILL.md.

Consulte examples/openclaw/README.md para o caminho de API recomendado e observações sobre a rota MCP mais avançada.

Guia rápido da API hospedada

URLs da API hospedada:

URL base: https://api.ticketlens.com/v1
JSON OpenAPI: https://api.ticketlens.com/v1/openapi.json
Swagger UI: https://api.ticketlens.com/v1/docs
ReDoc: https://api.ticketlens.com/v1/redoc
Artefato versionado: openapi/ticketlens-tour-search-api.v1.json

Os exemplos hospedados abaixo usam os endpoints HTTPS públicos diretamente e não exigem cabeçalhos extras na configuração pública atual.

Etapa 1: resolver a Torre Eiffel para um POI canônico do TicketLens:

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

Etapa 2: buscar ingressos para a Torre Eiffel usando o POI da etapa 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
  }'

Para fluxos de emissão de ingressos específicos de destinos, como a Torre Eiffel, isso é útil para agentes porque o TicketLens pode exibir inventário do site oficial da Torre Eiffel, incluindo disponibilidade difícil de encontrar em alta temporada quando existir, junto com opções de ingressos no mercado secundário no mesmo fluxo de busca.

Para filtrar por datas de viagem, adicione um objeto dates com valores ISO YYYY-MM-DD:

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
  }'

Observações sobre filtragem por data:

Use dates.from_date para uma busca de um único dia.
Use ambos dates.from_date e dates.to_date para um intervalo de datas.
As datas devem usar ISO YYYY-MM-DD.
dates.flexible_days existe no schema, mas não está implementado na versão pública atual.

Referência das ferramentas MCP

Ferramenta	O que faz
`search_tours`	Busca experiências de destino entre tours, ingressos de atrações, ônibus hop-on hop-off, ingressos esportivos, ingressos de eventos e outras atividades.
`search_pois`	Resolve POIs e aliases antes de chamar `search_tours`.
`get_tour`	Obtém detalhes de uma experiência retornada por `search_tours`.
`health_check`	Retorna um instantâneo passivo de saúde do serviço.
`submit_feedback`	Compartilha feedback MCP estruturado quando o comportamento está quebrado, pouco claro, com capacidades ausentes ou com oportunidades de melhoria.

Feedback do MCP

submit_feedback está disponível apenas no servidor MCP hospedado. Não faz parte da API REST pública nem do documento OpenAPI.

Use submit_feedback quando um agente encontrar:

comportamento quebrado
resultados confusos ou incompletos
capacidades ausentes
lacunas na documentação
melhorias claras de produto ou ferramenta

Campos suportados:

obrigatórios: category, message
opcionais: suggestion, related_tool_name, related_request_id, expected_behavior, actual_behavior, reproduction_summary

Categorias suportadas:

bug_report
improvement
missing_capability
documentation_gap
other

Exemplo de sugestão de melhoria:

{
  "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."
}

Exemplo de relatório de lacuna na documentação:

{
  "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."
}

Exemplo de payload de relatório de bug:

{
  "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."
}

Referência dos endpoints da API

Método	Caminho	Propósito
`POST`	`/v1/search/tours`	Busca experiências de destino, incluindo tours, ingressos de atrações, ônibus hop-on hop-off, ingressos esportivos, ingressos de eventos e outras atividades.
`GET`	`/v1/tours/{tour_id}`	Obtém detalhes de uma experiência retornada por `/v1/search/tours`.
`POST`	`/v1/search/pois`	Resolve pontos de interesse antes de filtrar a busca.
`GET`	`/v1/pois/{poi_id}`	Obtém um registro de POI canônico por ID.
`GET`	`/v1/livez`	Processa verificação de liveness.
`GET`	`/v1/readyz`	Verificação local de prontidão para configuração e inicialização de serviço.
`GET`	`/v1/health`	Saúde diagnóstica mais rica voltada a humanos, usando atividade recente do backend de busca.

Exemplos por tipo de experiência

Exemplos curl prontos para execução:

Descoberta de ingressos da Torre Eiffel
Descoberta de ônibus hop-on hop-off
Descoberta de ingressos de futebol
Descoberta de tour guiado clássico
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

Exemplos gerais de clientes de API:

FAQ

Por que o endpoint se chama tours se também retorna ingressos?

As ferramentas e endpoints públicos chamados tour cobrem experiências de destino de forma mais ampla, então search_tours e POST /v1/search/tours podem retornar tours guiados, ingressos de atrações, ônibus hop-on hop-off, ingressos esportivos, ingressos de eventos e outras atividades reserváveis.

Acesso, limites e suporte

O MCP e a API hospedados são públicos e destinados à avaliação e integração por desenvolvedores.
Limites de uso justo e proteção contra abuso podem ser aplicados.
Clientes MCP podem usar submit_feedback para problemas de runtime, comportamento confuso, capacidades ausentes e sugestões de melhoria.
Abra uma issue no GitHub para exemplos quebrados, documentação desatualizada ou lacunas de integração.

Manutenção

Este repositório é um espelho público curado da documentação, exemplos e artefatos de API exportados. O código-fonte de runtime permanece interno e os artefatos voltados ao público são atualizados a partir da fonte privada da verdade.