Blog / AI agents

Claude MCP Web Search: Live Results for an Agent

22 Oct 2026Perceptlayer8 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.

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 first, then export it.

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 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, 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 describes the server, and the protocol site 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.

claude mcp add --transport http perceptlayer https://api.perceptlayer.com/mcp \
  --header "Authorization: Bearer $API_KEY"

Confirm the server connected:

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

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 lists all seven, including search-advanced and search-advanced-place, and the search engines hub 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.

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, which calls the endpoint with your key and shows the result; the Search endpoint page 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 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:

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 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 <n> is a number from your run:

data calls: <n>, credits (estimate): <n>

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.

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 has all three, and the credits section of the docs 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.

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, and for a worked example of one data source end to end, read how to get Zillow listings as JSON.

claudemcpgoogle searchai agentstool calling