MCP Query Tools Reference

The Query API MCP server provides 5 tools for querying consented user data. Each tool maps 1:1 to a Query API sync endpoint.

Tools use session credentials by default (provided during connection). You can override per-tool by passing auth_token and uid parameters.

Tool: get_search_data

Retrieve user search history (Google searches).

Parameters

Parameter	Type	Required	Description
`auth_token`	string	No*	Base64-encoded JWT (starts with `eyJ...`). Not the user ID.
`uid`	string	No*	Consented user ID (typically starts with `psub_`). Not the auth token.
`begin`	string	No	Start time filter (ISO 8601)
`end`	string	No	End time filter (ISO 8601)
`ingested_begin`	string	No	Ingestion start (for delta queries)
`ingested_end`	string	No	Ingestion end (for delta queries)
`category`	string	No	Filter by category (e.g., “/Shopping”)
`cursor`	string	No	Pagination cursor from previous response
`limit`	number	No	Max results per request (default 100, max 1000)

Either provide in tool call or use session credentials from connection

Response Format

{
  "success": true,
  "count": 2,
  "has_more": true,
  "next_cursor": "eyJsYXN0X2V2ZW50X2lkIjoxMjM0NX0=",
  "applied_ingested_end": "2024-01-15T10:30:00Z",
  "data": [
    {
      "event_id": 12345,
      "user_id": "psub_e5f6789012345678901234abcdef0123",
      "query": "best restaurants nearby",
      "title": "best restaurants nearby - Google Search",
      "url": "https://www.google.com/search?q=best+restaurants+nearby",
      "timestamp": "2024-01-15T10:30:00Z",
      "category": "/Food/Restaurants",
      "intent": "find",
      "brands": ["Google"],
      "ingested_at": "2024-01-15T11:00:00Z"
    },
    {
      "event_id": 12346,
      "user_id": "psub_e5f6789012345678901234abcdef0123",
      "query": "laptop deals",
      "title": "laptop deals - Google Search",
      "url": "https://www.google.com/search?q=laptop+deals",
      "timestamp": "2024-01-15T14:20:00Z",
      "category": "/Shopping/Electronics",
      "intent": "buy",
      "brands": ["Google"],
      "ingested_at": "2024-01-15T14:25:00Z"
    }
  ]
}

Example Usage

"Get search history from January 1-15, 2024, filtered by Shopping category"

Agent uses: get_search_data({
  "begin": "2024-01-01T00:00:00Z",
  "end": "2024-01-15T23:59:59Z",
  "category": "/Shopping",
  "limit": 100
})

Tool: get_youtube_data

Retrieve user YouTube watch history and interactions.

Parameters

Parameter	Type	Required	Description
`auth_token`	string	No*	Base64-encoded JWT (starts with `eyJ...`). Not the user ID.
`uid`	string	No*	Consented user ID (typically starts with `psub_`). Not the auth token.
`begin`	string	No	Start time filter (ISO 8601)
`end`	string	No	End time filter (ISO 8601)
`ingested_begin`	string	No	Ingestion start (for delta queries)
`ingested_end`	string	No	Ingestion end (for delta queries)
`category`	string	No	Filter by category (e.g., “/Music”)
`cursor`	string	No	Pagination cursor
`limit`	number	No	Max results per request

Either provide in tool call or use session credentials from connection

Response Format

{
  "success": true,
  "count": 1,
  "has_more": false,
  "next_cursor": null,
  "applied_ingested_end": "2024-01-15T10:30:00Z",
  "data": [
    {
      "event_id": 67890,
      "user_id": "psub_e5f6789012345678901234abcdef0123",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "title": "Example Video Title",
      "timestamp": "2024-01-15T10:30:00Z",
      "category": "/Entertainment/Music",
      "brands": ["YouTube"],
      "ingested_at": "2024-01-15T11:00:00Z"
    }
  ]
}

Example Usage

"Show me YouTube videos watched in the last 3 days"

Agent uses: get_youtube_data({
  "begin": "2024-01-12T00:00:00Z",
  "limit": 50
})

Tool: get_browsing_data

Retrieve user web browsing history (Chrome).

Parameters

Parameter	Type	Required	Description
`auth_token`	string	No*	Base64-encoded JWT (starts with `eyJ...`). Not the user ID.
`uid`	string	No*	Consented user ID (typically starts with `psub_`). Not the auth token.
`begin`	string	No	Start time filter (ISO 8601)
`end`	string	No	End time filter (ISO 8601)
`ingested_begin`	string	No	Ingestion start (for delta queries)
`ingested_end`	string	No	Ingestion end (for delta queries)
`category`	string	No	Filter by category (e.g., “/Shopping”)
`cursor`	string	No	Pagination cursor
`limit`	number	No	Max results per request

Either provide in tool call or use session credentials from connection

Response Format

{
  "success": true,
  "count": 1,
  "has_more": true,
  "next_cursor": "eyJsYXN0X2lkIjogNjc4OX0=",
  "applied_ingested_end": "2024-01-15T10:30:00Z",
  "data": [
    {
      "event_id": 45678,
      "user_id": "psub_e5f6789012345678901234abcdef0123",
      "url": "https://example.com/product",
      "title": "Product Page - Example Store",
      "timestamp": "2024-01-15T10:30:00Z",
      "category": "/Shopping",
      "page_category": "/Shopping/Electronics",
      "brands": ["Example Store"],
      "ingested_at": "2024-01-15T11:00:00Z"
    }
  ]
}

Example Usage

"Find browsing history related to cooking recipes from last month"

Agent uses: get_browsing_data({
  "begin": "2023-12-15T00:00:00Z",
  "end": "2024-01-15T23:59:59Z",
  "category": "/Food/Recipes"
})

Tool: get_ads_data

Retrieve user ad interactions (clicks and views).

Parameters

Parameter	Type	Required	Description
`auth_token`	string	No*	Base64-encoded JWT (starts with `eyJ...`). Not the user ID.
`uid`	string	No*	Consented user ID (typically starts with `psub_`). Not the auth token.
`begin`	string	No	Start time filter (ISO 8601)
`end`	string	No	End time filter (ISO 8601)
`ingested_begin`	string	No	Ingestion start (for delta queries)
`ingested_end`	string	No	Ingestion end (for delta queries)
`category`	string	No	Filter by category
`cursor`	string	No	Pagination cursor
`limit`	number	No	Max results per request

Either provide in tool call or use session credentials from connection

Response Format

{
  "success": true,
  "count": 1,
  "has_more": false,
  "next_cursor": null,
  "applied_ingested_end": "2024-01-15T10:30:00Z",
  "data": [
    {
      "event_id": 23456,
      "user_id": "psub_e5f6789012345678901234abcdef0123",
      "url": "https://ads.example.com/click?id=abc123",
      "title": "Shop Electronics - Example Brand",
      "source_domain": "news.example.com",
      "landing_domain": "shop.examplebrand.com",
      "ad_network": "Google Ads",
      "timestamp": "2024-01-15T10:30:00Z",
      "category": "/Shopping/Electronics",
      "brands": ["Example Brand"],
      "ingested_at": "2024-01-15T11:00:00Z"
    }
  ]
}

Example Usage

"Show me ad interactions from the last week"

Agent uses: get_ads_data({
  "begin": "2024-01-08T00:00:00Z",
  "limit": 100
})

Tool: get_receipts_data

Retrieve user purchase receipts (email receipts).

Parameters

Parameter	Type	Required	Description
`auth_token`	string	No*	Base64-encoded JWT (starts with `eyJ...`). Not the user ID.
`uid`	string	No*	Consented user ID (typically starts with `psub_`). Not the auth token.
`begin`	string	No	Start time filter (ISO 8601)
`end`	string	No	End time filter (ISO 8601)
`ingested_begin`	string	No	Ingestion start (for delta queries)
`ingested_end`	string	No	Ingestion end (for delta queries)
`category`	string	No	Filter by category
`cursor`	string	No	Pagination cursor
`limit`	number	No	Max results per request

Either provide in tool call or use session credentials from connection

Response Format

{
  "success": true,
  "count": 1,
  "has_more": false,
  "next_cursor": null,
  "applied_ingested_end": "2024-01-15T10:30:00Z",
  "data": [
    {
      "event_id": 98765,
      "user_id": "psub_e5f6789012345678901234abcdef0123",
      "retailer_name": "Example Store",
      "total_value": 49.99,
      "receipt_currency": "USD",
      "subject": "Purchase Receipt - Example Store",
      "timestamp": "2024-01-15T10:30:00Z",
      "category": "/Shopping/Retail",
      "brands": ["Example Store"],
      "items": [],
      "ingested_at": "2024-01-15T11:00:00Z"
    }
  ]
}

Example Usage

"Find all purchases over $100 from the last month"

Agent uses: get_receipts_data({
  "begin": "2023-12-15T00:00:00Z",
  "end": "2024-01-15T23:59:59Z",
  "limit": 1000
})
// Then filters results where amount > 100

Common Patterns

Pagination

All tools support cursor-based pagination for large datasets:

Make initial request (no cursor parameter)
Check response has_more field
If true, use next_cursor in next request
Repeat until has_more = false

let allData = [];
let cursor = null;

do {
  const result = await mcpTool.call('get_search_data', {
    begin: '2024-01-01T00:00:00Z',
    limit: 1000,
    cursor: cursor
  });

  allData.push(...result.data);
  cursor = result.next_cursor;
} while (result.has_more);

all_data = []
cursor = None

while True:
    result = mcp_tool.call('get_search_data', {
        'begin': '2024-01-01T00:00:00Z',
        'limit': 1000,
        'cursor': cursor
    })

    all_data.extend(result['data'])

    if not result['has_more']:
        break

    cursor = result['next_cursor']

Delta Queries

Use ingested_begin/ingested_end to fetch only new data since last sync:

Store last_sync_time after each sync
Next sync: set ingested_begin = last_sync_time
Update last_sync_time to response applied_ingested_end
Repeat on subsequent syncs

This avoids re-fetching unchanged data.

Category Filtering

Categories use slash-delimited hierarchical paths:

/Shopping - All shopping data
/Shopping/Electronics - Electronics only
/Food/Restaurants - Restaurant searches/visits

Categories are assigned by Emerge’s classification system. Not all events have categories.

Error Handling

When a tool call fails, it returns an error structure:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error: 401 Unauthorized - Invalid API token. Verify your auth_token is correct."
    }
  ]
}

Common error codes:

401: Invalid credentials
400: Invalid parameters (e.g., malformed timestamp)
404: User not found (no consent)
429: Rate limit exceeded
500: Server error (retry with exponential backoff)

Best Practices

Use limit: 1000 for balanced performance and memory

Always check has_more for complete dataset retrieval

Use ingested_begin/end for incremental syncs

Apply category filters to reduce data volume

Handle errors gracefully with retry logic

Rate Limits

Per API token limits:

100 requests/minute
1000 requests/hour

Exceeding limits returns HTTP 429. Wait before retrying or contact support for higher limits.

Next Steps

Setup Guide

Configure AI tools to use these tools

Query API Reference

HTTP API equivalents

Examples

See workflow examples

MCP Query Setup

Architecture and configuration

Getting Started

MCP Servers

Examples

MCP Query Tools Reference

Tool: get_search_data

Parameters

Response Format

Example Usage

Tool: get_youtube_data

Parameters

Response Format

Example Usage

Tool: get_browsing_data

Parameters

Response Format

Example Usage

Tool: get_ads_data

Parameters

Response Format

Example Usage

Tool: get_receipts_data

Parameters

Response Format

Example Usage

Common Patterns

Delta Queries

Category Filtering

Error Handling

Best Practices

Rate Limits

Next Steps

Setup Guide

Query API Reference

Examples

MCP Query Setup

​Tool: get_search_data

​Parameters

​Response Format

​Example Usage

​Tool: get_youtube_data

​Parameters

​Response Format

​Example Usage

​Tool: get_browsing_data

​Parameters

​Response Format

​Example Usage

​Tool: get_ads_data

​Parameters

​Response Format

​Example Usage

​Tool: get_receipts_data

​Parameters

​Response Format

​Example Usage

​Common Patterns

​Pagination

​Delta Queries

​Category Filtering

​Error Handling

​Best Practices

​Rate Limits

​Next Steps

Setup Guide

Query API Reference

Examples

MCP Query Setup

Tool: get_search_data

Parameters

Response Format

Example Usage

Tool: get_youtube_data

Parameters

Response Format

Example Usage

Tool: get_browsing_data

Parameters

Response Format

Example Usage

Tool: get_ads_data

Parameters

Response Format

Example Usage

Tool: get_receipts_data

Parameters

Response Format

Example Usage

Common Patterns

Pagination

Delta Queries

Category Filtering

Error Handling

Best Practices

Rate Limits

Next Steps