v0.25.0 · 61 tools · Stdio + SSE

PriceTik MCP
One server. Three surfaces. Every LLM.

Drop into Claude, ChatGPT, Cursor, or any MCP-compatible host and your agent can answer real-time price questions across shopping, hotels, and events.

$npx @pricetik/mcp-server

Get installed in 60 seconds Try the live API

Free for every agent · No card required · Stdio + SSE transports

Drops into your favorite agent

ClaudeChatGPTCursorWindsurfClineContinue+ any MCP-compatible host

Shopping17 tools

Real-time retail prices

Price checks, deal scores, ML predictions, and demand signals across 25,000+ merchants.

Sub-second price lookups
30-day rate history & deal scoring
Watch alerts when prices drop

Pricing

Free for every agent

Auth

No API key required

Hotels16 tools

Search, compare, book

250K+ properties via Hotelbeds. Rich content, rate history, signed checkout URLs.

Hotelbeds inventory, one schema
Rate history & deal scores
Direct booking with API key on file

Pricing

Free for every agent

Auth

API key unlocks direct booking

Events7 tools

Tours, attractions & excursions

Bookable activities in 200+ destinations via Hotelbeds. USD pricing, deterministic deal scores.

200+ destinations worldwide
Filter by duration, language, cancellation
Side-by-side compare (2–4 codes) + watch-rate alerts

Pricing

Free for every agent

Auth

API key unlocks direct booking

One-Click Install

Skip the manual config. Install PriceTik MCP in your IDE with a single click, then paste your API key.

Install in Cursor Claude Code

Or follow the manual setup below for any MCP-compatible host

Or set up manually

Manual setup

Three steps. Sixty seconds.

Works with every MCP-compatible host. Pick yours below.

Get your API key

Create a PriceTik account and generate an API key from your dashboard.

Create account Sign in

API Key Format: ptk_live_xxxxxxxxxxxxx

Free for every agent. Optional — the MCP server works without a key, but authenticated keys unlock direct hotel & event booking on file.

Configure your AI tool

Pick your host and copy the config below. Replace YOUR_API_KEY with your actual key.

Location: ~/.cursor/mcp.json

mcp.json

{
  "mcpServers": {
    "pricetik": {
      "type": "http",
      "url": "https://mcp.pricetik.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Important: Replace YOUR_API_KEY with your actual key (e.g. ptk_live_xxx...).

Security: Your API key travels in the Authorization header over HTTPS. Never commit keys to source control.

Restart & verify

Restart your AI tool to apply the configuration, then verify the connection.

Restart your host

Quit and reopen Cursor / Claude Desktop / Windsurf. CLI tools (Codex, Claude Code) reload on next invocation.

Send a test prompt

“Use PriceTik to check the price of Sony WH-1000XM5.”

If the agent calls pricetik_price_checkand returns a price, you're live. If not, see troubleshooting.

Get started

Try the live API

Switch between Shopping, Hotels, and Tickets and hit the live API. All surfaces work without a key.

Live API Playground

No API key needed — free for every agent

Code-first

SDK quickstarts

Most agent runtimes speak MCP natively. The snippets below cover the three paths developers ask for most: TypeScript with the official MCP SDK, Python with the Anthropic SDK, and a curl-only fallback for non-MCP languages.

TypeScript · @modelcontextprotocol/sdk

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@pricetik/mcp-server'],
});

const client = new Client(
  { name: 'my-agent', version: '1.0.0' },
  { capabilities: { tools: {} } },
);
await client.connect(transport);

const { tools } = await client.listTools();
const result = await client.callTool({
  name: 'pricetik_hotel_search',
  arguments: {
    destination: 'Las Vegas',
    checkIn: '2026-08-15',
    checkOut: '2026-08-17',
    excludeResortFees: true,
  },
});
console.log(result.content);

Python · anthropic

python

# pip install anthropic mcp
from anthropic import Anthropic
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="npx",
    args=["-y", "@pricetik/mcp-server"],
)

async def main():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = (await session.list_tools()).tools
            result = await session.call_tool(
                "pricetik_compare_destinations",
                arguments={
                    "destinations": "Cabo,Tulum",
                    "checkIn": "2026-09-12",
                    "checkOut": "2026-09-15",
                    "guests": 2,
                },
            )
            print(result.content)

Or just curl — no MCP runtime required

bash

# Same API, no MCP runtime needed.
curl 'https://api.pricetik.com/api/v1/intel/hotel-flex-dates?destination=Lisbon&windowStart=2026-06-01&windowEnd=2026-06-30&nights=3&limit=5'

# Idempotent retries on booking-creating endpoints
curl -H 'Idempotency-Key: trip_2026_06_lisbon_v1' \
  'https://api.pricetik.com/api/v1/intel/hotel-booking-url?rateKey=...&providerPropertyId=...&checkIn=2026-06-12&checkOut=2026-06-15&guests=2&rooms=1'

OpenAPI 3.0

openapi.json

Generate SDKs in any language — Go, Java, Rust, Ruby, .NET. Validates clean against swagger-cli.

Discovery

/.well-known/mcp.json

PulseMCP-shaped discovery manifest. Registry crawlers find the server here.

LLM-readable

/llms.txt

Flat-text manifest per llmstxt.org. Crawling agents and discovery bots read this first.

Shopping

Shopping MCP

Real-time pricing, deal scoring, and demand intelligence across 25,000+ retailers. Free for every agent — no API key, no daily quota.

Shopping Tools

17 MCP tools backed by the /api/v1/intel/* REST surface. All retailer URLs come back as pricetik.com/go/{click_id} redirects — pass them to the browser unchanged.

Core

pricetik_price_checkFree

Check current prices across all tracked retailers.

Params: url OR productId

▸Example response

{
  "product": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Sony WH-1000XM5",
    "brand": "Sony"
  },
  "currentPrice": 278.00,
  "currency": "USD",
  "retailers": [
    { "name": "amazon",   "price": 278.00, "inStock": true,
      "url": "https://pricetik.com/go/ck_a1b2c3" },
    { "name": "bestbuy",  "price": 299.99, "inStock": true,
      "url": "https://pricetik.com/go/ck_d4e5f6" }
  ],
  "meta": { "cached": false, "requestId": "req-abc123" }
}

pricetik_should_buyFree

Buy/wait recommendation with confidence score.

Params: url OR productId, maxPrice?, urgency?

▸Example response

{
  "recommendation": "wait",
  "confidence": 0.74,
  "reasoning": "Price has dropped 8% in the last 30 days and historical lows are typically reached during October sales events.",
  "currentPrice": 278.00,
  "predictedPriceIn30Days": 249.00,
  "expectedSavings": 29.00,
  "currency": "USD"
}

pricetik_price_historyFree

Historical price data with trends, highs, lows.

Params: productId (required), days?, granularity?

▸Example response

{
  "productId": "550e8400-e29b-41d4-a716-446655440000",
  "days": 90,
  "granularity": "daily",
  "currentPrices": [
    { "retailer": "amazon", "price": 278.00, "inStock": true },
    { "retailer": "bestbuy", "price": 299.99, "inStock": true }
  ],
  "allTimeLow": {
    "price": 248.00,
    "retailer": "amazon",
    "date": "2026-03-22",
    "saleEvent": "Spring Sale"
  },
  "allTimeHigh": { "price": 399.99, "retailer": "bestbuy", "date": "2026-01-08" },
  "average90d": 287.42,
  "trend": "declining",
  "trendSlope": -0.42,
  "volatility": "low",
  "dataPointCount": 540,
  "pricePoints": [
    { "date": "2026-05-26", "retailer": "amazon", "price": 278.00 }
  ]
}

pricetik_deal_scoreFree

0–100 composite deal score based on history, demand, timing.

Params: url OR productId

▸Example response

{
  "score": 78,
  "tier": "good",
  "components": {
    "priceVsHistory": 84,
    "priceVsRetailers": 72,
    "demand": 65,
    "timing": 81
  },
  "reasoning": "Within 5% of 90-day low. 12% below median across tracked retailers.",
  "currentPrice": 278.00
}

pricetik_searchFree

Cross-vertical search. Default surface=shopping returns retail product matches. surface=hotels returns hotels matching the query, surface=events returns Hotelbeds activity destinations, surface=all fans out and merges round-robin. Each result carries a drillDownTool field telling the agent which tool to call next.

Params: q (required), surface?, category?, maxPrice?, limit?

▸Example response

{
  "query": "sony headphones",
  "surface": "all",
  "totalMatches": 12,
  "results": [
    { "surface": "shopping", "id": "550e8400-...", "name": "Sony WH-1000XM5",
      "drillDownTool": "pricetik_price_check" },
    { "surface": "hotel", "id": "660f9511-...", "name": "Sony Hilton Tokyo",
      "location": "Tokyo, Japan",
      "drillDownTool": "pricetik_hotel_details" }
  ],
  "meta": { "hotelMatches": 1, "eventMatches": 0, "shoppingMatches": 11 }
}

pricetik_compareFree

Side-by-side comparison of two products — prices, deal scores, history, and demand.

Params: productIds (required, array of 2 UUIDs)

▸Example response

{
  "products": [
    { "id": "550e8400-...", "name": "Sony WH-1000XM5",
      "currentPrice": 278.00, "dealScore": 78,
      "trend90d": "declining", "demandZone": "demand_zone" },
    { "id": "660f9511-...", "name": "Bose QuietComfort Ultra",
      "currentPrice": 379.00, "dealScore": 64,
      "trend90d": "stable", "demandZone": "none" }
  ],
  "winner": { "productId": "550e8400-...", "reasoning": "Higher deal score and stronger downward trend." }
}

pricetik_batch_price_checkFree

Check prices for multiple products in a single call. Up to 10 per request.

Params: productIds (required, array of UUIDs)

▸Example response

{
  "results": [
    { "productId": "550e8400-...", "currentPrice": 278.00, "currency": "USD",
      "lowestRetailer": "amazon", "inStock": true },
    { "productId": "660f9511-...", "currentPrice": 379.00, "currency": "USD",
      "lowestRetailer": "bestbuy", "inStock": true },
    { "productId": "770aa622-...", "error": "ProductNotFound" }
  ],
  "meta": { "totalRequested": 3, "successful": 2, "failed": 1 }
}

Intelligence

pricetik_demandFree

Consumer demand signals — bid counts, gravity scores, demand zones, price distribution. Pro+ tier. Pass `targetType: "hotel"` with productId + checkIn + checkOut for hotel demand, or `targetType: "activity"` with activityCode + travelDate for activity demand (Tier 5 #3 — backed by `intel_activity_demand_signals` rolled up every 15 minutes).

Params: productId (product/hotel) OR activityCode (activity), targetType?, checkIn?, checkOut?, travelDate?

▸Example response

{
  "productId": "550e8400-...",
  "demandZone": "demand_zone",
  "openBids": 23,
  "topBidPrice": 249.00,
  "medianBidPrice": 230.00,
  "currency": "USD",
  "gravityScore": 0.62,
  "windowHours": 24,
  "syntheticDemand": { "uniqueQueries24h": 412, "trend": "rising" }
}

pricetik_predictFree

ML probability estimates for hitting a target price within 30/60/90 days.

Params: productId (required), targetPrice (required)

▸Example response

{
  "productId": "550e8400-...",
  "currentPrice": 278.00,
  "targetPrice": 249.00,
  "currency": "USD",
  "predictions": [
    { "windowDays": 30, "probability": 0.62, "confidence": "medium" },
    { "windowDays": 60, "probability": 0.81, "confidence": "high" },
    { "windowDays": 90, "probability": 0.92, "confidence": "high" }
  ],
  "modelVersion": "ml-fill-prob-v3"
}

Alerts

pricetik_alert_createFree

Create a webhook alert for price conditions.

Params: productId, conditions[], webhookUrl

▸Example response

{
  "alert": {
    "id": "8a7b6c5d-1234-4abc-9def-0123456789ab",
    "targetType": "product",
    "productId": "550e8400-...",
    "conditions": [
      { "type": "price_below", "value": 249.00 },
      { "type": "deal_score_above", "value": 80 }
    ],
    "webhookUrl": "https://example.com/hooks/pricetik",
    "isActive": true,
    "createdAt": "2026-05-27T17:32:00Z",
    "expiresAt": null
  }
}

pricetik_alert_listFree

List active webhook alerts (covers both retail + hotel alerts).

Params: page?, limit?

▸Example response

{
  "page": 1,
  "perPage": 20,
  "total": 4,
  "alerts": [
    { "id": "8a7b6c5d-...", "targetType": "product",
      "webhookUrl": "https://example.com/***",
      "conditions": [{ "type": "price_below", "value": 249.00 }],
      "isActive": true, "consecutiveFailures": 0,
      "createdAt": "2026-05-27T17:32:00Z", "lastTriggeredAt": null }
  ]
}

pricetik_alert_updateFree

Update conditions or webhook URL on an existing alert.

Params: alertId (required), conditions?, webhookUrl?

▸Example response

{
  "alert": {
    "id": "8a7b6c5d-...",
    "conditions": [{ "type": "price_below", "value": 239.00 }],
    "webhookUrl": "https://example.com/hooks/pricetik",
    "isActive": true,
    "updatedAt": "2026-05-27T17:45:00Z"
  }
}

pricetik_alert_deleteFree

Delete an alert subscription by ID.

Params: alertId

▸Example response

{
  "deleted": true,
  "alertId": "8a7b6c5d-1234-4abc-9def-0123456789ab"
}

pricetik_alert_testFree

Send a test webhook to verify your endpoint signature handling.

Params: alertId

▸Example response

{
  "delivered": true,
  "alertId": "8a7b6c5d-...",
  "endpoint": "https://example.com/hooks/pricetik",
  "responseStatus": 200,
  "latencyMs": 142,
  "signatureSent": "X-PriceTik-Signature: sha256=abc123..."
}

pricetik_alert_deliveriesFree

Inspect recent delivery attempts for an alert (status, response codes, retries).

Params: alertId, limit?

▸Example response

{
  "alertId": "8a7b6c5d-...",
  "deliveries": [
    { "id": "del_2x9y8", "deliveredAt": "2026-05-27T17:30:14Z",
      "status": "succeeded", "responseStatus": 200, "latencyMs": 132 },
    { "id": "del_1k4m2", "deliveredAt": "2026-05-26T09:12:08Z",
      "status": "failed", "responseStatus": 503, "retryCount": 3 }
  ],
  "meta": { "totalAttempts": 2, "succeeded": 1, "failed": 1 }
}

pricetik_statusFree

Service health and feature-flag state.

Params: —

▸Example response

{
  "ok": true,
  "version": "0.25.0",
  "uptimeSec": 419820,
  "flags": {
    "intelApiEnabled": true,
    "hotelToolsV2Enabled": true,
    "activitiesV1Enabled": true,
    "loyaltyInjectionEnabled": true,
    "getCashbackRateEnabled": true
  },
  "providers": {
    "hotelbeds": "operational",
    "openMeteo": "operational"
  }
}

Alert Condition Types

price_belowFire when price drops below value (Shopping)

price_drop_percentFire when price drops by percentage (Shopping)

historical_lowFire when price hits historical low (Shopping)

deal_score_aboveFire when deal score exceeds value 0–100 (Shopping)

hotel_nightly_rate_belowFire when cross-provider best nightly rate drops below value (Hotels)

Access & limits

The entire MCP surface — Shopping, Hotels, and Tickets — is free for every agent. No API key, no daily quota, no card. Optional API keys are available for usage analytics and higher abuse-cap ceilings, but they are never required.

Shopping

· Free for every agent
· No API key required
· Per-fingerprint abuse caps

Hotels

· Free for every agent
· 60 / minute · 1,000 / hour
· Bursts allowed via sliding window

Tickets

· Free for every agent
· Same caps as Hotels
· USD pricing built in

Abuse controls

Burst limit

60 requests per minute per fingerprint (sliding window).

Hourly cap

1,000 requests per hour per fingerprint (sliding window).

Pattern detection

Flags fingerprints with 0% click-through and sequential-id walking (catalog mirroring).

Throttle then ban

Soft-throttle to 10 req/hour for 24h on first flag; permanent ban + email if pattern recurs.

Caps are per IP fingerprint with a sliding window. Established agents that consistently produce legitimate traffic have their caps lifted automatically.

Hotels

Hotels MCP

Search 250K+ hotels via Hotelbeds, with rich content (description, amenities, paid extras, nearby POIs, room catalog), 30+ days of rate history, deal scoring, watch-rate alerts, and signed booking URLs that complete on PriceTik.

Hotel Tools

16 MCP tools backed by /api/v1/intel/hotel-*, /api/v1/intel/explain-price, and /api/v1/intel/check-availability. The surface is cache-first — search, rate history, deal scores, demand, content, room catalog, price breakdowns, and review summaries all read from PriceTik's internal cache. Provider APIs are touched only when refreshing a rateKey before a booking handoff.

Discovery & content

pricetik_hotel_searchFree

Search hotels by destination, dates, guests, with filters for stars, segments (BEACH/BUSINESS/ROMANCE/etc.), chainCode + excludeChainCodes, accommodationType, and the always-on flags excludeResortFees / freeBreakfast / petFriendly. Pin a search center to a specific POI via nearPoiLat / nearPoiLng / nearPoiRadiusKm.

Params: destination, checkIn, checkOut, guests, rooms, segments?, chainCode?, excludeChainCodes?, accommodationType?, excludeResortFees?, freeBreakfast?, petFriendly?, nearPoi*?

▸Example response

{
  "destination": "Las Vegas",
  "checkIn": "2026-08-15",
  "checkOut": "2026-08-17",
  "guests": 2,
  "rooms": 1,
  "totalResults": 24,
  "properties": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "providerPropertyId": "16914",
      "provider": "hotelbeds",
      "name": "Wynn Las Vegas",
      "city": "Las Vegas",
      "country": "US",
      "starRating": 5,
      "reviewScore": 9.2,
      "thumbnailUrl": "https://photos.hotelbeds.com/.../1.jpg",
      "lowestNightlyRate": 389.00,
      "amenities": ["Wi-Fi", "Pool", "Spa", "Gym", "Restaurant"]
    }
  ],
  "travelerProfileApplied": false
}

pricetik_hotel_detailsFree

Full content for a property — description, amenities, paid extras (resort fees), nearby POIs, room catalog, segments, chain, contact info, gallery.

Params: propertyId OR providerPropertyId, include?

▸Example response

{
  "id": "550e8400-...",
  "providerPropertyId": "16914",
  "provider": "hotelbeds",
  "name": "Wynn Las Vegas",
  "starRating": 5,
  "address": "3131 Las Vegas Blvd S, Las Vegas, NV 89109",
  "description": "Five-star resort and casino on the Strip with award-winning restaurants...",
  "amenities": ["Wi-Fi", "Pool", "Spa", "Gym", "Restaurant", "Casino", "Concierge"],
  "paidAmenities": [
    { "name": "Resort fee", "amount": 50.00, "currency": "USD", "frequency": "per_night" },
    { "name": "Self parking", "amount": 18.00, "currency": "USD", "frequency": "per_night" }
  ],
  "interestPoints": [
    { "name": "Las Vegas Strip", "distanceKm": 0.0 },
    { "name": "T-Mobile Arena", "distanceKm": 1.4 }
  ],
  "rooms": [
    { "code": "DLX-K", "name": "Deluxe King", "maxOccupancy": 2 }
  ],
  "chainCode": "WYNN",
  "segments": ["LUXURY", "CITY"]
}

pricetik_hotel_price_checkFree

Per-provider rate comparison for a property + date window. Returns rateKey, paymentType, rateType, cancellation policy, free-cancellation flag.

Params: propertyId, checkIn, checkOut, guests, rooms

▸Example response

{
  "propertyId": "550e8400-...",
  "checkIn": "2026-08-15",
  "checkOut": "2026-08-17",
  "rates": [
    {
      "provider": "hotelbeds",
      "rateKey": "20260815|20260817|W|...",
      "rateType": "BOOKABLE",
      "paymentType": "AT_HOTEL",
      "nightlyRate": 389.00,
      "totalStayCost": 825.30,
      "currency": "USD",
      "freeCancellation": true,
      "cancellationDeadline": "2026-08-13T23:59:00Z"
    }
  ]
}

pricetik_hotel_statusFree

Cache health for the hotel surface — content freshness, rate-history coverage, refresh-worker status. Use before high-stakes booking flows.

Params: —

▸Example response

{
  "ok": true,
  "contentRefreshedAt": "2026-05-27T11:00:00Z",
  "rateHistoryCoverageDays": 184,
  "workers": {
    "hotelPoll": "running",
    "hotelMatch": "running",
    "hotelExpiry": "running"
  },
  "providers": { "hotelbeds": "operational" },
  "killSwitches": {
    "hotelToolsV2Enabled": true,
    "hotelBookingV1Enabled": true
  }
}

Decision intelligence

pricetik_hotel_deal_scoreFree

0–100 deal score based on rate history, provider spread, demand signals, and seasonal premium flags (peak event weeks).

Params: propertyId, checkIn, checkOut

▸Example response

{
  "propertyId": "550e8400-...",
  "checkIn": "2026-08-15",
  "checkOut": "2026-08-17",
  "score": 82,
  "tier": "great",
  "components": {
    "rateVsHistory": 88,
    "providerSpread": 75,
    "demand": 71,
    "seasonalAdjustment": -4
  },
  "seasonalFlag": { "isPeak": false, "eventName": null, "premiumPct": null },
  "currentBest": { "nightlyRate": 389.00, "currency": "USD" }
}

pricetik_hotel_rate_historyFree

Daily best-nightly-rate-across-providers series with deterministic OLS trend slope. Configurable lookback window up to 180 days.

Params: propertyId, checkIn, checkOut, days

▸Example response

{
  "propertyId": "550e8400-...",
  "checkIn": "2026-08-15",
  "checkOut": "2026-08-17",
  "days": 90,
  "trend": "declining",
  "trendSlope": -0.32,
  "history": [
    { "recordedAt": "2026-05-27", "bestNightlyRate": 389.00, "provider": "hotelbeds" },
    { "recordedAt": "2026-05-26", "bestNightlyRate": 401.00, "provider": "hotelbeds" }
  ],
  "stats": { "min": 365.00, "max": 449.00, "median": 402.00, "currency": "USD" }
}

pricetik_hotel_should_bookFree

Deterministic book_now / wait / watch recommendation combining rate trend, demand pressure, cancellation flexibility, days-to-check-in, and seasonal flags. No LLM in the loop.

Params: propertyId, checkIn, checkOut, guests, rooms

▸Example response

{
  "propertyId": "550e8400-...",
  "recommendation": "book_now",
  "confidence": 0.78,
  "reasoning": "Rate is 8% below 90-day median, demand is rising for the date range, and free cancellation is offered.",
  "factors": {
    "rateTrend": "declining",
    "demandPressure": "rising",
    "freeCancellation": true,
    "daysToCheckIn": 80,
    "seasonalFlag": null
  },
  "currentBest": { "nightlyRate": 389.00, "currency": "USD" }
}

pricetik_hotel_compareFree

Side-by-side comparison of 2–4 properties for a single stay window — rate, deal score, top amenities, optional distance from a reference POI.

Params: propertyIds[2..4], checkIn, checkOut, guests, rooms, referencePoi?

▸Example response

{
  "checkIn": "2026-08-15",
  "checkOut": "2026-08-17",
  "properties": [
    { "id": "550e8400-...", "name": "Wynn Las Vegas",
      "nightlyRate": 389.00, "currency": "USD", "starRating": 5,
      "dealScore": 82, "topAmenities": ["Pool", "Spa", "Casino"] },
    { "id": "660f9511-...", "name": "Bellagio",
      "nightlyRate": 359.00, "currency": "USD", "starRating": 5,
      "dealScore": 76, "topAmenities": ["Pool", "Spa", "Fountains"] }
  ],
  "winner": { "propertyId": "550e8400-...", "reason": "Higher deal score and richer amenity match." }
}

pricetik_flexible_datesNew

Find the cheapest contiguous N-night stay within a flexible date window. Pass propertyId for one hotel or destination for the top-25 in radius. Backed by `hotel_price_history` — never calls Hotelbeds. Returns up to 10 candidates with high/low confidence flags.

Params: propertyId? OR destination?, windowStart, windowEnd, nights?, maxNightlyRate?, maxTotalCost?, limit?

▸Example response

{
  "destination": "Las Vegas",
  "windowStart": "2026-06-01",
  "windowEnd": "2026-06-30",
  "nights": 2,
  "candidates": [
    { "checkIn": "2026-06-09", "checkOut": "2026-06-11",
      "totalCost": 612.00, "nightlyRate": 306.00,
      "currency": "USD", "confidence": "high",
      "savingsVsMedian": 124.00 },
    { "checkIn": "2026-06-16", "checkOut": "2026-06-18",
      "totalCost": 638.00, "nightlyRate": 319.00,
      "currency": "USD", "confidence": "high",
      "savingsVsMedian": 98.00 }
  ],
  "meta": { "lookbackDays": 90, "source": "hotel_price_history" }
}

pricetik_alternative_datesNew

Anchored ±N-day shifts of an intended check-in. Same trip duration, just tests wiggle room on the start date. Returns alternatives ranked by savings vs. the requested window. Cache-only.

Params: propertyId, checkIn, checkOut, shiftDays?

▸Example response

{
  "anchor": { "checkIn": "2026-08-15", "checkOut": "2026-08-17" },
  "alternatives": [
    { "checkIn": "2026-08-13", "checkOut": "2026-08-15",
      "totalCost": 698.00, "currency": "USD", "savings": 127.30 },
    { "checkIn": "2026-08-16", "checkOut": "2026-08-18",
      "totalCost": 758.00, "currency": "USD", "savings": 67.30 }
  ],
  "currency": "USD",
  "meta": { "shiftDays": 3 }
}

pricetik_explain_priceNew

Decompose a hotel total into base rate, taxes & fees, paid amenities (resort fee, parking), and seasonal premium. Returns a deterministic headline ("Rate is 20% above this property's typical") plus a renderable line list. Cache-only.

Params: propertyId, checkIn, checkOut

▸Example response

{
  "propertyId": "550e8400-...",
  "checkIn": "2026-08-15",
  "checkOut": "2026-08-17",
  "totalStayCost": 825.30,
  "currency": "USD",
  "lines": [
    { "label": "Base rate (2 nights)", "amount": 700.00 },
    { "label": "Taxes & fees", "amount": 25.30 },
    { "label": "Resort fee (50/night)", "amount": 100.00 }
  ],
  "headline": "Rate is 12% above this property's typical for August.",
  "seasonalPremiumPct": 12.0
}

pricetik_room_typesNew

Filtered, ranked room catalog. Reads cached hotel_property_content.rooms and joins cheapest cached rate per room when a stay window is supplied. Filter by bedType, suite, kitchenette, accessible, minAdults. Cache-only.

Params: propertyId, checkIn?, checkOut?, bedType?, suite?, kitchenette?, accessible?, minAdults?, limit?

▸Example response

{
  "propertyId": "550e8400-...",
  "rooms": [
    { "code": "DLX-K", "name": "Deluxe King",
      "bedType": "king", "maxOccupancy": 2,
      "amenities": ["Wi-Fi", "Mini-bar"],
      "cheapestNightlyRate": 389.00, "currency": "USD" },
    { "code": "STE-1B", "name": "1-Bedroom Suite",
      "bedType": "king", "suite": true, "maxOccupancy": 4,
      "amenities": ["Wi-Fi", "Mini-bar", "Living room"],
      "cheapestNightlyRate": 689.00, "currency": "USD" }
  ]
}

pricetik_check_availabilityNew

Lightweight 'is this rateKey still bookable?' probe. Cheaper than pricetik_hotel_price_check because it doesn't re-price — calls Hotelbeds /checkrates and returns bookable boolean, expiresAt, currentNet/currentGross, paymentType, and a freeCancellation flag.

Params: rateKey, surface?

▸Example response

{
  "rateKey": "20260815|20260817|W|...",
  "bookable": true,
  "expiresAt": "2026-05-27T17:42:00Z",
  "currentNet": 825.30,
  "currentGross": 825.30,
  "currency": "USD",
  "paymentType": "AT_HOTEL",
  "freeCancellation": true,
  "rateType": "BOOKABLE"
}

pricetik_hotel_review_summaryNew

Synthesised review summary — score + count + star rating + segments + theme cues for cleanliness, location, staff, value, comfort. Cache-only — themes are derived from cached amenity content (Hotelbeds doesn't expose per-category breakdowns) and surfaced as -1/0/+1 cues with reasons.

Params: propertyId

▸Example response

{
  "propertyId": "550e8400-...",
  "score": 9.2,
  "count": 3214,
  "starRating": 5,
  "segments": ["LUXURY", "CITY"],
  "themes": [
    { "theme": "cleanliness", "cue": 1, "reasons": ["Pool", "Spa", "Daily housekeeping"] },
    { "theme": "location", "cue": 1, "reasons": ["Las Vegas Strip"] },
    { "theme": "staff", "cue": 1, "reasons": ["Concierge", "Bellman"] },
    { "theme": "value", "cue": -1, "reasons": ["Resort fee"] },
    { "theme": "comfort", "cue": 1, "reasons": ["King bed", "Spa"] }
  ]
}

Booking & alerts

pricetik_hotel_get_booking_urlFree

Generate a signed pricetik.com/go/ booking URL for a held rate. Refreshes the rateKey when within 2 minutes of expiry. Pass an Idempotency-Key header on retries to avoid duplicate redirects (24-hour replay window). User clicks through to PriceTik to complete checkout.

Params: rateKey, providerPropertyId, checkIn, checkOut, guests, rooms, holderEmail? · header: Idempotency-Key?

▸Example response

{
  "url": "https://pricetik.com/go/ck_x9y8z7",
  "expiresAt": "2026-05-27T15:42:00Z",
  "rateKey": "20260815|20260817|W|...",
  "currentBest": {
    "nightlyRate": 389.00,
    "totalStayCost": 825.30,
    "currency": "USD",
    "paymentType": "AT_HOTEL",
    "rateType": "BOOKABLE",
    "freeCancellation": true
  },
  "handoffPolicy": "user_completes_booking"
}

pricetik_hotel_watch_rateFree

Subscribe a webhook to fire when the cross-provider best nightly rate hits or drops below your target. Webhook payload includes a pre-generated booking URL. Pass an Idempotency-Key header on creation retries.

Params: propertyId, checkIn, checkOut, guests, rooms, targetNightlyRate, currency, webhookUrl, expiresAt? · header: Idempotency-Key?

▸Example response

{
  "alert": {
    "id": "9b8c7d6e-...",
    "targetType": "hotel",
    "hotelTarget": {
      "propertyId": "550e8400-...",
      "checkIn": "2026-08-15",
      "checkOut": "2026-08-17",
      "guests": 2,
      "rooms": 1
    },
    "conditions": [{ "type": "hotel_nightly_rate_below", "value": 320.00, "currency": "USD" }],
    "webhookUrl": "https://example.com/hooks/pricetik",
    "isActive": true,
    "expiresAt": "2026-08-13T00:00:00Z",
    "createdAt": "2026-05-27T17:32:00Z"
  }
}

Booking handoff: pricetik_hotel_get_booking_url returns a signed pricetik.com/go/{click_id} redirect. The user clicks through to PriceTik to complete checkout. Agents do not (and per partner certification, cannot) execute the booking themselves.

A typical hotel agent workflow

Five tool calls. No human typing into a search box.

pricetik_hotel_search

Filter by destination, dates, segments (luxury/beach), max nightly rate. Returns 10–25 candidates.

pricetik_hotel_details (top 3, in parallel)

Description, amenities, nearby POIs, paid extras, room catalog.

pricetik_hotel_should_book (each top candidate)

book_now / wait / watch with confidence + reasoning.

pricetik_hotel_get_booking_url (selected)

Signed redirect handed back to the user — completes checkout on PriceTik.

pricetik_hotel_watch_rate (runners-up)

Webhook alert fires if rate drops below the user’s target before check-in.

Provider certification boundary

The Hotels MCP is built around partner certification rules. Some actions are explicitly out of bounds for any agent runtime — the API will refuse them.

Action	Allowed?	Why
Search hotels on the agent’s behalf	✓ Yes	Same as the consumer web app does.
Return rateKey, paymentType, rateType, cancellation policy	✓ Yes	Surfacing these is required by partner certification.
Return description, amenities, nearby POIs from cache	✓ Yes	Content is licensed for local mirroring and reuse.
Generate redirect URL to pricetik.com/hotels/live/...	✓ Yes	Deep link only — no booking executes from the agent runtime.
Have the agent complete the booking via API	✗ No	Booking confirmation must be initiated by an authenticated end user, not an agent.
Surface other-provider rates as if they were Hotelbeds rates	✗ No	Mislabels the source.

Tickets

Tickets MCP

Tours, attractions, and excursions in 200+ destinations via Hotelbeds Activities. Same agent flow as hotels: search → details → booking-url → user. The agent hands the user a pricetik.com/tickets/... URL with trip parameters pre-filled — confirmation happens on PriceTik, not in the agent runtime.

Ticket Tools

7 MCP tools backed by /api/v1/intel/activity-*. Prices come back in USD by default with the source EUR quote preserved alongside, so consumer UIs can show both. Free for every agent — no API key required.

pricetik_activity_searchFree

Search bookable tours, attractions, and excursions by Hotelbeds destination code + dates. Returns price-from in USD with the source EUR quote preserved.

Params: destination, from, to, adults, children, language?, pageSize?, pageNumber?, targetCurrency?

▸Example response

{
  "destination": "LAS",
  "from": "2026-06-15",
  "to": "2026-06-15",
  "totalResults": 18,
  "page": 1,
  "pageSize": 25,
  "displayCurrency": "USD",
  "activities": [
    { "code": "E-E10-A1GMNO0125", "name": "High Roller Observation Wheel",
      "type": "ATTRACTION", "fromAmount": 32.00, "currency": "USD",
      "originalFromAmount": 30.00, "originalCurrency": "EUR",
      "destinationCode": "LAS", "rating": 4.6,
      "thumbnailUrl": "https://photos.hotelbeds.com/.../high-roller.jpg" }
  ]
}

pricetik_activity_detailsFree

Full content for one activity — description, highlights, gallery, meeting point, redemption type — and bookable rates with confirmable rateKeys.

Params: activityCode, from, to, adults, children, language?, targetCurrency?

▸Example response

{
  "code": "E-E10-A1GMNO0125",
  "name": "High Roller Observation Wheel",
  "type": "ATTRACTION",
  "description": "550-foot observation wheel on the Las Vegas Strip...",
  "highlights": ["Tallest observation wheel in the U.S.", "30-min revolution"],
  "displayCurrency": "USD",
  "modalities": [
    { "code": "ANYTIME", "name": "Anytime ticket",
      "rates": [
        { "rateKey": "abc123|...", "net": 28.00, "gross": 32.00,
          "originalNet": 26.00, "originalGross": 30.00, "originalCurrency": "EUR",
          "cancellation": { "freeCancellation": true, "deadline": "2026-06-13T23:59:00Z" } }
      ]
    }
  ],
  "meetingPoint": "High Roller box office at The LINQ Promenade",
  "redeemInfo": "Direct entrance — show voucher at turnstile."
}

pricetik_activity_deal_scoreFree

Deterministic 0–100 score with a reasons array (free cancellation, modality count, meeting-point published, direct entrance, rich content, gallery depth). No LLM in the loop.

Params: activityCode, from, to, adults, children, targetCurrency?

▸Example response

{
  "activityCode": "E-E10-A1GMNO0125",
  "name": "High Roller Observation Wheel",
  "score": 75,
  "fromAmount": 32.00,
  "currency": "USD",
  "originalFromAmount": 30.00,
  "originalCurrency": "EUR",
  "reasons": [
    { "code": "free_cancellation", "label": "Free cancellation available", "contribution": 25 },
    { "code": "many_modalities", "label": "3 pickup/timing options", "contribution": 15 },
    { "code": "direct_entrance", "label": "Direct entrance — skip the line", "contribution": 10 },
    { "code": "rich_gallery", "label": "8 photos", "contribution": 10 },
    { "code": "rich_highlights", "label": "Editor highlights provided", "contribution": 10 },
    { "code": "low_markup_ladder", "label": "Strong net-to-retail spread", "contribution": 5 }
  ]
}

pricetik_activity_get_booking_urlFree

Return a pricetik.com/tickets/... checkout URL pre-filled with the trip parameters. Verifies a bookable rate exists before handing the URL back. Pass an Idempotency-Key header on retries to avoid duplicate redirects (24-hour replay window). The user — not the agent — completes the booking.

Params: activityCode, from, to, adults, children, targetCurrency? · header: Idempotency-Key?

▸Example response

{
  "activityCode": "E-E10-A1GMNO0125",
  "name": "High Roller Observation Wheel",
  "url": "https://pricetik.com/tickets/E-E10-A1GMNO0125?from=2026-06-15&to=2026-06-15&adults=2",
  "expiresAt": "2026-05-27T18:00:00Z",
  "fromAmount": 32.00,
  "currency": "USD",
  "handoffPolicy": "user_completes_booking"
}

pricetik_activity_watch_rateFree

Subscribe a webhook (or auto-book) to a Hotelbeds activity's price or availability. Conditions: targetPricePerPerson, dropPercent, dealScoreAbove, notifyOnAvailability (fires when sold-out activities reappear). Same auto_book semantics as hotels. Evaluation runs every 30 minutes via the activity-watch-rate worker — it groups active alerts by `(activityCode, travelDate, pax, currency)`, re-prices each group via Hotelbeds, and fires HMAC-signed webhooks for matching conditions. Per-alert rate cache (Redis, 30-day TTL) tracks last-observed price + availability so drop-percent and sold-out → available transitions work across pass boundaries.

Params: activityCode, travelDate, adults, children?, targetPricePerPerson?, dropPercent?, dealScoreAbove?, notifyOnAvailability?, currency?, action?, webhookUrl, expiresAt?

▸Example response

{
  "alert": {
    "id": "a1b2c3d4-...",
    "activityCode": "E-MAL-CATAMARAN",
    "travelDate": "2026-07-12",
    "adults": 2,
    "children": 0,
    "conditions": [
      { "type": "activity_price_below", "value": 60.00, "currency": "EUR" },
      { "type": "activity_availability_in_window" }
    ],
    "webhookUrl": "https://example.com/hooks/pricetik",
    "createdAt": "2026-05-27T17:32:00Z",
    "expiresAt": "2026-07-11T00:00:00Z"
  },
  "note": "Activity watch is live. The webhook fires on the first triggering condition; auto_book is honored only for keys with directBookingEnabled=true and a saved Stripe payment method."
}

pricetik_activity_pickup_checkNew

Pickup + meeting-point detail for an activity. Returns hasPickup boolean, meetingPoint, and the list of modalities that include pickup with their pricing and free-cancellation flag. Piggy-backs on the activity-detail cache.

Params: activityCode, from, to, adults, children?, targetCurrency?

▸Example response

{
  "activityCode": "E-MAL-CATAMARAN",
  "name": "Mallorca Catamaran Sunset Cruise",
  "hasPickup": true,
  "meetingPoint": "Port d'Andratx pier, Berth 14",
  "modalitiesWithPickup": [
    { "code": "PICKUP-PALMA", "name": "Hotel pickup — Palma area",
      "additionalCharge": 12.00, "currency": "EUR",
      "freeCancellation": true }
  ]
}

pricetik_activity_compareNew

Side-by-side comparison of 2–4 Hotelbeds activity offerings for a single travel window. Mirror of pricetik_hotel_compare. Returns name, type, cheapest fromAmount + originalFromAmount, freeCancellation flag, modalitiesCount, meetingPoint, and a 0–100 dealScore per activity. The winner block picks the highest dealScore (ties broken by fromAmount ascending) so the agent can quote a clear pick.

Params: activityCodes[2..4], from, to, adults?, children?, language?, targetCurrency?

▸Example response

{
  "from": "2026-08-15",
  "to": "2026-08-15",
  "rows": [
    { "activityCode": "E-LAS-CIRQUE-O",
      "name": "Cirque du Soleil — O at Bellagio",
      "type": "ATTRACTION",
      "fromAmount": 159.00, "currency": "USD",
      "originalFromAmount": 147.00, "originalCurrency": "EUR",
      "freeCancellation": true,
      "modalitiesCount": 3,
      "meetingPoint": "Bellagio O Theatre box office",
      "dealScore": 88 },
    { "activityCode": "E-E10-A1GMNO0125",
      "name": "High Roller Observation Wheel",
      "type": "ATTRACTION",
      "fromAmount": 32.00, "currency": "USD",
      "originalFromAmount": 30.00, "originalCurrency": "EUR",
      "freeCancellation": true,
      "modalitiesCount": 2,
      "meetingPoint": "High Roller box office at The LINQ Promenade",
      "dealScore": 75 }
  ],
  "winner": {
    "activityCode": "E-LAS-CIRQUE-O",
    "reason": "Highest deal score (88/100) with a clear margin."
  }
}

Booking handoff: pricetik_activity_get_booking_url returns a pricetik.com/tickets/{activityCode} URL pre-filled with dates and guest counts. The user clicks through to PriceTik to complete checkout. Agents do not execute the booking themselves — same boundary as hotels.

A typical ticket agent workflow

Four tool calls. Single-day tour or multi-day excursion — same flow.

pricetik_activity_search

Discover candidates by destination + dates. Returns 10–25 activities with USD price-from.

pricetik_activity_details (top 1–3, in parallel)

Description, highlights, gallery, modalities, supplier-required questions, bookable rates.

pricetik_activity_deal_score (each top candidate)

Quote-able reasons the agent can show the user (free cancel, direct entry, rich content).

pricetik_activity_get_booking_url (selected)

Pre-filled pricetik.com/tickets/{code}?from=...&to=... handed back to the user — completes checkout on PriceTik.

Trip Planner

Trip planner tools

Cross-vertical orchestration so agents can answer prompts like "find me the cheapest hotel in Vegas June 14–17, no resort fees, near the strip, plus some fun events" in onetool call instead of 4–6 sequential ones. Saves both latency and the LLM's tool-call budget.

Trip Planner Tools

Backed by /api/v1/intel/trip-plan and /api/v1/intel/destinations. Free for every agent — no key required, though authenticated calls get higher abuse-cap ceilings.

pricetik_trip_planFree

Single-call orchestrated trip planner. Pass destination + dates + budget + interests; get back top hotels, recommended activities, and an estimated total spend. Set `groupByDay=true` to receive a daily itinerary with rest-day placeholders for trips longer than 5 nights and conflict avoidance for 4h+ activities. Honors `noResortFees` (now SQL-backed), `starRating`, `segments`, and per-day caps.

Params: destination, checkIn, checkOut, adults?, children?, rooms?, budgetUsd?, activityDestinationCode?, interests?, activitiesPerDay?, groupByDay?, noResortFees?, starRating?, segments?, hotelCount?

▸Example response

{
  "destination": "Las Vegas",
  "trip": { "checkIn": "2026-06-14", "checkOut": "2026-06-17", "nights": 3,
            "adults": 2, "children": 0, "rooms": 1 },
  "budget": { "totalUsd": 1500, "suggestedHotelCapUsd": 1050, "suggestedActivitiesCapUsd": 450 },
  "hotels": [
    { "id": "550e8400-...", "name": "Wynn Las Vegas", "city": "Las Vegas",
      "nightlyRate": 312, "totalStayCost": 936, "currency": "USD",
      "starRating": 5, "dealScore": 78,
      "bookingUrl": "https://pricetik.com/hotels/...",
      "summary": "78/100 deal · 3 nights at $312/night" }
  ],
  "activities": [
    { "code": "E-E10-A1GMNO0125", "name": "High Roller Observation Wheel",
      "pricePerPerson": 32, "currency": "USD", "durationHours": 1,
      "freeCancellation": true,
      "bookingUrl": "https://pricetik.com/tickets/E-E10-A1GMNO0125...",
      "summary": "~$32pp · 1h" }
  ],
  "estimatedTotalUsd": 1064,
  "notes": []
}

pricetik_destinationsFree

Resolve free-text destination input ("Las Vegas", "Mallorca") into the canonical shape every other PriceTik tool needs: hotel-search-friendly text, Hotelbeds 3-letter activity destination code, country, and subtitle. Use BEFORE calling pricetik_hotel_search or pricetik_activity_search when you only have free-text from the user.

Params: q (required, min 2 chars), limit?

▸Example response

{
  "query": "las vegas",
  "results": [
    { "label": "Las Vegas, Nevada",
      "hotelSearchText": "Las Vegas",
      "activityDestinationCode": "LAS",
      "country": "United States",
      "subtitle": "Nevada · 4-star average $245/night" },
    { "label": "Las Vegas, New Mexico",
      "hotelSearchText": "Las Vegas, NM",
      "activityDestinationCode": null,
      "country": "United States",
      "subtitle": "New Mexico · smaller market" }
  ]
}

pricetik_compare_destinationsNew

Apples-to-apples destination comparison ("Cabo vs Tulum"). Returns median 4★ nightly rate, top-3 hotels per destination by deal score, top-3 activities, and a seasonal-premium flag (event-window markers like "F1 weekend in Vegas — rates 65% above baseline"). Stricter rate cap than other tools — fans out 2–4 parallel hotel + activity searches.

Params: destinations[2..4], checkIn, checkOut, guests?, rooms?, activityCodes?, starRating?

▸Example response

{
  "destinations": ["Cabo San Lucas", "Tulum"],
  "checkIn": "2026-09-12",
  "checkOut": "2026-09-15",
  "comparison": [
    { "destination": "Cabo San Lucas",
      "median4StarNightlyRate": 312.00, "currency": "USD",
      "topHotels": [
        { "id": "550e8400-...", "name": "Grand Velas Los Cabos",
          "nightlyRate": 489.00, "dealScore": 81 }
      ],
      "topActivities": [
        { "code": "E-CSL-WHALEWATCH", "name": "Whale Watching Tour",
          "fromAmount": 78.00, "currency": "USD" }
      ],
      "seasonalFlag": null
    },
    { "destination": "Tulum",
      "median4StarNightlyRate": 268.00, "currency": "USD",
      "topHotels": [
        { "id": "660f9511-...", "name": "Hotel Esencia",
          "nightlyRate": 419.00, "dealScore": 84 }
      ],
      "topActivities": [
        { "code": "E-TUL-CENOTES", "name": "Cenotes & Mayan Ruins",
          "fromAmount": 92.00, "currency": "USD" }
      ],
      "seasonalFlag": null
    }
  ]
}

pricetik_my_tripsNew · Auth required

List the authenticated user's trips — bookings grouped by destination + overlapping window. Each trip carries hotel + all activities, total spend, days-until-departure countdown, and per-member manage URLs. Powers "what's on my Vegas trip in June?" prompts. Requires API key.

Params: status?, limit?

▸Example response

{
  "trips": [
    { "id": "trip_2026_06_vegas",
      "destination": "Las Vegas",
      "checkIn": "2026-06-14",
      "checkOut": "2026-06-17",
      "daysUntilDeparture": 18,
      "totalSpendUsd": 1064.00,
      "members": ["00000000-0000-4000-8000-000000000abc"],
      "hotel": { "name": "Wynn Las Vegas",
                 "manageUrl": "https://pricetik.com/my-account/hotels/00000000-0000-4000-8000-000000000001" },
      "activities": [
        { "name": "High Roller Observation Wheel",
          "manageUrl": "https://pricetik.com/my-account/tickets/00000000-0000-4000-8000-000000000002" }
      ] }
  ],
  "meta": { "totalTrips": 1 }
}

Reference Tools

Cross-vertical helpers agents reach for repeatedly: currency conversion against the same FX cache the booking surfaces use, weather forecasts that pair with pricetik_hotel_should_book, a real-time presence indicator (pricetik_demand_pulse), and per-retailer cashback rates (pricetik_get_cashback_rate). Free for every agent.

pricetik_currency_convertNew

Convert an amount between two ISO 4217 currencies. Cache-only — uses the same Redis FX cache the hotel + activity surfaces share. Returns the converted amount, effective rate, and cache fetched-at. Batch endpoint accepts up to 100 amounts in one round-trip.

Params: amount, from, to · POST /batch: { from, to, amounts[] }

▸Example response

{
  "amount": 100.00,
  "from": "EUR",
  "to": "USD",
  "convertedAmount": 108.42,
  "rate": 1.0842,
  "fetchedAt": "2026-05-27T17:00:00Z",
  "source": "ecb_redis_cache"
}

pricetik_weather_forecastNew

Daily weather forecast for a destination + date window. Powered by Open-Meteo (free, no API key, ~16-day horizon). Returns per-day highs/lows/precip/wind plus an aggregate headline summary. Pairs with pricetik_hotel_should_book to answer "should I book + what is the weather" in two tool calls.

Params: destination, startDate, endDate, units?

▸Example response

{
  "destination": "Las Vegas",
  "lat": 36.1716,
  "lng": -115.1391,
  "startDate": "2026-08-15",
  "endDate": "2026-08-17",
  "units": "imperial",
  "headline": "Hot and clear — highs in the low 100s, near-zero precipitation.",
  "days": [
    { "date": "2026-08-15", "highF": 102, "lowF": 81, "precipIn": 0.0, "windMph": 8 },
    { "date": "2026-08-16", "highF": 104, "lowF": 82, "precipIn": 0.0, "windMph": 6 },
    { "date": "2026-08-17", "highF": 103, "lowF": 80, "precipIn": 0.0, "windMph": 7 }
  ],
  "aggregate": { "avgHighF": 103, "avgLowF": 81, "totalPrecipIn": 0.0 },
  "source": "open-meteo"
}

pricetik_demand_pulseNew

Real-time presence indicator. Returns unique-viewer + query counts for a target (hotel, product, or activity) over the trailing window. Activity targets pivot on `intel_queries.activity_code` and enrich the headline with the cached display name — "8 people are looking at this Cirque du Soleil show right now."

Params: target (hotel | product | activity), id, windowSec?

▸Example response

{
  "target": "activity",
  "id": "E-LAS-CIRQUE-O",
  "windowSec": 60,
  "uniqueViewers": 8,
  "totalQueries": 14,
  "intensity": "moderate",
  "headline": "8 people are looking at this Cirque du Soleil show right now.",
  "targetName": "Cirque du Soleil show",
  "meta": { "method": "intel_queries", "queriedAt": "2026-05-27T17:55:00Z" }
}

pricetik_get_cashback_rateNew

Return the cashback rate a user would earn for a retailer. Pass exactly one of `retailer` (canonical key like 'amazon'), `productId`, or `url`. Optional `price` adds a USD `estimatedCashback` projection. Auth optional — Pro callers see the Pro multiplier (1.25× share rate, capped at 100%). Returns rate=0 with `meta.isFallback=true` when no active affiliate config exists for the retailer.

Params: retailer? OR productId? OR url? (exactly one), price?

▸Example response

{
  "retailer": {
    "key": "amazon",
    "displayName": "Amazon",
    "tier": "general",
    "domain": "amazon.com"
  },
  "commissionRate": 0.045,
  "userShareRate": 0.50,
  "cookieWindowDays": 30,
  "tierMultiplier": 1.25,
  "effectiveShareRate": 0.625,
  "cashbackPercent": 2.81,
  "userTier": "pro",
  "projection": {
    "price": 278.00,
    "estimatedCommission": 12.51,
    "estimatedCashback": 7.82,
    "currency": "USD"
  },
  "meta": {
    "resolvedFrom": "url",
    "rateFetchedAt": "2026-05-26T08:00:00Z",
    "isFallback": false
  }
}

Watch & alert tools (enhanced)

Watch tools now accept multiple OR-conditions (price, percent drop, deal score, availability) in one call, and an optional action="auto_book" that attempts a direct charge when the trigger fires.

pricetik_hotel_watch_rate (enhanced)Free

Now accepts multiple OR-conditions in one call: targetNightlyRate (dollar threshold), dropPercent (% off creation baseline), dealScoreAbove (0–100 deal score). Optional action="auto_book" attempts a direct charge when the trigger fires (requires API key with directBookingEnabled=true; degrades to webhook otherwise). All triggers OR — alert fires on the first that hits.

Params: propertyId, checkIn, checkOut, guests, rooms, targetNightlyRate?, dropPercent?, dealScoreAbove?, currency?, action?, webhookUrl, expiresAt?

pricetik_activity_watch_rateFree

Params: activityCode, travelDate, adults, children?, targetPricePerPerson?, dropPercent?, dealScoreAbove?, notifyOnAvailability?, currency?, action?, webhookUrl, expiresAt?

Auto-book safety: the email-confirmation handshake still runs before any charge, even on auto_book triggers. Hotelbeds partner certification requires a human-in-the-loop confirmation, and we honor it by sending a 1-click confirm/cancel email; the user can cancel before any card movement. See the agent-keys-backend-spec for the full lifecycle.

Account

Account tools

Authenticated tools that surface a user's own PriceTik state — bookings, vouchers, account summary, payment methods, billing portal handoff. Require a bearer API key minted from the dashboard. Power conversations like "pull up my Wynn Vegas voucher," "update my credit card," and "what did I save this year?"

Account Tools

Backed by /api/v1/intel/my-*. Open-tier requests get 401 Unauthorized; the bearer key's userId is the implicit filter, so an agent can never read another user's data.

pricetik_my_bookingsAuth required

List the authenticated user's hotel and event bookings. Returns property name, dates, total, status (upcoming/past/cancelled), and a manage URL. Filter by free-text property name (q), status, surface, and limit. Returns 401 without a bearer API key.

Params: q?, status?, surface?, limit?

▸Example response

{
  "page": 1,
  "limit": 20,
  "total": 3,
  "bookings": [
    { "id": "00000000-0000-4000-8000-000000000001",
      "surface": "hotel", "providerReference": "HBED-12345-67",
      "propertyName": "Wynn Las Vegas",
      "checkIn": "2026-08-15", "checkOut": "2026-08-17",
      "totalCost": 825.30, "currency": "USD", "status": "upcoming",
      "manageUrl": "https://pricetik.com/my-account/hotels/00000000-0000-4000-8000-000000000001" },
    { "id": "00000000-0000-4000-8000-000000000002",
      "surface": "activity", "providerReference": "HBED-A-9988",
      "name": "High Roller Observation Wheel",
      "travelDate": "2026-08-16",
      "totalCost": 64.00, "currency": "USD", "status": "upcoming",
      "manageUrl": "https://pricetik.com/my-account/tickets/00000000-0000-4000-8000-000000000002" }
  ]
}

pricetik_my_booking_voucherAuth required

Return full reservation detail for a single booking the user owns: confirmation number, address, room type, check-in dates, total paid, cancellation policy, manage URL. Use after pricetik_my_bookings narrows to one record.

Params: bookingId (required, UUID)

▸Example response

{
  "bookingId": "00000000-0000-4000-8000-000000000001",
  "providerReference": "HBED-12345-67",
  "surface": "hotel",
  "propertyName": "Wynn Las Vegas",
  "address": "3131 Las Vegas Blvd S, Las Vegas, NV 89109",
  "checkIn": "2026-08-15",
  "checkOut": "2026-08-17",
  "rooms": [{ "type": "Deluxe King", "occupants": 2 }],
  "totalCost": 825.30,
  "currency": "USD",
  "cancellationPolicy": "Free cancellation until 2026-08-13 23:59 UTC.",
  "manageUrl": "https://pricetik.com/my-account/hotels/00000000-0000-4000-8000-000000000001"
}

pricetik_my_watchesAuth required

List every active price-watch / watch-rate the user has across hotels, events, and shopping. Each entry includes a human-readable conditions array (e.g. "Nightly rate drops below USD $200") so the agent can quote watches verbatim. Filter by status (active/disabled/all), surface, limit.

Params: status?, surface?, limit?

▸Example response

{
  "page": 1,
  "limit": 20,
  "total": 2,
  "watches": [
    { "id": "9b8c7d6e-...", "surface": "hotel", "isActive": true,
      "target": { "propertyName": "Wynn Las Vegas",
                  "checkIn": "2026-08-15", "checkOut": "2026-08-17" },
      "conditionsHuman": ["Nightly rate drops below USD $320"],
      "createdAt": "2026-05-27T17:32:00Z" }
  ]
}

pricetik_my_accountAuth required

Return account summary: email, plan, lifetime savings, total fills, hasPaymentMethod flag. Use to pre-flight conversational paths like "should I suggest direct booking?"

Params: —

▸Example response

{
  "userId": "00000000-0000-4000-8000-000000000abc",
  "email": "alex@example.com",
  "plan": "pro",
  "lifetimeSavings": 3214.80,
  "totalFills": 18,
  "hasPaymentMethod": true,
  "createdAt": "2025-11-04T12:00:00Z"
}

pricetik_my_payment_methodsAuth required

List saved Stripe cards (last4, brand, expiry, default flag). Read-only. To add or change a card, call pricetik_update_payment_method instead — raw card data is never accepted over MCP.

Params: —

▸Example response

{
  "paymentMethods": [
    { "id": "pm_1Nx9...", "brand": "visa", "last4": "4242",
      "expMonth": 12, "expYear": 2028, "isDefault": true },
    { "id": "pm_1Mr3...", "brand": "amex", "last4": "0005",
      "expMonth": 5, "expYear": 2027, "isDefault": false }
  ]
}

pricetik_update_payment_methodAuth required

Return a Stripe-hosted Customer Portal URL where the user can add, remove, or change their default payment method. Hand the URL to the user verbatim. Single-use, expires in ~1 hour. PCI scope-out: card data never touches the agent runtime.

Params: returnUrl?

▸Example response

{
  "url": "https://billing.stripe.com/p/session/_xyz789",
  "expiresAt": "2026-05-27T18:32:00Z",
  "single_use": true
}

pricetik_cancel_bookingNew · Auth required

Cancel a completed direct booking the user owns. Calls the provider DELETE, refunds the Stripe charge, marks the row cancelled. Hotels-only today (Activities cancel via support email). Returns the refund id and amount.

Params: bookingId

▸Example response

{
  "bookingId": "00000000-0000-4000-8000-000000000001",
  "status": "cancelled",
  "refund": {
    "id": "re_1Nx9abc",
    "amount": 825.30,
    "currency": "USD",
    "expectedSettlementDays": 7
  },
  "cancelledAt": "2026-05-27T17:50:00Z"
}

pricetik_modify_bookingNew · Auth required

Modify a completed direct booking. Hotelbeds doesn't support real modifications, so this tool returns 422 with a `nextSteps` payload describing the cancel + rebook flow (price-check → cancel-booking → get-booking-url). Use it to surface clear guidance to the user.

Params: bookingId

▸Example response

{
  "statusCode": 422,
  "error": "ModifyNotSupported",
  "message": "Hotelbeds does not support direct booking modifications.",
  "nextSteps": [
    { "step": 1, "tool": "pricetik_hotel_price_check",
      "purpose": "Re-check the rate for the new dates." },
    { "step": 2, "tool": "pricetik_cancel_booking",
      "purpose": "Cancel this booking and trigger refund." },
    { "step": 3, "tool": "pricetik_hotel_get_booking_url",
      "purpose": "Generate a fresh booking URL for the new dates." }
  ]
}

pricetik_traveler_profile_get / setNew · Auth required

Stored per-user travel preferences (preferred chains, excluded chains, segments, bed type, star floor, resort-fee/breakfast/pet flags, max nightly rate, loyalty programs, freeform extraPrefs). Once stored, pass `applyTravelerProfile=true` on hotel_search and trip_plan to soft-merge prefs over caller params. Caller params always win.

Params: GET: — · SET: full profile body (PUT) or partial (PATCH)

▸Example response

{
  "userId": "00000000-0000-4000-8000-000000000abc",
  "preferredChainCodes": ["MARR", "HYAT"],
  "excludedChainCodes": [],
  "preferredSegments": ["BUSINESS"],
  "preferredBedType": "king",
  "minStarRating": 4,
  "excludeResortFees": true,
  "freeBreakfast": true,
  "petFriendly": false,
  "needsAccessible": false,
  "maxNightlyRateUsd": 350,
  "loyaltyPrograms": [
    { "program": "MARR", "memberId": "BONVOY-12345" }
  ],
  "extraPrefs": {},
  "updatedAt": "2026-05-20T09:30:00Z"
}

pricetik_my_savings_reportNew · Auth required

Authenticated savings breakdown — lifetime totals (savings, fills, avg/fill), year-to-date, per-month breakdown for the requested year, top 3 fills by savings, and per-surface (retail / hotel) split. Powers "how much have I saved this year?" prompts.

Params: year?

▸Example response

{
  "userId": "00000000-0000-4000-8000-000000000abc",
  "year": 2026,
  "lifetime": { "savingsUsd": 3214.80, "fills": 18, "avgPerFill": 178.60 },
  "ytd": { "savingsUsd": 1102.45, "fills": 7 },
  "perMonth": [
    { "month": "2026-01", "savingsUsd": 142.50, "fills": 1 },
    { "month": "2026-03", "savingsUsd": 580.20, "fills": 3 },
    { "month": "2026-05", "savingsUsd": 379.75, "fills": 3 }
  ],
  "topFills": [
    { "surface": "hotel", "name": "Wynn Las Vegas",
      "savingsUsd": 240.00, "filledAt": "2026-05-12" }
  ],
  "perSurface": { "retail": 824.30, "hotel": 2390.50 }
}

pricetik_my_loyalty_linkNew · Auth required

Read-only convenience tool over `traveler_profiles.loyaltyPrograms`. Pass `?program=MARRIOTT` to narrow to a single program, or omit for all stored entries. Saves a round-trip vs. `pricetik_traveler_profile_get` when the agent only needs the loyalty block.

Params: program?

▸Example response

{
  "userId": "00000000-0000-4000-8000-000000000abc",
  "loyaltyPrograms": [
    { "program": "MARR", "memberId": "BONVOY-12345" }
  ],
  "meta": { "totalStored": 1, "returned": 1, "filteredBy": "MARR" },
  "notice": null
}

pricetik_my_loyalty_link_setNew · Auth required

Upsert or remove a single loyalty program on the authenticated user's `traveler_profiles.loyaltyPrograms`. Body: `{ program, memberId }` to upsert (replace by case-insensitive program match, else append), or `{ program, delete: true }` to remove. The traveler_profiles row is created if missing — first-time linking does NOT need a prior pricetik_traveler_profile_set call. Returns the updated `loyaltyPrograms` array plus an `action` field (`appended` / `replaced` / `removed` / `noop`).

Params: program (required), memberId (required on upsert), delete?

▸Example response

{
  "userId": "00000000-0000-4000-8000-000000000abc",
  "program": "MARR",
  "action": "appended",
  "loyaltyPrograms": [
    { "program": "HILT", "memberId": "HONORS-99999" },
    { "program": "MARR", "memberId": "BONVOY-12345" }
  ],
  "meta": {
    "previousCount": 1,
    "currentCount": 2,
    "removedCount": 0
  }
}

pricetik_alert_rotate_secretNew · Auth required

Rotate the HMAC signing secret on the developer-API-key row. The new secret is returned once (preview only) — store it server-side and update the verifier within 24h. Mirrors the existing key-rotation pattern.

Params: —

▸Example response

{
  "rotated": true,
  "apiKeyId": "key_1abc...",
  "newSecretPreview": "whsec_********9zk2",
  "rotatedAt": "2026-05-27T17:55:00Z",
  "noticeForReceiver": "Future webhook deliveries will be HMAC-signed with the new secret. Update your verifier within 24h."
}

Privacy: bookings made before the user minted their key are still visible (the key authenticates the user, not the time window). Direct-charge bookings include providerBookingReference so the agent can quote a confirmation number; deep-link bookings only include the PriceTik-side manage URL.

PCI compliance: pricetik_update_payment_methodnever accepts raw card data. It returns a single-use Stripe Customer Portal URL the agent hands to the user; card collection happens inside Stripe's hosted UI. This keeps your agent runtime out of PCI scope and matches the same flow Stripe uses for "manage subscription."

Reference (all surfaces)

Authentication

Every surface — Shopping, Hotels, and Tickets — works without authentication. Just call the MCP tools. API keys are optional and only useful for usage analytics or higher abuse-cap ceilings; pass them via the Authorization: Bearer <key> header.

Key Management Endpoints

POST /intel/keys

Create a new API key. Returns the plaintext key once — store it securely.

Params: —

GET /intel/keys

List your API keys (masked). Shows prefix, status, and last used.

Params: —

POST /intel/keys/:id/rotate

Rotate a key. Old key remains valid for a 1-hour grace period.

Params: id (required)

DELETE /intel/keys/:id

Revoke a key immediately. Cannot be undone.

Params: id (required)

OpenAPI Spec

Machine-readable spec available at /api/v1/intel/openapi.json. Covers both Shopping and Hotels routes. Use it to auto-generate client SDKs or import into Postman.

Response Format

All endpoints return a consistent envelope. Retailer and booking URLs are always /go/ redirects — never raw affiliate links.

Shopping

json

{
  "product": {
    "id": "550e8400-...",
    "name": "Sony WH-1000XM5",
    "currentPrice": 278.00,
    "retailers": [
      {
        "name": "amazon",
        "price": 278.00,
        "url": "https://pricetik.com/go/ck_a1b2c3",
        "inStock": true
      }
    ]
  },
  "dealScore": 82,
  "meta": {
    "cached": false,
    "requestId": "req-abc123"
  }
}

Hotels

json

{
  "property": {
    "id": "550e8400-...",
    "providerPropertyId": "16914",
    "name": "Westgate Las Vegas Resort & Casino",
    "stars": 4,
    "city": "Las Vegas",
    "country": "US"
  },
  "bestRate": {
    "provider": "hotelbeds",
    "nightlyRate": 189.00,
    "currency": "USD",
    "rateKey": "20260815|20260817|...",
    "rateType": "BOOKABLE",
    "freeCancellation": true,
    "expiresAt": "2026-05-23T18:42:00Z"
  },
  "dealScore": 78,
  "meta": {
    "cached": true,
    "source": "cache",
    "requestId": "req-hot-456"
  }
}

X-PriceTik-Cached

hit / miss — response cache status

X-Request-Id

Echoes the request ID for tracing

X-RateLimit-Remaining

Remaining requests in the current window

Streaming (NDJSON)

The heavy fan-out routes (pricetik_hotel_search, pricetik_trip_plan, pricetik_compare_destinations) accept ?stream=ndjson or Accept: application/x-ndjson for incremental output. The header frame ships in under 50ms even on cache-miss searches that take 2–3s overall — your agent can render the first hotel while the rest are still on the wire.

bash

# Stream hotel results row-by-row as they materialize
curl -N 'https://api.pricetik.com/api/v1/intel/hotel-search?destination=Las%20Vegas&checkIn=2026-08-15&checkOut=2026-08-17&guests=2&rooms=1&stream=ndjson'

# Or via Accept header
curl -N -H 'Accept: application/x-ndjson' \
  'https://api.pricetik.com/api/v1/intel/trip-plan?destination=Mallorca&checkIn=2026-06-02&checkOut=2026-06-09&adults=2&groupByDay=true'

# In Node — read line-by-line and dispatch on `kind`
const res = await fetch(url);
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buf = '';
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buf += decoder.decode(value, { stream: true });
  let nl;
  while ((nl = buf.indexOf('\n')) >= 0) {
    const line = buf.slice(0, nl);
    buf = buf.slice(nl + 1);
    if (line.trim()) {
      const frame = JSON.parse(line);
      // frame.kind = 'header' | 'property' | 'summary' | 'error'
      handleFrame(frame);
    }
  }
}

Frame protocol — one JSON object per line, separated by \n:

ndjson

{"kind":"header","destination":"Las Vegas","checkIn":"2026-08-15","checkOut":"2026-08-17","guests":2,"rooms":1,"totalResults":24}
{"kind":"property","data":{"id":"550e8400-...","name":"Wynn Las Vegas","starRating":5,"lowestNightlyRate":389.00}}
{"kind":"property","data":{"id":"660f9511-...","name":"Bellagio","starRating":5,"lowestNightlyRate":345.00}}
{"kind":"property","data":{"id":"7720ab22-...","name":"The Cosmopolitan","starRating":5,"lowestNightlyRate":312.00}}
{"kind":"summary","totalResults":24,"returned":10}

kind: header

First frame — trip parameters echoed back. Always present.

kind: property | hotel | activity | destination

One frame per result. Order matches the non-streaming response.

kind: summary

Closing frame — totals, notes, and any aggregated fields.

kind: error

Surfaces if the upstream fails mid-stream. Always the last frame.

MCP transport note: streaming is HTTP-only today. The MCP stdio transport returns one JSON-RPC result per call, so calling these tools through Claude / Cursor / Cline gets the full non-streaming response. Direct REST callers see the streaming benefit.

Error Codes

All errors follow the same envelope. Handle these codes in your agent's error path.

Status	Error Code	Description	Retry?
400	`ValidationError`	Invalid or missing parameters	No — fix params
401	`Unauthorized`	Invalid API key (when an optional key is provided)	No — check key
404	`ProductNotFound`	Product or property ID not in catalog or URL not recognized	No
410	`RateKeyExpired`	Hotel rateKey expired before booking-URL generation	Yes — refetch via pricetik_hotel_price_check
429	`RateLimitExceeded`	Sliding-window abuse cap exceeded for your fingerprint	Yes — after Retry-After
503	`HotelToolDisabled`	Hotel surface temporarily disabled via kill switch	Yes — backoff
503	`ServiceUnavailable`	Intel API temporarily disabled via kill switch	Yes — backoff
500	`InternalError`	Unexpected server error	Yes — exponential backoff

Rate Limiting

Shopping

Per-IP-fingerprint sliding-window caps — 60 req/min and 1,000 req/hour. Optional API keys lift these caps automatically as usage history builds.

Hotels

Same per-fingerprint sliding caps as Shopping — 60 req/min and 1,000 req/hour. No daily quota anywhere.

When you hit a limit

The API returns 429 Too Many Requests with a Retry-After header indicating seconds until the window resets.

http

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 3600
X-RateLimit-Remaining: 0

{
  "statusCode": 429,
  "error": "RateLimitExceeded",
  "message": "Rate limit exceeded. Resets in 3600 seconds."
}

Webhook Payloads

Both Shopping and Hotels alerts use the same delivery pipeline. Webhook requests include an X-PriceTik-Signature header containing an HMAC-SHA256 signature of the body using your key's webhook signing secret.

Shopping

json

{
  "event": "alert.triggered",
  "alertId": "a1b2c3d4-...",
  "triggeredAt": "2026-04-25T14:30:00Z",
  "product": {
    "id": "550e8400-...",
    "name": "Sony WH-1000XM5",
    "currentPrice": 248.00,
    "previousPrice": 278.00,
    "url": "https://pricetik.com/go/ck_x9y8z7"
  },
  "condition": {
    "type": "price_below",
    "value": 250,
    "matched": true
  },
  "meta": {
    "retailer": "amazon",
    "dealScore": 91,
    "requestId": "wh-abc123"
  }
}

Hotels

json

{
  "event": "alert.triggered",
  "alertId": "h1b2c3d4-...",
  "triggeredAt": "2026-05-23T09:15:00Z",
  "hotelTarget": {
    "propertyId": "550e8400-...",
    "propertyName": "Hotel Riu Palace Cabo San Lucas",
    "checkIn": "2026-06-15",
    "checkOut": "2026-06-17",
    "guests": 2,
    "rooms": 1,
    "currentNightlyRate": 178.00,
    "previousNightlyRate": 215.00,
    "currency": "USD"
  },
  "condition": {
    "type": "hotel_nightly_rate_below",
    "value": 180,
    "matched": true
  },
  "bookingUrl": "https://pricetik.com/go/ck_h_x9y8z7",
  "meta": {
    "provider": "hotelbeds",
    "rateKeyExpiresAt": "2026-05-23T09:35:00Z",
    "requestId": "wh-hot-789"
  }
}

Retry policy

3 retries with exponential backoff (1s, 2s, 4s). Alert disabled after 5 consecutive failures.

Timeout

Your endpoint must respond within 10 seconds with a 2xx status code.

Attribution System

How /go/ URLs work end-to-end — the same flow for both retailer and hotel-booking URLs.

All retailer and hotel-booking URLs in API responses are pricetik.com/go/{click_id} redirects.

Affiliate tag (retail) or rateKey (hotels) is composed at redirect time — not embedded in the API response.

Click records track the full lifecycle: created → opened → converted (booking confirmed for hotels and events).

Browser vs server-fetch classification detects tag stripping.

Reconciliation from affiliate networks (CJ, Impact, AWIN, ShareASale) for retail; direct booking confirmations for hotels and events.

No raw affiliate IDs ever appear in API responses — they are composed at redirect time.

Anomaly detection flags suspicious attribution patterns and ranks fingerprints by conversion to lift hotel throttles.

Feature Flags

Runtime kill switches. Shopping flags default to true in production; Hotels flags use a layered allowlist → percentage rollout.

INTEL_API_ENABLED

Master kill switch for the entire MCP server surface.

INTEL_OPEN_TIER_ENABLED

Disable unauthenticated Shopping access if abuse spikes.

INTEL_GO_REDIRECT_ENABLED

Toggle the /go/ redirect system.

INTEL_ANOMALY_DETECTION_ENABLED

Toggle the anomaly detection worker.

HOTEL_TOOLS_V2_ENABLED

Phase-0 master kill switch for the entire hotel surface.

HOTEL_CONTENT_TOOLS_V1_ENABLED

Phase-1 master kill switch (details, rate-history, should-book, compare).

HOTEL_BOOKING_V1_ENABLED

Phase-2 master kill switch (booking URL, watch-rate, hotel demand).

HOTEL_BOOKING_URL_V1_ENABLED

Per-tool flag for pricetik_hotel_get_booking_url. Protects partner quota.

HOTEL_FLEX_DATES_ENABLED

Per-tool flag for pricetik_flexible_dates.

TRIP_PLAN_ENABLED

Per-tool flag for pricetik_trip_plan. Drops just the orchestrator without touching hotels or activities.

COMPARE_DESTINATIONS_ENABLED

Per-tool flag for pricetik_compare_destinations.

MY_TRIPS_ENABLED

Per-tool flag for pricetik_my_trips.

EXPLAIN_PRICE_ENABLED

Per-tool flag for pricetik_explain_price.

HOTEL_ALTERNATIVE_DATES_ENABLED

Per-tool flag for pricetik_alternative_dates.

HOTEL_ROOM_TYPES_ENABLED

Per-tool flag for pricetik_room_types.

BOOKING_LIFECYCLE_ENABLED

Per-tool flag for pricetik_cancel_booking + pricetik_modify_booking.

TRAVELER_PROFILE_ENABLED

Per-tool flag for the traveler-profile get/set/patch/delete surface.

CURRENCY_CONVERT_ENABLED

Per-tool flag for pricetik_currency_convert (single + batch).

WEATHER_FORECAST_ENABLED

Per-tool flag for pricetik_weather_forecast (Open-Meteo upstream).

CHECK_AVAILABILITY_ENABLED

Per-tool flag for pricetik_check_availability. Critical for Hotelbeds quota protection.

HOTEL_REVIEW_SUMMARY_ENABLED

Per-tool flag for pricetik_hotel_review_summary.

ACTIVITY_PICKUP_CHECK_ENABLED

Per-tool flag for pricetik_activity_pickup_check.

MY_SAVINGS_REPORT_ENABLED

Per-tool flag for pricetik_my_savings_report.

DEMAND_PULSE_ENABLED

Per-tool flag for pricetik_demand_pulse.

ALERT_ROTATE_SECRET_ENABLED

Per-tool flag for pricetik_alert_rotate_secret.

MY_LOYALTY_LINK_ENABLED

Per-tool flag for pricetik_my_loyalty_link.

LOYALTY_INJECTION_ENABLED

Per-tool flag for the loyalty-injection branch on pricetik_hotel_get_booking_url.

GET_CASHBACK_RATE_ENABLED

Per-tool flag for pricetik_get_cashback_rate.

ACTIVITIES_V1_ENABLED

Master kill switch for the Events / Tickets MCP surface (covers pricetik_activity_compare too).

Architecture Overview

Agent calls MCP tool → Fastify intel endpoint.

Fingerprint resolution → sliding-window abuse caps → cache check → response shaping.

Hotel surface serves entirely from PriceTik-side cache during normal traffic. Provider APIs are touched only for rateKey refresh in pricetik_hotel_get_booking_url.

Retailer + booking URLs wrapped in /go/{click_id} redirects.

End user clicks /go/ URL → browser/server-fetch classification → 302 redirect to retailer or PriceTik checkout.

Retail: click → conversion match against the affiliate network. Hotels & events: booking completed on PriceTik checkout.

Anomaly detection worker runs hourly, flags suspicious consumers and rewards converting fingerprints with lifted hotel throttles.

Changelog

PriceTik MCP follows semantic versioning. Breaking changes are announced at least 30 days in advance.

v0.25.0May 2026Latest

•Lighthouse 100 across the board — `/mcp-server` and homepage now both score 100 / 100 / 100 / 100 (Accessibility / Best Practices / SEO / Agentic Browsing) on desktop and mobile, up from 92 / 96 respectively. Fix shipped over the design tokens in `apps/web/src/app/globals.css`: `--color-text-muted` `#9ca3af → #5b6370` (4.69:1 → 5.10:1 against bg), `--color-brand-primary` `#10b981 → #047857` (2.44:1 → 6.05:1), `--color-brand-secondary` `#3b82f6 → #1d4ed8`, plus AA-aligned status colors. Vertical accent text (`text-blue-500`, `text-amber-400`, `text-emerald-400`, `text-violet-400`, `text-pink-400`, `text-rose-500`, `text-cyan-500`) bumped to `-700` shades on every page. Heading order fixed in `SurfaceCards` (h3 → h2). Sidebar TOC links now meet WCAG 2.2 AA target-size (24×24 minimum). LiveTickerWithHotels animation drops opacity transition so motion-mid contrast scoring is solid.
•Master agent-API surface count unchanged: 61 tools across Shopping (17), Hotels (16), Events (7), Account (13), Trip Planner (4), Reference (4).

v0.24.0May 2026

•`/mcp-server` page refactor — extracted ~2,100 lines of static data (TOC groups, tool catalogs, tool-response examples, marketing examples, reference tables, changelog) out of `apps/web/src/app/(public)/mcp-server/page.tsx` into a focused `_data/` directory. The page is now pure composition at 1,302 lines (was 3,384). Six modules: `toc.ts`, `marketing-examples.ts`, `tool-examples.ts` (every EX_* response shape), `tool-catalogs.ts` (per-vertical tool definitions), `reference.ts` (workflows / error codes / feature flags / architecture / abuse controls / cert boundary), `changelog.ts`. Barrel export at `_data/index.ts` keeps the page imports tidy.
•Master agent-API surface count unchanged: 61 tools across Shopping (17), Hotels (16), Events (7), Account (13), Trip Planner (4), Reference (4).

v0.23.0May 2026

•Coverage map generator — new script `packages/mcp-server/scripts/generate-coverage-map.ts` introspects the live `TOOL_DEFINITIONS` array and emits `docs/mcp-coverage-map.generated.md` with per-vertical tool tables (name + method + path). Path-prefix heuristics first, name-prefix fallbacks, anything unmapped lands in "Reference / cross-cutting" so unmapped tools surface visibly. Run via `pnpm --filter @pricetik/mcp-server gen:coverage-map`.
•Demand-pulse activity tests — new `apps/api/src/routes/intel/__tests__/demand-pulse.test.ts` covers the response composition (intensity bucketing, headline copy variants, activity-name enrichment, fallback messaging). 12 unit tests on the pure `buildPulseResponse` helper, exported from the route module specifically for testability. Catches headline-copy drift before it ships.
•Master agent-API surface count unchanged: 61 tools across Shopping (17), Hotels (16), Events (7), Account (13), Trip Planner (4), Reference (4).

v0.22.0May 2026

•Public homepage stats endpoint — new `GET /api/v1/intel/platform-stats` returns live merchant / hotel-property / event-destination counts plus the SSOT MCP tool counts. Cached 1h in Redis, falls back to `MCP_STATS` constants on DB hiccup. New `PLATFORM_STATS_ENABLED` feature flag (default on). The marketing homepage now SSR-fetches from this endpoint with a 10-minute revalidate so the stats bar renders real numbers instead of static fallbacks.
•Feature-flag dashboard panel on `/admin/intel/metrics` — read-only resolved-state view of every `getIntelFeatureFlags()` flag with env-var name and on/off pill. Filterable by enabled / disabled / all, links out to the existing `/admin/feature-flags` page for toggling. Backed by new `GET /admin/intel/feature-flags` endpoint that derives the list from the flag service so new flags show up without registering.
•Tool-metrics admin endpoint — new `GET /admin/intel/tool-metrics` returns the per-tool latency + error-rate dashboard data the existing metrics page was already trying to render. Reads `summariseAllEndpoints()` from the Redis-backed 1h rolling window. The dashboard now actually has data.
•Activity travel-date column on `intel_queries` — migration 0081 adds `activity_travel_date` plus a partial composite index `(activity_code, activity_travel_date, queried_at DESC)`. All six activity routes log the `from` date alongside `activityCode`. The demand-aggregate worker pivots on persisted travel date instead of `queried_at::date`, so per-show-date demand stays in distinct buckets. `pricetik_demand_pulse` accepts an optional `travelDate` filter.
•Master agent-API surface count unchanged: 61 tools across Shopping (17), Hotels (16), Events (7), Account (13), Trip Planner (4), Reference (4).

v0.20.0May 2026

•Activity demand-aggregate rollup — `pricetik_demand` now answers `targetType: "activity"` queries. Migration 0080 adds `intel_activity_demand_signals` (mirror of the hotel rollup table). The `intel-demand-aggregate.worker.ts` job grew an activity branch alongside the hotel branch — every 15-minute pass groups `intel_queries.activity_code` rows by `(activityCode, travelDate)`, gates on the same ≥3 unique fingerprint threshold, and inserts one row per tuple that meets the threshold.
•New `getActivityDemand(...)` service reads the latest signal for a `(activityCode, travelDate)` tuple. Same Pro+ tier gate as the hotel branch. Returns `uniqueAgentCount`, `totalQueryCount`, `medianTargetPrice`, `topTargetPriceModes`, and a bucketed `priceDistribution` matching the hotel response schema.
•Daily prune extended — `intel-db-maintenance.worker.ts` now also prunes `intel_activity_demand_signals` rows older than 15 days. Same retention window as the hotel rollup so any future "demand history" surface can join both tables.
•`pricetik_demand` validator extended — `targetType: "activity"` requires `activityCode` + `travelDate` and rejects `productId` / `checkIn` / `checkOut`. Existing `targetType: "product"` and `targetType: "hotel"` callers stay backwards-compatible.
•9 new unit tests on the rollup helpers (threshold gate, grouping, median + modes + buckets, window stamps).
•Master agent-API surface count unchanged: 61 tools across Shopping (17), Hotels (16), Events (7), Account (13), Trip Planner (4), Reference (4).

v0.19.0May 2026

•Activity watch-rate worker — `pricetik_activity_watch_rate` alerts now actually fire. The new BullMQ worker (`activity-watch-rate.worker.ts`) scans active alerts every 30 minutes, groups by `(activityCode, travelDate, pax, currency)` so a single Hotelbeds availability call serves every alert in the group, and forwards each group to the new `evaluateActivityAlertsForCode(...)` evaluator.
•New per-alert rate cache (Redis, 30-day TTL) tracks last-observed price + availability so `activity_price_drop_percent` can compute deltas and `activity_availability_in_window` can detect sold-out → available transitions across pass boundaries.
•New `evaluateActivityConditions(...)` evaluator with cross-surface isolation — retail and hotel evaluators skip activity_* conditions and vice versa, defense in depth on top of the SQL XOR check.
•Webhook delivery shared with retail + hotel — same HMAC-SHA256 signing, 1m / 5m / 30m retries, disable-after-3-failures path. New `ActivityAlertWebhookPayload` shape carries `currentPricePerPerson`, `previousPricePerPerson`, `available`, and the `activityTarget` block.
•New env flag `DISABLE_ACTIVITY_WATCH_RATE=true` to drop the worker during incidents without disabling the alert-creation route. 22 unit tests on the new evaluator + grouping + snapshot helpers.
•Master agent-API surface count unchanged: 61 tools across Shopping (17), Hotels (16), Events (7), Account (13), Trip Planner (4), Reference (4).

v0.18.0May 2026

•pricetik_my_loyalty_link_set — write half of the loyalty-link surface. Body `{ program, memberId }` upserts the program (replace by case-insensitive match, else append); body `{ program, delete: true }` removes it. The `traveler_profiles` row is created on first call so a brand-new user can link Marriott Bonvoy mid-conversation without a separate `pricetik_traveler_profile_set` round-trip. Response carries the updated `loyaltyPrograms` array + an `action` field (`appended` / `replaced` / `removed` / `noop`) so retries are detectable.
•Master agent-API surface count: 61 tools across Shopping (17), Hotels (16), Events (7), Account (13), Trip Planner (4), Reference (4).

v0.17.0May 2026

•pricetik_get_cashback_rate — read-only resolution of the cashback rate a user would earn for a retailer. Pass `retailer`, `productId`, or `url` (exactly one). Optional `price` adds a USD `estimatedCashback` projection. Auth optional — Pro callers receive the 1.25× share-rate multiplier (capped at 100%). Returns rate=0 with `meta.isFallback=true` when no active affiliate config exists for the retailer, so agents can quote "no cashback active for this retailer" rather than leaving the user wondering.
•pricetik_activity_compare — mirror of pricetik_hotel_compare for Hotelbeds activities. Compare 2–4 codes side-by-side: name, type, cheapest fromAmount, freeCancellation flag, modalitiesCount, meetingPoint, and a 0–100 dealScore per activity. The winner block picks the highest dealScore (ties broken by fromAmount ascending) so the agent can quote a clear pick.
•Per-tool feature flag `GET_CASHBACK_RATE_ENABLED` (default `true`). Activity-compare reuses the existing `ACTIVITIES_V1_ENABLED` master.
•Master agent-API surface count: 60 tools across Shopping (17), Hotels (16), Events (7), Account (12), Trip Planner (4), Reference (4).

v0.16.0May 2026

•Worked-example responses on every tool card. The remaining ~50 cards (Shopping 12, Hotels 13, Events 6, Account 12, Trip Planner 3, Reference 3) now have a collapsible "Example response" block on `/mcp-server` showing the JSON shape an agent receives. Realistic sample IDs throughout — `550e8400-...` for product UUIDs, `16914` for Hotelbeds property IDs, `E-E10-A1GMNO0125` for activity codes.
•Added missing tool cards on `/mcp-server` for `pricetik_demand_pulse` (Reference), `pricetik_my_loyalty_link` (Account), and `pricetik_alert_rotate_secret` (Account) — they shipped in v0.12.0 but had no card on the page yet.
•Master agent-API surface count unchanged: 58 tools across Shopping (17), Hotels (16), Events (6), Account (12), Trip Planner (4), Reference (3).

v0.15.0May 2026

•`pricetik_demand_pulse` now works for activity targets — previously returned zero for `target=activity` because `intel_queries` had no activity column. Migration 0079 adds an `activity_code varchar(80)` column, a partial index `idx_intel_queries_activity_code` on `(activity_code, queried_at DESC)` filtered by `target_type = 'activity'`, and extends the `target_type` CHECK to include `'activity'`.
•Activity routes (`activity-search`, `activity-details`, `activity-deal-score`) now call `logIntelQuery` with `targetType: 'activity'` and `activityCode`. `activity-search` logs the first 10 results per call so a single search seeds the pulse for the whole result set.
•Headline enrichment — activity pulses now read the cached display name from a new `pricetik:activity:name:{code}` Redis key (24h TTL, populated on every activity-search / activity-details / activity-deal-score call). Output reads "8 people are looking at this Cirque du Soleil show right now" instead of the generic "8 viewers in the last 60s." Cache miss falls back to "this show" so the headline still composes.
•New `targetName` field on the response — null when the cache misses, populated when present, ignored on hotel/product targets today.
•Master agent-API surface count unchanged: 58 tools across Shopping (17), Hotels (16), Events (6), Account (12), Trip Planner (4), Reference (3).

v0.14.0May 2026

•Activity-target column on `intel_alerts` — activities now persist via the dedicated `target_type = 'activity'` branch with a structured `activity_target` JSONB payload `{ activityCode, travelDate, adults, children }`. The synthetic-UUID indirection (where activity codes were hashed to a UUID and stored as `productId`) is gone, and the worker can now look up alerts by `((activity_target->>'activityCode'))` via a partial index.
•New `createActivityAlert(...)` helper in `intel-alert.service.ts` mirrors the shape of `createHotelAlert` — Pro+ tier check, default `expiresAt = travelDate - 24h`, shared per-tier alert-count budget. The legacy `createAlert(...)` is now `@deprecated` for activity callers (still works for retail).
•`pricetik_activity_watch_rate` route now calls `createActivityAlert` instead of `createAlert` with a synthetic UUID. The idempotency-key path stays unchanged. Response carries the structured travel context (travelDate, adults, children) the worker will need at fire time.
•Migration `0078_intel_alerts_activity_target.sql` extends the `target_type` enum, adds the `activity_target` JSONB column, rewrites the `intel_alerts_target_xor` CHECK to cover three branches (product / hotel / activity), and adds the `idx_intel_alerts_activity_code` partial index.
•Master agent-API surface count unchanged: 58 tools across Shopping (17), Hotels (16), Events (6), Account (12), Trip Planner (4), Reference (3).

v0.13.0May 2026

•Loyalty injection on the booking-url handoff — when the caller is authenticated and a stored loyalty program (`traveler_profiles.loyaltyPrograms`) matches the property's `chainCode`, `pricetik_hotel_get_booking_url` now stamps the signed `pricetik.com/hotels/live/...` URL with `?loyalty=<chainCode>&loyaltyMember=<id>`. Response carries a new `loyaltyApplied: { program, memberId } | null` block so agents can quote "Marriott Bonvoy linked" to the user. Consumer checkout shows a "linked" badge above the lead-booker fields.
•Per-tool kill switch `LOYALTY_INJECTION_ENABLED` (default `true`) — flip to drop just the loyalty stamping during chain-loyalty incidents without disabling the booking-url tool itself.
•Best-effort lookup — booking-URL still succeeds when the property has no chain affiliation, the user has no traveler-profile row, or the database read fails. Loyalty is additive; it never blocks a booking handoff.
•Master agent-API surface count unchanged: 58 tools across Shopping (17), Hotels (16), Events (6), Account (12), Trip Planner (4), Reference (3).

v0.12.0May 2026

•pricetik_demand_pulse — real-time presence indicator. Returns unique-viewer + query counts for a hotel/product/activity over the trailing 60s window. Powers "12 people are looking at this hotel right now" prompts.
•pricetik_alert_rotate_secret — rotate the HMAC signing secret on the developer-API-key row. Mirrors the existing key-rotation pattern. Auth required.
•pricetik_my_loyalty_link — read-only convenience tool over `traveler_profiles.loyaltyPrograms`. Saves a round-trip vs `pricetik_traveler_profile_get` when the agent only needs the loyalty block.
•Idempotency-Key support on `pricetik_hotel_watch_rate` and `pricetik_activity_watch_rate` — retries are now safe; same 24-hour replay window as the booking-url tools.
•Worked-example responses on every high-traffic tool card. Click "Example response" on price_check, should_buy, deal_score, search, hotel_search, hotel_price_check, hotel_booking_url, trip_plan to see the JSON shape an agent gets back.
•Per-tool feature flags for demand_pulse, alert_rotate_secret, my_loyalty_link.
•Master agent-API surface count: 58 tools across Shopping (17), Hotels (16), Events (6), Account (12), Trip Planner (4), Reference (3).

v0.11.0May 2026

•pricetik_check_availability — lightweight rateKey probe via Hotelbeds /checkrates. Cuts the booking flow by 1 round-trip vs. pricetik_hotel_price_check.
•pricetik_hotel_review_summary — synthesised review summary with theme cues for cleanliness, location, staff, value, and comfort. Cache-only; theme cues are inferred from cached amenity content.
•pricetik_activity_pickup_check — pickup + meeting-point detail for an activity. Returns hasPickup boolean, meetingPoint, and the list of modalities that include pickup.
•pricetik_my_savings_report — authenticated savings breakdown (lifetime, YTD, per-month, top fills, per-surface).
•pricetik_search — now cross-vertical: pass surface=shopping|hotels|events|all to fan out across all three surfaces with round-robin merging.
•Per-tool feature flags for check_availability, hotel_review_summary, activity_pickup_check, my_savings_report.
•Master agent-API surface count: 55 tools across Shopping (17), Hotels (16), Events (6), Account (10), Trip Planner (4), Reference (2).

v0.10.0May 2026

•pricetik_currency_convert — single-amount + batch endpoints converting between any two ISO 4217 currencies. Cache-only — same Redis FX cache the hotel and activity surfaces share. Up to 100 amounts per batch call.
•pricetik_weather_forecast — daily forecast for a destination + date window. Open-Meteo upstream (free, no API key, ~16-day horizon). Returns per-day highs/lows/precip/wind plus aggregate stats and a headline summary. Pairs with pricetik_hotel_should_book.
•New "Reference Tools" section on /mcp-server with TOC entry. Both new tools sit alongside Trip Planner.
•Per-tool feature flags for currency_convert and weather_forecast.
•Master agent-API surface count: 51 tools across Shopping (17), Hotels (14), Events (5), Account (9), Trip Planner (4), Reference (2).

v0.9.0May 2026

•pricetik_explain_price — decompose a hotel total into base rate + taxes & fees + paid amenities (resort fee, parking) + seasonal premium. Pure cache read.
•pricetik_alternative_dates — anchored ±N-day shifts of an intended check-in. Returns alternatives ranked by savings vs. the requested window.
•pricetik_room_types — filtered, ranked room catalog for a property. Reads cached hotel_property_content.rooms and joins cheapest cached rate when a stay window is supplied. Filter by bedType, suite, kitchenette, accessible, minAdults.
•pricetik_cancel_booking — cancel a completed direct booking the user owns. Calls the provider DELETE, refunds the Stripe charge, marks the row cancelled.
•pricetik_modify_booking — surfaces 422 ModifyNotSupported with a `nextSteps` payload describing the cancel + rebook flow (Hotelbeds doesn't support real modifications).
•pricetik_traveler_profile_get/_set — stored per-user travel preferences (preferred chains, excluded chains, segments, bed type, star floor, resort-fee/breakfast/pet flags, max nightly rate, loyalty programs). Pass applyTravelerProfile=true on hotel_search and trip_plan to soft-merge prefs over caller params.
•Per-tool feature flags for explain_price, alternative_dates, room_types, booking_lifecycle, traveler_profile.
•Master agent-API surface count: 49 tools across Shopping (17), Hotels (14), Events (5), Account (9), Trip Planner (4).

v0.8.0May 2026

•Hotel-search filter expansion — excludeResortFees (now a real SQL NOT EXISTS against hotel_property_content.paid_amenities, no more flaky heuristic), excludeChainCodes (inverse of chainCode), freeBreakfast, petFriendly, minNightlyRate, and POI-pin filters (nearPoiLat / nearPoiLng / nearPoiRadiusKm) so agents can pin a search to "the Strip" rather than the Vegas centroid.
•pricetik_flexible_dates — "find the cheapest weekend in June" via the cached hotel_price_history hypertable. Tier-clamped windows (Open ≤ 30 days, Pro ≤ 90, Scale+ ≤ 180); each candidate carries a high/low confidence flag.
•pricetik_compare_destinations — apples-to-apples "Cabo vs Tulum" comparison: median 4★ rate, top-3 hotels by deal score, top-3 activities, and seasonal-premium flag (event-window markers like "F1 weekend in Vegas — rates 65% above baseline"). Stricter rate cap of 10/min.
•pricetik_my_trips — group bookings into actual trip objects (destination + overlapping windows), with total spend, days-until-departure countdown, and per-member manage URLs.
•pricetik_trip_plan v2 — opt-in daily itinerary via groupByDay=true. Conflict avoidance for 4h+ activities + rest-day placeholders for trips longer than 5 nights. Resort-fee filter now SQL-backed, not a post-fetch heuristic.
•Idempotency-Key support on pricetik_hotel_get_booking_url and pricetik_activity_get_booking_url — 24-hour replay window keyed on (fingerprint, route, key). Replays return Idempotency-Replay: true.
•NDJSON streaming opt-in — pass `?stream=ndjson` (or `Accept: application/x-ndjson`) on pricetik_hotel_search, pricetik_trip_plan, and pricetik_compare_destinations to receive frames incrementally as they materialize. Cuts perceived TTFB on cache-miss searches from ~3s to <50ms.
•Per-tool feature flags for trip-plan, compare-destinations, hotel-flex-dates, my-trips so ops can drop just one tool during incidents.
•Tool-level metrics dashboard at /admin/intel/metrics — Redis-backed 1-hour rolling window. Surfaces per-tool call counts, p50/p95/p99 latency, error rates, and last-sample-seen timestamps. Powers incident triage without spinning up ClickHouse.
•@pricetik/mcp-server published to npm — npx @pricetik/mcp-server now works without a 404. SDK quickstarts on this page cover TypeScript, Python, and curl.
•Master agent-API surface count: 43 tools across Shopping (17), Hotels (11), Events (5), Account (6), Trip Planner (4).

v0.7.0May 2026

•Trip Planner MCP — pricetik_trip_plan stitches hotel + activity search + budget allocation into one call. Powers prompts like "find me the cheapest hotel in Vegas, no resort fees, plus fun events" without 4–6 sequential tool calls.
•Destinations resolver — pricetik_destinations converts free-text ("Las Vegas") into the canonical shape every other tool needs (hotel-search-friendly text, Hotelbeds 3-letter activity code, country, lat/lng).
•Activity watch-rate — pricetik_activity_watch_rate mirrors hotel watches: targetPricePerPerson, dropPercent, dealScoreAbove, notifyOnAvailability triggers; auto_book action mode honored when API key has directBookingEnabled=true.
•My-watches tool — pricetik_my_watches consolidates every active alert (hotel, activity, shopping) under the user's account into one human-readable list. Each row includes a prettified conditions array agents can quote verbatim.
•Hotel watch-rate enhanced — now accepts targetNightlyRate / dropPercent / dealScoreAbove as OR-conditions in one call, plus optional action="auto_book". Existing single-condition callers stay backwards-compatible.
•Alert condition vocabulary expanded: hotel_rate_drop_percent, hotel_deal_score_above, hotel_availability_in_window, activity_price_below, activity_price_drop_percent, activity_availability_in_window.
•Master agent-API surface count: 40 tools across Shopping (17), Hotels (10), Events (5), Account (6), Trip Planner (2).

v0.6.0May 2026

•Account MCP — 5 new authenticated tools: pricetik_my_bookings (list trips), pricetik_my_booking_voucher (single-booking detail with confirmation #, address, cancellation policy), pricetik_my_account (plan + lifetime stats), pricetik_my_payment_methods (masked card list), pricetik_update_payment_method (Stripe Customer Portal handoff). Powers conversational lookup like "pull up my Wynn voucher" and "update my card."
•PCI scope-out: pricetik_update_payment_method returns a Stripe-hosted URL — raw card data never enters the agent runtime.
•Direct booking groundwork — agent_direct_bookings table + email-confirmation handshake routes shipped behind feature flag. Stripe + provider settlement still pending.
•API key dashboard — users can now mint, name, revoke, and toggle direct-booking permission on keys at /api-keys (no Stripe subscription required).

v0.5.0May 2026

•Tickets MCP — 4 new tools wrapping Hotelbeds Activities: pricetik_activity_search, pricetik_activity_details, pricetik_activity_deal_score, pricetik_activity_get_booking_url.
•Activity prices auto-convert EUR → USD (or any ISO 4217 target) using the same exchange-rate cache the hotel surface relies on; source quote always preserved on `originalCurrency`/`originalFromAmount`.
•New error code: 503 ActivityToolDisabled when ACTIVITIES_V1_ENABLED kill switch is off.

v0.4.0May 2026

•Hotels MCP — Phase 2: pricetik_hotel_get_booking_url generates signed pricetik.com/go/ booking URLs with rateKey refresh.
•Hotels MCP — Phase 2: pricetik_hotel_watch_rate webhook alerts fire when cross-provider best nightly rate drops below target.
•pricetik_demand extended to accept hotel UUIDs via targetType=hotel.
•Per-fingerprint sliding-window abuse caps (60/min, 1,000/hour) on every surface.
•New error code: 410 RateKeyExpired for stale hotel rate handles.

v0.3.0April 2026

•Hotels MCP — Phase 1: pricetik_hotel_details surfaces full property content (description, amenities, paid extras, POIs, rooms, chain, contact).
•Hotels MCP — Phase 1: pricetik_hotel_rate_history with deterministic OLS trend slope.
•Hotels MCP — Phase 1: pricetik_hotel_should_book deterministic recommendation engine.
•Hotels MCP — Phase 1: pricetik_hotel_compare for 2–4 properties in one call.
•pricetik_hotel_search adds segments, chainCode, accommodationType filters.
•Richer response shaping for hotel-price-check (full content depth on every request).

v0.2.0March 2026

•Added pricetik_compare tool for side-by-side product comparison
•Added pricetik_batch_price_check for multi-product price checks
•Added pricetik_alert_update for modifying existing alerts
•Spread analysis and confidence intervals added to deal-score response
•Webhook payload format documented with HMAC-SHA256 signature verification
•Initial three hotel tools shipped: pricetik_hotel_search, pricetik_hotel_price_check, pricetik_hotel_deal_score.

v0.1.0February 2026

•Initial release with 12 Shopping MCP tools
•Free for every agent — no API key required
•Attribution system with /go/ redirect tracking
•Webhook alerts with 4 condition types
•Anti-scraping anomaly detection

PriceTik MCPOne server. Three surfaces. Every LLM.

Real-time retail prices

Search, compare, book

Tours, attractions & excursions

One-Click Install

Three steps. Sixty seconds.

Get your API key

Configure your AI tool

Restart & verify

Try the live API

SDK quickstarts

Shopping MCP

Shopping Tools

Core

Intelligence

Alerts

Alert Condition Types

Access & limits

Abuse controls

Hotels MCP

Hotel Tools

Discovery & content

Decision intelligence

Booking & alerts

A typical hotel agent workflow

Provider certification boundary

Tickets MCP

Ticket Tools

A typical ticket agent workflow

Trip planner tools

Trip Planner Tools

Reference Tools

Watch & alert tools (enhanced)

Account tools

Account Tools

Authentication

Key Management Endpoints

OpenAPI Spec

Response Format

Streaming (NDJSON)

Error Codes

Rate Limiting

Webhook Payloads

Attribution System

Feature Flags

Architecture Overview

Changelog

PriceTik MCPOne server. Three surfaces. Every LLM.

Real-time retail prices

Search, compare, book

Tours, attractions & excursions

One-Click Install

Three steps. Sixty seconds.

Get your API key

Configure your AI tool

Restart & verify

Try the live API

SDK quickstarts

Shopping MCP

Shopping Tools

Core

Intelligence

Alerts

Alert Condition Types

Access & limits

Abuse controls

Hotels MCP

Hotel Tools

Discovery & content

Decision intelligence

Booking & alerts

A typical hotel agent workflow

Provider certification boundary

Tickets MCP

Ticket Tools

A typical ticket agent workflow

Trip planner tools

Trip Planner Tools

Reference Tools

Watch & alert tools (enhanced)

PriceTik MCP
One server. Three surfaces. Every LLM.

PriceTik MCP
One server. Three surfaces. Every LLM.