MCP Query Setup

The Query API MCP server gives AI agents (Claude, Cursor, VS Code) secure access to consented user data. Instead of making direct HTTP calls, AI tools use the Model Context Protocol with session-based credentials.

Different from Docs MCP: This server queries user data. For documentation search, see Docs MCP Setup.

Architecture

The MCP server is a thin wrapper around Query API sync endpoints:

Feature	MCP Server	Direct HTTP
Protocol	MCP (JSON-RPC over HTTP)	REST API
Credentials	Session-based (provide once)	Per-request (Bearer token)
Tool Discovery	Built-in (`tools/list`)	OpenAPI spec
Ship with MCP	Native support	Manual implementation
Best For	AI agents, IDE plugins	Server-to-server, custom apps

Prerequisites

The Control Room account with API credentials

At least one user with granted consent

Don’t have credentials? Sign up here.

MCP Server URL

https://mcp.emergedata.ai/mcp

Authentication: Session-based credentials passed via URL parameters during initialization.

Setup by Tool

Claude Code
Claude Desktop
Cursor
VS Code

Add MCP Server

claude mcp add emerge-query "https://mcp.emergedata.ai/mcp?auth_token=YOUR_TOKEN&uid=YOUR_UID"

Verify Connection

claude mcp list

You should see:

emerge-query: https://mcp.emergedata.ai/mcp (connected)

Usage

Now you can query user data:

claude "Get search history for psub_c3d4e5f6789012345678901234abcdef from the last week"

Claude Code will:

Call the get_search_data tool
Apply date range filters
Return formatted results

Add MCP Server

Open Claude desktop app
Go to Settings → Connectors
Click Add custom connector
Enter configuration:
- Name: Emerge Query API
- URL: https://mcp.emergedata.ai/mcp

Add connection parameters:

?auth_token=YOUR_API_TOKEN&uid=YOUR_USER_ID

Click Save

Usage

Now you can ask Claude to query user data:

“Get search history for the last week”
“What YouTube videos has this user watched?”
“Show me browsing history filtered by Shopping category”

Claude will automatically call the appropriate MCP tools and format the results.

Configuration File

Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "Emerge Query": {
      "url": "https://mcp.emergedata.ai/mcp?auth_token=YOUR_TOKEN&uid=YOUR_USER_ID"
    }
  }
}

Security: Never commit credentials to git. Use environment variables:

{
  "mcpServers": {
    "Emerge Query": {
      "url": "https://mcp.emergedata.ai/mcp?auth_token=${EMERGE_TOKEN}&uid=${EMERGE_UID}"
    }
  }
}

Usage

In Cursor’s AI chat, ask questions about user data:

@Emerge Query Show me search patterns for the last month

Cursor will:

Query the MCP server
Receive structured data
Analyze and present insights

MCP Configuration

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "Emerge Query": {
      "type": "http",
      "url": "https://mcp.emergedata.ai/mcp?auth_token=YOUR_TOKEN&uid=YOUR_UID"
    }
  }
}

With GitHub Copilot

If using Copilot Chat, the MCP connection provides:

Direct access to user data via natural language
Structured queries with proper filtering
Context-aware code generation

With Other AI Extensions

Any VS Code AI extension supporting MCP can use this configuration.

Verify Connection

After configuration, test the health endpoint:

curl https://mcp.emergedata.ai/mcp/health

# Expected response
{
  "status": "ok",
  "service": "mcp-server",
  "version": "1.0.0",
  "protocol": "streamable-http"
}

Session Credentials

The MCP server uses session-based credentials — provide them once on connection, and all tool calls use them automatically.

Credential	What it is	Format	Example
`auth_token`	Base64-encoded JWT from The Control Room	Starts with `eyJ...` (long string)	`eyJhbGciOiJSUzI1NiIs...`
`uid`	Consented user identifier from consent callback	Typically starts with `psub_`	`psub_c3d4e5f6789012345678901234abcdef`

Don’t mix these up! A common mistake is swapping auth_token and uid. The auth_token is always a long JWT string starting with eyJ. The uid is a shorter identifier, typically starting with psub_.

You can override session credentials for individual tool calls by passing auth_token and uid as tool parameters.

Security Best Practices

Never commit credentials to git repositories

Use environment variables in configuration files

Rotate API tokens regularly via The Control Room

Use unique uid per user (don’t share across users)

Available Tools

The MCP server exposes 5 tools that map 1:1 to Query API sync endpoints:

MCP Tool	Query API Endpoint	Data Type
`get_search_data`	`/v1/sync/get_search`	Search history
`get_youtube_data`	`/v1/sync/get_youtube`	YouTube watch history
`get_browsing_data`	`/v1/sync/get_browsing`	Web browsing
`get_ads_data`	`/v1/sync/get_ads`	Ad interactions
`get_receipts_data`	`/v1/sync/get_receipts`	Purchase receipts

See MCP Query Tools for detailed parameter and response documentation.

Response Format

All tools return the same structure:

{
  "success": true,
  "count": 10,
  "has_more": true,
  "next_cursor": "eyJsYXN0X2V2ZW50X2lkIjoxMjM0NX0=",
  "applied_ingested_end": "2024-01-15T10:30:00Z",
  "data": [
    // ... event objects
  ]
}

Pagination

Use cursor-based pagination for large datasets:

let cursor = null;
let allData = [];

do {
  const result = await use_mcp_tool({
    tool: "get_search_data",
    arguments: {
      begin: "2024-01-01T00:00:00Z",
      limit: 1000,
      cursor: cursor
    }
  });

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

See Pagination Guide for best practices.

Error Handling

When a tool call fails, it returns:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Detailed error message"
    }
  ]
}

Common errors:

401 Unauthorized: Invalid or missing credentials
400 Bad Request: Invalid parameters (e.g., malformed timestamp)
500 Internal Server Error: Query API or database error

Example Queries

"Get search history for psub_c3d4e5f6789012345678901234abcdef from the last 7 days filtered by Shopping category"

"Show me the most recent YouTube videos watched by this user, grouped by category"

"Retrieve browsing history with pagination, starting from cursor abc123, limit 500"

The AI agent will:

Parse your natural language query
Select the appropriate MCP tool
Apply filters and parameters
Return formatted results

Troubleshooting

Tool calls fail with 401 Unauthorized

Cause: Invalid or missing credentialsSolutions:

Verify auth_token is correct from The Control Room
Check that user has granted consent (callback status=success)
Ensure credentials are in the connection URL
Try refreshing/rotating your API token

Empty data arrays returned

Cause: No data available for querySolutions:

Data export may still be processing (watch for data.ready/data.failed webhooks or poll GET /export/status/{uid} until provider data_ready: true)
User may not have data for the requested type
Check time filters (begin/end) aren’t excluding all data
Verify category filter isn’t too restrictive

Connection timeout

Cause: Cannot reach MCP serverSolutions:

Verify MCP server URL is exactly https://mcp.emergedata.ai/mcp
Check firewall/network settings allow HTTPS outbound
Test health endpoint: curl https://mcp.emergedata.ai/mcp/health
Contact support if server appears down

Tools not appearing in AI tool

Cause: MCP connection not establishedSolutions:

Restart your AI tool after adding configuration
Verify config file is in the correct location
Check file permissions (must be readable)
Review AI tool logs for MCP connection errors

Rate Limits

The MCP server inherits rate limits from the Query API:

Requests: 100 requests per minute per auth token
Data: 10,000 events per request (recommended: 1000)
Concurrent: 10 simultaneous connections per organization

Exceeding limits returns HTTP 429 errors. Contact support for higher limits.

Source Code

The MCP server is open-source:

Repository: github.com/emerge-protocol/emgcp
Issues: Report bugs or request features
License: MIT

Next Steps

Tool Reference

Detailed documentation for all 5 tools

Query Guide

Learn about sync vs async queries

Examples

See AI workflow examples

Webhooks

Track consent and data export lifecycle changes

Getting Started

MCP Servers

Examples

Architecture

Prerequisites

MCP Server URL

Setup by Tool

Add MCP Server

Verify Connection

Usage

Add MCP Server

Usage

Configuration File

Usage

MCP Configuration

With GitHub Copilot

With Other AI Extensions

Verify Connection

Session Credentials

Security Best Practices

Available Tools

Response Format

Error Handling

Example Queries

Troubleshooting

Rate Limits

Source Code

Next Steps

Tool Reference

Query Guide

Examples

Webhooks

​Architecture

​Prerequisites

​MCP Server URL

​Setup by Tool

​Add MCP Server

​Verify Connection

​Usage

​Add MCP Server

​Usage

​Configuration File

​Usage

​MCP Configuration

​With GitHub Copilot

​With Other AI Extensions

​Verify Connection

​Session Credentials

​Security Best Practices

​Available Tools

​Response Format

​Pagination

​Error Handling

​Example Queries

​Troubleshooting

​Rate Limits

​Source Code

​Next Steps

Tool Reference

Query Guide

Examples

Webhooks

Architecture

Prerequisites

MCP Server URL

Setup by Tool

Add MCP Server

Verify Connection

Usage

Add MCP Server

Usage

Configuration File

Usage

MCP Configuration

With GitHub Copilot

With Other AI Extensions

Verify Connection

Session Credentials

Security Best Practices

Available Tools

Response Format

Pagination

Error Handling

Example Queries

Troubleshooting

Rate Limits

Source Code

Next Steps