MagicSearch

Provider Index

MagicSearch is a commerce provider index built for agents, not a browser search page built for humans. The index can contain human-curated providers, automatically discovered providers, trust information, supported countries, merchant domains, checkout entry points, provider tags, historical purchase signals, and payment method records. The goal is to answer the agent quickly: which provider should handle this intent, which channel should be used, and whether the workflow can continue through an API or should hand off to MagicBrowse.

// Simplified shapes — see @mercuryo-ai/magicsearch for the full types.type MagicSearchProviderRecord = {  id: string;  name: string;  description: string | null;  category: string | null;  enabled: boolean;  status: 'active' | 'paused' | 'deprecated';  domains: string[];  searchTerms: string[];  intentTypes: string[];  categories: string[];  tags: string[];  score: number;  metadata: Record<string, unknown>;}; type MagicSearchPurchaseMethodRecord = {  id: string;  providerId: string;  type: 'x402' | 'mcp' | 'api' | 'reversed_api' | 'browser';  status: 'active' | 'experimental' | 'paused';  metadata: Record<string, unknown>;};

Agent Query Interface

Agents query MagicSearch with the user request plus structured hints. The query can include merchant, domain, product, category, country, region, place, intent type, checkout shape, quote requirements, authentication context, and preferred method types. MagicSearch normalizes those inputs into a provider query and a discovery query, so the agent does not need to open a browser just to find the right starting point.

import { createRemoteMagicSearchClient } from '@mercuryo-ai/magicsearch'; const search = createRemoteMagicSearchClient({  apiUrl: process.env.MAGICPAY_API_URL!,  apiKey: process.env.MAGICPAY_API_KEY!,}); const result = await search.query({  query: 'Book a hotel in Lisbon for May 10 to 12',  purpose: 'checkout',  hints: {    merchantHint: 'Booking.com',    category: 'hotel',    country: 'PT',    placeHint: 'Lisbon',  },  providerQuery: {    intentType: 'booking',    preferredMethodTypes: ['mcp', 'api', 'browser'],    quoteRequirements: ['dates', 'room', 'refund policy'],  },});

Payment Methods

A provider can expose multiple payment methods. MagicSearch scores the compatible methods before the workflow starts, so the agent can prefer the fastest and most agent-native channel while still falling back to legacy commerce when needed.

Scoring

Provider scoring combines evidence about the provider and evidence about the method. Exact merchant or domain matches rank highest. Vertical matches such as hotel or flight providers beat loose text matches. Intent, category, tag, country, region, and product hints help narrow the catalog. Payment method scoring then favors x402, MCP, API, reversed API, and browser in that order, with a small bonus for method types requested by the agent. Low-confidence matches fall back to discovery instead of pretending the index knows the answer.

• Only active and enabled provider entries can be selected.
• A strong provider match needs exact provider evidence, vertical evidence, intent/category evidence, or enough trusted metadata.
• If the selected provider has no compatible active payment method, MagicSearch falls back to discovery.
• Scores improve routing, but they never bypass user approval, MagicPay policy, or Memory-managed payment requests.

Result Shape

MagicSearch returns the route the agent should use next. A provider-index result can carry the selected provider, selected method, confidence, and direct URL. If the method can complete the payment through API, the backend can continue there. If the method is browser checkout, the URL becomes the start point for MagicBrowse.

// Simplified shape — see @mercuryo-ai/magicsearch for the full type.type MagicSearchUrlResult = {  url: string;  source: MagicSearchResultSource;  title: string | null;  query: string;  confidence: 'high' | 'medium' | 'low';  provider: {    id: string;    name: string | null;    methodId: string | null;    methodType: 'x402' | 'mcp' | 'api' | 'reversed_api' | 'browser' | null;    confidence: 'high' | 'medium' | 'low' | 'none';  } | null;  choices?: MagicSearchChoiceOption[];};

Choice Request

When MagicSearch finds several plausible items, providers, hotels, flights, products, or checkout targets, it can pause the workflow with a MagicPay choice request. The user picks the option that matches their intent instead of forcing the agent to guess. The user can also add notes, such as a preferred room type, delivery constraint, budget, or merchant preference; MagicSearch can use those notes as adjusted search input and continue the job with better context.

• Choice options can include title, subtitle, description, URL, price, images, and characteristics.
• The agent receives the selected option and can continue with the selected checkout URL.
• Choice requests are especially useful for travel, tickets, restaurants, products, and services where the phrase “best option” depends on user preference.

Search Fallback

If the provider index has no match, has only a low-confidence match, or has a provider without a usable URL, MagicSearch falls back to agentic web discovery using web search providers. The fallback result gives MagicBrowse a better starting URL than a blank browser search, and multiple fallback results can become choice options for the user.

• Fallback is a recovery path, not the primary product model.
• The discovery query is built from the prompt plus merchant, product, domain, category, geography, and purchase-purpose hints.
• MagicBrowse starts from the returned provider, product, or checkout page instead of browsing like a human from the homepage.

Related Docs