Thordata SERP 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.

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.

Parameter	Required	Description
engine	No	Thordata engine key such as google, google_images, google_maps, or bing. The schema default is used when omitted.
q	No	Convenience search input. It is mapped to the engine's declared query field when that field is not q.
json	No	Response format: 1, 2, or 3. Defaults to 1.
params	No	Engine-specific parameters defined by the engine resource. Unsupported keys are ignored.
response_mode	No	complete or compact. Compact mode removes common metadata fields.

A successful result uses this envelope:

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

history

Queries SERP request history for the API-key owner.

Parameter	Required	Description
page	No	Page number. Defaults to 1.
page_size	No	Page size. Defaults to 20.
search_query	No	Search query filter.
search_engine	No	Thordata engine-key filter.
status	No	all, success, or error. Defaults to all.
start_time	No	Start time in Unix seconds.
end_time	No	End time in Unix seconds.
timezone	No	IANA timezone or numeric offset.

statistics

Queries SERP usage statistics for the API-key owner.

Parameter	Required	Description
start_date	Yes	Start date in YYYY-MM-DD.
end_date	Yes	End date in YYYY-MM-DD.
engines	No	Comma-separated engine string or string array.
timezone	No	IANA timezone or offset such as +08:00.

Resources

Resource	Description
thordata://engines	Index of the current supported engine definitions.
thordata://engines/<engine-key>	Groups, fields, controls, defaults, options, and conditions for one engine.

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.