Google custom search API for MCP agents
On this page
The Google Custom Search JSON API returns web search results as a JSON object for a search engine you configure in Google. An MCP tool wraps that call so an AI agent can send a query and read titles, links, and snippets without writing HTTP code. You need a Google API key and a programmable search engine ID to start.
What the Google Custom Search API returns
The API takes a query and returns a JSON object. The object holds a list of items, and each item carries a title, a link, a display link, and a snippet. The response also includes search metadata, such as information about the result set and the query that produced it.
Google's programmable search engine sets the search scope. You create the engine in Google and choose which sites it covers. Results come only from that scope. Change the engine settings and the same query can return different items.
Google also exposes request parameters for filtering and for image search. The parameter list changes over time. Check Google's current documentation before you build against any parameter.
Get the credentials you need
Create a Google Cloud project and enable the Custom Search API in it. Generate an API key from the credentials page. Then create a programmable search engine and copy its search engine ID from the engine settings.
Every request needs three values:
- The API key, sent with each call
- The search engine ID, sent as the cx parameter
- The query text, sent as the q parameter
Keep the key out of prompts, logs, and version control. Store it in an environment variable or a secrets manager. Give the MCP tool read access at runtime only.
Wrap the search call as an MCP tool
An MCP tool gives the agent a name, a description, and an input schema. For this API, the schema needs a query string. A result count is optional, and the tool can set a sensible default for it.
The tool sends the request, reads the items list, and returns a trimmed result to the agent. The agent never sees the API key or the raw HTTP response.
Write the description so the model knows when to call the tool. A vague description leads the agent to run searches it did not need, and each extra search draws on the quota.
Trim results before they reach the model
Return only the fields the agent uses. For most tasks, that means the title, the link, and the snippet. Full responses carry metadata that fills the context window and adds cost without helping the answer.
- Title, so the agent can name the source
- Link, so the agent can cite the source
- Snippet, so the agent can judge relevance
Keep the link attached to its snippet at every step. An agent that loses the pairing cannot cite the page it used.
Snippets are short summaries, not full pages. An agent that needs body text must fetch each link in a separate tool call. That fetch is a different step, with its own cost and failure modes.
Handle errors and empty results
The API returns an error object when the key is invalid, the engine ID is wrong, or the daily quota runs out. The tool should pass that message to the agent in plain words, so the agent can stop or tell the user what failed.
An empty items list means the query had no match inside the search engine scope. The agent should broaden the terms, or the operator should widen the sites the engine covers, before the agent concludes that nothing exists.
Retry only transient failures. A bad key or a bad engine ID fails the same way every time, so a retry loop wastes calls and quota.
Quotas, cost, and caveats
Google sets the daily query quota and the price for queries above it. Check the current quota and pricing on Google's pricing page before you plan volume. No public pricing was confirmed for this guide, so this page does not state Google's figures.
An agent loop can fire several searches for one user request. Cap the number of search calls per task in the tool or in the agent configuration. That cap keeps one long prompt from using up the day's quota.
APIbase lists this search tool with prices that range from 0 USD to 29.99 USD, depending on the tool and plan you pick.
When to choose this API over other search tools
Choose this API when you need results limited to sites you select. A programmable search engine gives that control directly, and the scope stays the same across every agent that uses it.
Choose another search tool when the task needs full page text in a single call, or when the query must reach the whole open web without a scope. Those tasks need a fetch step, a different index, or both.
Test the tool with a fixed set of queries before you ship it. Compare the returned links against the sites you expect. A scope that looks right in the console can still return off-topic pages for ambiguous terms.
Log usage so you can spot runaway loops
Log each search call with the query, the timestamp, and the agent task that triggered it. The log shows which prompts consume the most quota and which queries repeat without new results.
Review the log after the first week of use. Repeated identical queries usually mean a prompt never accepts the result. That pattern is cheap to fix once you see it.
Live pricing — search
Data source: live tool catalog snapshot, fetched 2026-11-21.
Chart data as a table
| Tool | Price per call | Cache-hit price |
|---|---|---|
| DuckDuckGo Instant Answer | $0.001 | $0.0001 |
| DuckDuckGo Related Topics | $0.001 | $0.0001 |
| Google Image Search | $0.002 | $0.0002 |
| Google News Search | $0.002 | $0.0002 |
| Google Shopping Search | $0.002 | $0.0002 |
| Google Web Search | $0.002 | $0.0002 |
| Extract Page Content | $0.003 | $0.0003 |
| Scrape Web Page | $0.003 | $0.0003 |
| Web Search + Scrape | $0.005 | $0.0005 |
| Web Page Content Extract | $0.011 | $0.0011 |
| AI Web Search | $0.011 | $0.0011 |
| Find Similar Pages | $0.012 | $0.0012 |
| Tool | Provider | Price/call | Cache-hit |
|---|---|---|---|
| DuckDuckGo Instant Answer | duckduckgo | $0.001 | $0.0001 |
| DuckDuckGo Related Topics | duckduckgo | $0.001 | $0.0001 |
| Google Image Search | serper | $0.002 | $0.0002 |
| Google News Search | serper | $0.002 | $0.0002 |
| Google Shopping Search | serper | $0.002 | $0.0002 |
| Google Web Search | serper | $0.002 | $0.0002 |
| Extract Page Content | exa | $0.003 | $0.0003 |
| Scrape Web Page | spider | $0.003 | $0.0003 |
| Web Search + Scrape | spider | $0.005 | $0.0005 |
| Web Page Content Extract | tavily | $0.011 | $0.0011 |
| AI Web Search | tavily | $0.011 | $0.0011 |
| Find Similar Pages | exa | $0.012 | $0.0012 |
Connect via MCP
$ curl -X POST https://apibase.pro/api/v1/tools/duckduckgo.instant_answer/call \
-H "Content-Type: application/json" -d '{"params": {}}'FAQ
Does the Google Custom Search API return JSON?
Yes. The response is a JSON object with an items list. Each item holds a title, a link, and a snippet. An MCP tool trims that list before it passes the results to the agent.
What do I need to call the Google Custom Search API?
You need a Google API key and a programmable search engine ID. Send both with each request, along with the query text.
Can an AI agent use this API without writing code?
Yes, once an MCP tool wraps the call. The agent sees a named tool with a description and an input schema, and it calls that tool like any other tool.
Why does a search return no items?
The query has no match inside the search engine scope. Broaden the terms, or widen the sites the engine covers, and run the query again.
What does the Google Custom Search API cost?
Google sets the quota and the pricing for queries above it. Check Google's current pricing page for the figures. APIbase lists this tool at 0 USD to 29.99 USD, depending on the plan.
Recommended next step
- STEP 1/2 Connect your MCP client
- STEP 2/2 Browse the full catalog
Related guides
Written with AI assistance from APIbase's published documentation and public data; checked automatically against them. Corrections: https://apibase.pro/
Published: 2026-11-21Source: live apibase.pro catalog snapshot