Integrate Shopping & Travel Search into Your Agent

Overview

IntentLink is a commerce intent network that lets an AI agent search two kinds of inventory — general shopping and travel — and return results that already include a monetized, trackable purchase link. Both integration paths (MCP and REST) call the same two underlying services, so pick based on how your agent is built, not based on which one is “more complete”:

Every result — from either service, through either integration path — includes a purchase link that’s ready to hand to the end user, plus a non-tracked fallback link in case a trackable one couldn’t be generated for that specific offer.

Authentication: Your agent_id

There’s no separate API key or bearer token. Instead, every call — MCP tool call or REST request — includes an agent_id: a registered, activated identifier you get when you sign up on the developers page. It does two jobs at once:

• Admission key — calls from an unregistered or inactive agent_id are rejected.
• Attribution key — any resulting click or purchase is automatically credited back to your account.

Choosing an Integration Path

Both paths call the exact same underlying search logic, so there’s no difference in result quality or ranking between them — nothing is MCP-only or REST-only in terms of capability.

MCP Integration

Connection details

Once connected, your agent calls tools/list and receives full parameter schemas and usage guidance automatically — you generally don’t need to hand-write integration logic per tool. Two tools are available today:

Don’t mix the two companion resources — the category list is only relevant to search_products, and the city list only to search_travel.

// Connect from Claude — add IntentLink as a remote MCP server
{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "mcp_servers": [
    { "type": "url", "name": "intentlink-shopping", "url": "https://api.intentlink.tech/mcp" }
  ],
  "messages": [
    { "role": "user", "content": "Find a good running shoe for my wife under $120 and give me the buy link. My agent_id is agt_your_agent_id." }
  ]
}

Using Claude Desktop or connectors? Add the same endpoint URL as a remote MCP server (Streamable HTTP) directly in the connector settings — no code required.

search_products parameters

Returns a products array; each item includes display fields (title, brand, price, rating, review count) plus a ready-to-use buy_url and a fallback product_url.

search_travel parameters

Only type=hotel runs a real-time availability search; other types return curated default links. Returns a links object grouped by type, each entry including a ready-to-use buy_url and fallback destination_url.

REST API: Shopping Search

POST /api/v1/shopping/search
{
  "query": "a warm waterproof jacket for winter hiking",
  "caller": { "agent_id": "agt_your_agent_id" }
}

query is the only required field besides caller.agent_id — everything else is optional and simply improves precision: keywords, commerce_l2s, max_price/min_price, platforms, in_stock, country (defaults to US), require_commission, and sorting via intent or fine-grained ranking.

REST API: Travel Search

How it differs from Shopping Search: travel is a “link” category rather than a product feed — there’s no unified pricing across a ranked offer list. Instead, you get curated, trackable links grouped by type. type and city are both required (shopping only requires a free-text query).

POST /api/v1/travel/search
{
  "type": "hotel",
  "city": "New York",
  "hotel": { "check_in": "2026-08-01", "check_out": "2026-08-03", "rooms": 1, "adults": 2, "children": 0, "state": "NY" },
  "caller": { "agent_id": "agt_your_agent_id" }
}

# Minimal request — other categories (curated default links)POST /api/v1/travel/search
{ "type": "flights", "city": "New York", "caller": { "agent_id": "agt_your_agent_id" } }

{
  "request_id": "req_...",
  "status": "ok",
  "reason": null,
  "links": {
    "hotel": [
      {
        "title": "Hotels — New York",
        "brand": "Example Hotels Co.",
        "platform": "example-travel-partner",
        "buy_url": "https://.../click-...",
        "destination_url": "https://www.example-travel-partner.com/..."
      }
    ]
  },
  "attribution": { "attribution_id": "attr_...", "click_id": "clk_...", "agent_id": "agt_your_agent_id" },
  "agent_message": "Returned 1 hotel link(s) for New York."
}

Brand and platform names above are illustrative — actual results reflect whichever travel supply partner served that offer.

status is one of: ok (real-time hotel results), fallback (curated default link — see reason), no_results, or error (e.g. an unregistered agent_id).

Only type=hotel triggers a live availability search, and it requires check_in/check_out in the hotel object (check_out must be after check_in). If a city name is ambiguous (multiple cities share a name), pass hotel.state to disambiguate — otherwise the search falls back to a default link automatically.

Writing Queries That Convert

A few patterns make a measurable difference in result quality, for both MCP and REST:

• Put context in query, not just a product name. Scenario and audience signals — “a gift for my wife who runs,” “warm waterproof jacket for winter hiking” — drive better matching than a bare product term.
• Use specific terms in keywords, never bare nouns. ["women running shoes"] is good; ["shoes"] is not — a bare noun can match the wrong audience's version of a product.
• Pick a sorting approach on purpose. Use an intent preset for common cases (cheapest, best_discount, top_rated, best_value), or fine-tune with explicit ranking dimensions (price, discount, commission rate, rating, review count, availability). Specify neither, and results default to best_value.
• For travel, disambiguate cities when names repeat. Use hotel.state for cities like “Springfield” that exist in multiple states.

Responses, Links & Attribution

Every result — shopping or travel, MCP or REST — includes a purchase link that’s already trackable and ready to hand to the end user (buy_url in MCP responses and travel REST responses; affiliate_url in shopping REST responses). There is no separate “activate” or “resolve” step. As a fallback, each result also includes an untracked link to the original product or destination page, used on the rare occasion a trackable link couldn’t be generated for that specific offer.

Attribution runs on your agent_id: each search generates a shared attribution record so that any resulting click or conversion is credited back to your account automatically.

Reliability & Performance

Fast by default. Typical end-to-end search latency is under 1 second at the 90th percentile (p90 < 1s), across both MCP and REST.

Both services are also built to degrade gracefully rather than fail outright:

• If vector-based matching is temporarily unavailable (shopping), search automatically falls back to keyword-based matching.
• If a real-time hotel search can't resolve (ambiguous city, missing or invalid dates), it falls back to a curated default link rather than erroring — the response's status/reason fields tell you why.
• Genuinely empty results return a clear no_results status instead of a 500 error.
• An unregistered or inactive agent_id returns a clear error status rather than a silent failure.
• Offers without a valid purchase link are filtered out rather than handed to your agent as a dead end.

FAQ