A1 AI engineering company GitHub
Connect the Google Custom Search MCP server to your AI agent Open source, MIT, on npm. Setup instructions for Claude, Cursor and Codex are in the repository; adoption questions — Telegram. GitHub repository Telegram

Google Custom Search: Raw Custom Search API call — MCP tool

Google Custom Search MCP tool: Escape hatch — a GET against any Custom Search JSON API path, returning the raw response envelope for parameters and fields the typed tools don't expose.

Technical name: raw_request

What task it solves

I want to call the Custom Search JSON API directly when the typed search tools don't expose the parameter or the response field I need.

Performs a GET against a Custom Search API path (e.g. customsearch/v1?q=test&num=3) and returns the raw, unnormalized response: queries.request/nextPage, searchInformation, promotions, context, and items[] with htmlSnippet, htmlTitle, formattedUrl and the full pagemap.

When to use it

Use it for parameters the typed tools deliberately leave out — lowRange/highRange, c2coff, hq, a fields projection to trim the response — or when you need the raw envelope itself (promotions, HTML-formatted snippets). For everyday searching prefer search and search-images: they return the compact normalized shape.

What to provide

  • path — required. The API path with its query string, relative to https://customsearch.googleapis.com, e.g. customsearch/v1?q=hello&num=3&fields=items(title,link).

The API key is attached automatically (in a request header, never the URL), and the configured engine id is filled in when the path carries no cx parameter — an explicit cx in the path wins.

What it returns

The raw JSON envelope exactly as the API sent it, or a clear MCP error. Nothing is normalized or trimmed unless you pass a fields projection yourself.

What changes in Google Custom Search

Nothing. The Custom Search JSON API consists of GET endpoints only, so even this escape hatch cannot modify data — which is why the tool is annotated read-only. Each call still consumes one unit of the daily quota.

Example request

Call customsearch/v1 with q="model context protocol", num=3 and a fields projection that keeps only items' titles and links.

Errors and limitations

  • A path resolving to a foreign origin is rejected before any network call (SSRF guard) — the API key can never leave customsearch.googleapis.com.
  • The same limits as every other tool: 10 results per call, 100 per query, one quota unit per call, HTTP 429 on quota exhaustion.
  • customsearch/v1/siterestrict is deprecated by Google and may not work.

Access also depends on key restrictions, quotas, and upstream API limits.

Related MCP tools

Technical details