--- title: "Claude MCP Web Search: Live Results for an Agent" description: "Add the Perceptlayer MCP server to Claude, let the agent call the Google Search endpoint, and count its cost: 1 credit per search call." url: https://perceptlayer.com/blog/claude-agent-live-search-mcp --- [Blog](https://perceptlayer.com/blog) / [AI agents](https://perceptlayer.com/blog/category/ai-agents) # Claude MCP Web Search: Live Results for an Agent 22 Oct 2026 Perceptlayer 8 min read To give a Claude agent live search results over MCP, add the Perceptlayer MCP server at `https://api.perceptlayer.com/mcp` with your API key, then let the agent find and call the Google Search endpoint through the `search_endpoints`, `get_endpoint` and `call_endpoint` tools. Each successful search call costs 1 credit and failed calls cost nothing. This tutorial wires it up in Claude Code and in a Python agent, then counts the credits per question. ## Key takeaways - One command, `claude mcp add --transport http perceptlayer https://api.perceptlayer.com/mcp`, connects Claude Code to the server with a Bearer header. - The server exposes three tools: `search_endpoints`, `get_endpoint` and `call_endpoint`. - A successful Google Search call costs 1 credit, so 1,000 free monthly credits cover 1,000 search calls. - Failed calls cost nothing and return `X-Credits-Used: 0`, so a retry loop in your agent can't drain credits through errors. - A cap of 3 search calls per question in the system prompt bounds a question's spend at 3 credits, and the script in step 4 prints the count so you can check it. ## What do you need before you start? You need a Perceptlayer API key, the `claude` CLI or the Claude Agent SDK for Python, and an environment variable holding the key. Keys start with `sk_live_`. Every account gets 1,000 free credits each month after verifying an email address, with no credit card, so you can run everything below without paying. [Get a free API key](https://perceptlayer.com/signup) first, then export it. ```bash export API_KEY="sk_live_..." ``` The same key authenticates plain HTTP calls with the `X-API-Key` header and the MCP server with an `Authorization: Bearer` header. The [authentication docs](https://perceptlayer.com/docs#authentication) cover both, plus the `api_key` query parameter for cases where headers aren't possible. ## How does a Claude agent search the web over MCP? The Model Context Protocol lets an agent discover and call tools on a remote server. Perceptlayer's server speaks [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports), the protocol's standard transport for remote servers, and gives the agent access to a catalogue of 248 websites and 1,659 endpoints, all returning JSON. The server's tools are `search_endpoints`, `get_endpoint` and `call_endpoint`. The [MCP section of the docs](https://perceptlayer.com/docs#mcp) describes the server, and the [protocol site](https://modelcontextprotocol.io/) describes MCP itself. ## Step 1: How do you add the MCP server to Claude Code? Run one command. It registers the server under the name `perceptlayer`, using the HTTP transport and your key as a Bearer token. Claude Code stores the entry in its MCP configuration. ```bash claude mcp add --transport http perceptlayer https://api.perceptlayer.com/mcp \ --header "Authorization: Bearer $API_KEY" ``` Confirm the server connected: ```bash claude mcp list ``` You should see `perceptlayer` in the list. Inside a Claude Code session, the `/mcp` command shows the connection status of the server. If you want the entry scoped to a project instead of your user, the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) lists the scope options. ### Ask a question that needs live search Start `claude` and ask something the model can't know from training, such as: "Use Perceptlayer to search Google for the latest Claude Code release notes and list the top five result titles with their URLs." If Claude Code prompts you about the MCP tools, allow `search_endpoints`, `get_endpoint` and `call_endpoint` so the agent can reach the Google Search endpoint. ## Step 2: Which Google Search endpoint should the agent use? The Google Search API has 7 endpoints, and every one costs 1 credit per successful call. For an agent answering open questions, start with `/v1/google-search/search`, which takes a required `query` and optional parameters for country ( `gl`), language ( `hl`), result count and paging. The others fit narrower jobs, so tell the agent which to prefer if you care. | Endpoint | Required | Use it when | | --- | --- | --- | | [`/v1/google-search/search`](https://perceptlayer.com/apis/google-search/search) | `query` | General web search with the full parameter set | | [`/v1/google-search/search-light`](https://perceptlayer.com/apis/google-search/search-light) | `query` | A smaller parameter set, with `num` for result count | | [`/v1/google-search/search-ai-overview`](https://perceptlayer.com/apis/google-search/search-ai-overview) | `query` | You want the AI Overview for a query | | [`/v1/google-search/google-ai-mode-search`](https://perceptlayer.com/apis/google-search/google-ai-mode-search) | `q` | You want an AI Mode answer, with `follow_up_token` for follow-ups | | [`/v1/google-search/search-light-autocomplete`](https://perceptlayer.com/apis/google-search/search-light-autocomplete) | `query` | Query suggestions, with `hl` and `limit` | Note that `google-ai-mode-search` uses `q` where the others use `query`. A hard-coded script needs to get that right. The [Google Search API page](https://perceptlayer.com/apis/google-search) lists all seven, including [`search-advanced`](https://perceptlayer.com/apis/google-search/search-advanced) and [`search-advanced-place`](https://perceptlayer.com/apis/google-search/search-advanced-place), and the [search engines hub](https://perceptlayer.com/verticals/search) shows related sources. ## Step 3: How do you check the endpoint outside the agent? Call the endpoint directly with cURL before trusting an agent with it. If the request works from your terminal, any later failure is in the agent's prompt or tool use, not in the data call. The `-i` flag prints the response headers so you can see the status. ```bash curl -i "https://api.perceptlayer.com/v1/google-search/search?query=claude%20code%20release%20notes" \ -H "X-API-Key: $API_KEY" ``` The endpoint returns the search results as JSON. To see a real response for your own query before you wire up the agent, run it in the playground on the [Google Search API page](https://perceptlayer.com/apis/google-search), which calls the endpoint with your key and shows the result; the [Search endpoint page](https://perceptlayer.com/apis/google-search/search) lists every parameter. Break the call on purpose to see the failure shape. Send a bad key and you get HTTP 401 with a body like `{"error": {"code": "invalid_api_key", ...}}`, and the response carries `X-Credits-Used: 0`. The [errors section of the docs](https://perceptlayer.com/docs#errors) lists every code. ## Step 4: How do you build a Python agent that uses the server? Use the Claude Agent SDK, point `mcp_servers` at the Perceptlayer URL, and allow the three tools by name. The script below asks one question, prints the answer, and counts how many times the agent called `call_endpoint`. The script counts every `call_endpoint` call and assumes 1 credit each, which holds for every Google Search endpoint and for nearly all others. It doesn't count `search_endpoints` or `get_endpoint` calls, and it counts failed calls too, which are free. Treat the total as an estimate, not a bill. Install the SDK with `pip install claude-agent-sdk`, then save this as `agent.py`: ```python import asyncio import os from claude_agent_sdk import ( AssistantMessage, ClaudeAgentOptions, TextBlock, ToolUseBlock, query, ) QUESTION = "What changed in the latest Claude Code release? Cite the result URLs you used." SYSTEM_PROMPT = ( "You answer questions with live web search. " "Use the perceptlayer MCP tools to find and call a Google Search endpoint. " "Make at most 3 search calls per question. Cite the URLs you relied on." ) OPTIONS = ClaudeAgentOptions( system_prompt=SYSTEM_PROMPT, mcp_servers={ "perceptlayer": { "type": "http", "url": "https://api.perceptlayer.com/mcp", "headers": {"Authorization": f"Bearer {os.environ['API_KEY']}"}, } }, allowed_tools=[ "mcp__perceptlayer__search_endpoints", "mcp__perceptlayer__get_endpoint", "mcp__perceptlayer__call_endpoint", ], ) CREDITS_PER_CALL = 1 # every Google Search endpoint costs 1 credit; failed calls cost 0 async def main(): data_calls = 0 async for message in query(prompt=QUESTION, options=OPTIONS): if not isinstance(message, AssistantMessage): continue for block in message.content: if isinstance(block, ToolUseBlock) and block.name.endswith("call_endpoint"): data_calls += 1 elif isinstance(block, TextBlock): print(block.text) print(f"\ndata calls: {data_calls}, credits (estimate): {data_calls * CREDITS_PER_CALL}") asyncio.run(main()) ``` The [Agent SDK documentation](https://code.claude.com/docs/en/agent-sdk/python) covers the options used above. ## Step 5: What does the script print? Run it with `python agent.py`. The agent's answer text prints as it arrives, followed by one summary line in this format, where each `` is a number from your run: ```text data calls: , credits (estimate): ``` Compare that number with the cap in the system prompt. If the count is higher than the cap, tighten the prompt. ### Why cap the number of search calls? Each successful search call costs 1 credit, so the number of calls sets the credit cost of a question. The prompt line "at most 3 search calls per question" bounds that spend at 3 credits, and the counter shows whether the agent respects it. Treat the cap as a guardrail, not a guarantee, and check the printed count while you tune the prompt. ## What does each question cost? A successful `call_endpoint` call to a Google Search endpoint costs 1 credit, so an agent that searches twice spends 2 credits. The figures below count only those search calls; they leave out `search_endpoints` and `get_endpoint` calls. The free tier of 1,000 credits a month covers 1,000 search calls, and purchased credits last 12 months with no subscription and no seats. The table below counts Perceptlayer credits only. Claude model tokens are billed separately by Anthropic, so the real cost of a question is higher than the credit figure. | Workload | Calls | Credits | Covered by | | --- | --- | --- | --- | | 300 questions × 1 search each | 300 | 300 | Free tier (1,000 credits) | | 300 questions × 3 searches each | 900 | 900 | Free tier (1,000 credits) | | 10,000 questions × 1 search each | 10,000 | 10,000 | Starter pack, 12,500 credits for $10 | | 5,000 questions × 3 searches each | 15,000 | 15,000 | Growth pack, 83,000 credits for $50 | Packs are bought whole. The Starter pack is $10 for 12,500 credits, an effective $0.80 per 1,000 calls, and it covers the 10,000 calls in the third row. The Growth pack is $50 for 83,000 credits, an effective $0.60 per 1,000 calls, and it covers the 15,000 calls in the last row. The Scale pack is $200 for 400,000 credits, or $0.50 per 1,000 calls. The [pricing page](https://perceptlayer.com/pricing) has all three, and the [credits section of the docs](https://perceptlayer.com/docs#credits) explains how a call is billed. Because failed calls are free, a rate-limited or erroring call doesn't add to the total. Only a successful response debits credits. ## What happens when a call fails? A failed call returns an HTTP status and a JSON body with `error.code`, `error.message` and `error.request_id`, and it costs nothing. Give the agent a rule for each case in the system prompt so it knows whether to retry, change the query, or stop, and doesn't loop. | Code | Status | What the agent should do | | --- | --- | --- | | `invalid_parameters` | 422 | Check the parameters against the endpoint page, fix, retry once | | `rate_limited` | 429 | Wait and retry; see [rate limits](https://perceptlayer.com/docs#limits) | | `source_error` | 502 | Retry once, then report that search is unavailable | | `temporarily_unavailable` | 503 | Retry later | | `insufficient_credits` | 402 | Stop and tell the user to top up | | `invalid_api_key` | 401 | Stop; the key is wrong or revoked | | `restricted_endpoint` | 403 | Stop; the endpoint needs the restricted-endpoint terms accepted in the dashboard | Add a sentence such as "If a tool call fails with insufficient\_credits or invalid\_api\_key, stop and say so" to `SYSTEM_PROMPT`. Retries on the transient codes are safe for your balance because failures aren't billed. ## Next step: point the same server at more sources The server isn't limited to Google Search. The same key and the same three tools reach the rest of the catalogue, so the agent can move from a search result to a listing, a review page or a price without a new integration. Some endpoints, covering social, personal and SEO data, need you to accept the restricted-endpoint terms in the dashboard first. Add the server with the command in step 1, ask your agent a question that needs live data, and check the credit count it prints. To read more about how agents pick and call endpoints, see the [MCP docs](https://perceptlayer.com/docs#mcp), and for a worked example of one data source end to end, read [how to get Zillow listings as JSON](https://perceptlayer.com/blog/zillow-listings-api-json). ## APIs in this post - [Google Search **1 credit per call** · 7 endpoints](https://perceptlayer.com/apis/google-search) ## Frequently asked questions ### How much does a Claude MCP web search cost with Perceptlayer? A successful call to a Google Search endpoint costs 1 credit. The free tier gives 1,000 credits every month, and packs start at $10 for 12,500 credits, which is $0.80 per 1,000 calls. Failed calls cost nothing and return `X-Credits-Used: 0`, so errors never add to your bill. ### Do I need the Claude Agent SDK, or does Claude Code work on its own? Claude Code works on its own. The `claude mcp add` command registers the server, and you ask questions in the terminal. The Agent SDK is for embedding the same behaviour in your own application, where you want to control the prompt, cap the number of searches and print the credits used per question. ### Can I use the key in a header other than Authorization? On plain HTTP calls, send the key in `X-API-Key`, or in the `api_key` query parameter where headers aren't possible. The MCP server uses an `Authorization: Bearer` header in the Claude Code command shown above. Keys start with `sk_live_`, and the authentication section of the docs covers both forms. ### What does the agent do when search is rate limited? A rate-limited call returns HTTP 429 with the code `rate_limited`, and it isn't billed. Put a retry rule in the system prompt so the agent waits and tries again instead of looping. ### What are the data-use terms for search results? Data is collected from publicly available sources and returned as found at the time of the call. How you use results is your responsibility, so check the terms that apply to your use case. Social, personal and SEO endpoints need you to accept the restricted-endpoint terms, and you shouldn't use personal data to contact people without a lawful basis. claude mcp google search ai agents tool calling ## More from the blog 1. [AI agents](https://perceptlayer.com/blog/category/ai-agents) 22 Oct 2026 Perceptlayer 7 min read ## [AI Agent API Cost Control: Cap Web Data Spend](https://perceptlayer.com/blog/ai-agent-web-data-costs) Cap an agent's web data spend per run: credit arithmetic for 8 and 20 calls per task, a Python budget wrapper, and why failed calls cost 0 credits. 2. [API guides](https://perceptlayer.com/blog/category/api-guides) 22 Oct 2026 Perceptlayer 7 min read ## [Zillow Listings API: Get Property Data as JSON](https://perceptlayer.com/blog/zillow-listings-api-json) One GET to /v1/zillow/search returns listings near a point as JSON with price, beds, baths and address. Parameters, a real response, 1 credit per call.