Thordata MCP Server

Thordata MCP Server

Connect Thordata SERP to MCP-compatible AI agents and clients for real-time search, usage history, and statistics.

The Thordata SERP MCP Server exposes Thordata search capabilities through the Model Context Protocol (MCP), making it easy to integrate live search tools into agents, workflows, and MCP clients. In addition to real-time SERP requests, it also provides access to search history, usage statistics, and engine schema resources for richer integrations.

Official MCP Registry

This server is published in the official MCP Registry as io.github.Thordata/thordata-mcp.

View the official Registry entry

The Registry entry points to the hosted Thordata MCP endpoint and provides standardized connection metadata for compatible clients.

Quick start

Most users connect to the hosted Thordata MCP endpoint — no installation, no local build. You only need a Thordata SERP API key.

1. Get your API key

Sign up at Thordata and get your SERP API key from the dashboard.

2. Connect your MCP client

Point your MCP client at the hosted endpoint and put your API key in the URL path. Your key is used per request; Thordata never stores a shared credential on your behalf.

The default connection URL is:

https://mcp.thordata.com/YOUR_API_KEY/mcp

Replace YOUR_API_KEY with your Thordata SERP API key and use this MCP client configuration:

{
  "mcpServers": {
    "thordata": {
      "url": "https://mcp.thordata.com/YOUR_API_KEY/mcp"
    }
  }
}

If your client supports custom headers, you can instead use the Bearer configuration:

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

For a Claude Code one-line install, run:

claude mcp add --transport http thordata https://mcp.thordata.com/YOUR_API_KEY/mcp

3. Make your first request

A typical call flow is:

1. Read the thordata://engines resource to list supported engines.
2. Read thordata://engines/<engine-key> for the engine you want.
3. Build params from that engine's schema.
4. Call the search tool.

What you can do

• search — run a real-time SERP search on any supported engine.
• list_engines — see the current engine list, query field, and schema resources.
• history — query SERP request history for your own account.
• statistics — query SERP usage statistics for your own account.

History and statistics are scoped to the API key you send; you cannot query another user's data.

Authentication

Supported token delivery methods:

• Default: https://mcp.thordata.com/YOUR_API_KEY/mcp (token in the path).
• Optional: Authorization: Bearer YOUR_API_KEY with https://mcp.thordata.com/mcp.
• Compatible: X-Thordata-Serp-Token: YOUR_API_KEY.

Notes:

• The hosted path-token URL is the default connection method.
• The Bearer form is available for clients that support custom headers.
• A path token can appear in access logs and referrers, so the hosted endpoint always uses HTTPS.
• Query-string tokens are not accepted.
• Your API key is forwarded per request and is never included in MCP result metadata; it is redacted from returned data and error text.
• Your engine availability and access level are decided by the Thordata SERP service using your API key.

Tools

list_engines

Returns the current schema version, audience, default engine, engine list, query field for each engine, and its resource URI.

search

Executes a Thordata SERP search request.

A successful result uses this envelope:

{
  "ok": true,
  "status": 200,
  "engine": "google",
  "data": {}
}

history

Queries SERP request history for the API-key owner.

statistics

Queries SERP usage statistics for the API-key owner.

Resources

Building correct parameters

Only fields declared by the selected engine schema are sent. When you build a request:

• The final engine value is always the selected engine key.
• Top-level q and json override values with the same names in params; json defaults to 1.
• Null values, empty strings, and empty arrays are omitted. Numeric zero and boolean false are preserved.

Serialization rules by field type:

• string and options values are sent as they are; Google Flights departure_id and arrival_id are normalized to uppercase.
• boolean (switch) values are serialized as true or false.
• number values are serialized as strings.
• array (multi_select) values are joined with commas, and every element must be a scalar. The country restriction field cr is declared as an array in the current schemas, so it is sent comma-joined exactly as given.
• object values are serialized as JSON.
• Unknown parameters are ignored, and the selected engine remains authoritative.

Response format:

• json=1: structured JSON only.
• json=2: JSON and HTML when supported.
• json=3: HTML only when supported.

complete mode returns the full result; compact mode strips common metadata fields.

Error handling

The server normalizes responses and surfaces failures as MCP tool errors:

• Successful business codes are treated as success; all other non-success codes, non-2xx responses, transport failures, and error text are treated as failures.
• Double-encoded JSON payloads are unwrapped, and user tokens are redacted before results or errors are returned to you.