simple-websearch-mcp

Give any MCP client — Claude Desktop, a custom agent, anything speaking MCP over HTTP — web search with just one endpoint URL and one API key. No local process to install, no AWS credentials on the client, no OAuth flow. The SigV4 signing and Amazon Bedrock AgentCore protocol translation all happen server-side, so the client stays trivially simple.

Why this project

Wiring web search into an agent usually forces a trade-off. This server removes it:

Approach	What the client needs	Friction
Local stdio MCP server (uvx/npx)	A runtime, a local process, the search provider's key stored locally	Install & maintain a process on every machine
Direct AgentCore Gateway calls	Local AWS credentials + SigV4 signing on every request	Client needs an AWS account and signing logic
Hosted search APIs	Vendor SDK, OAuth/SSO	Onboarding overhead per client
simple-websearch-mcp	One HTTPS URL + one x-api-key header	—

That gives you three properties the other paths don't:

• Zero client footprint — the client is pure HTTP. No processes, no AWS credentials, no OAuth. Any MCP Streamable-HTTP client connects by pasting a URL and a key.
• Deploy once, share widely — one backend serves many agents. Keys are issued and revoked centrally, with a rate limit (10 req/s) and per-key usage stats.
• Complexity absorbed by AWS — API Gateway authenticates the key, and the Lambda handles SigV4 signing and the AgentCore MCP protocol. The client never sees any of it.

Quick Start (for client users)

Add this block to your MCP client settings (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "websearch": {
      "type": "http",
      "url": "<EndpointUrl>",
      "headers": {
        "x-api-key": "<api-key-value>"
      }
    }
  }
}

Fill in the two placeholders — that's the entire setup:

• <EndpointUrl> — paste the EndpointUrl stack output verbatim. It is already the complete URL (e.g. https://abc123.execute-api.us-east-1.amazonaws.com/prod/mcp); there is nothing to extract or reassemble.

• <api-key-value> — the 40-character API key value. The ApiKeyId stack output is only the key's ID, not a usable key, so resolve the value with:

  aws apigateway get-api-key --api-key <ApiKeyId> --include-value --query value --output text
  

  (Or use scripts/manage_keys.py create-key, described under Key management, which prints a ready-to-paste config block with the value already filled in.)

If you are the person deploying the backend, see Operating the server below first.

The web_search Tool

Once connected, the server exposes a single tool, web_search:

Parameter	Type	Required	Description
query	string	yes	Search query (truncated to 200 characters).
max_results	integer	no	Number of results to return, 1–25 (default 10; values outside the range are clamped).

Most MCP clients invoke the tool for you and let the agent choose the arguments — you only set max_results directly if your client exposes tool arguments. The underlying JSON-RPC tools/call request looks like this:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "web_search",
    "arguments": {
      "query": "latest Amazon financial report",
      "max_results": 5
    }
  }
}

Each result is an object with the following fields:

Field	Type	Description
content	string	The result snippet/body text. Always present (may be a long passage, not just a short summary).
url	string	Source URL. May be an empty string if the result has no URL.
title	string	Source title. May be an empty string.
published_date	string | null	Publication date as a free-form string (e.g. "06:01AM, Tuesday, July 28 2026, PDT") — not a normalized ISO date, and null when the source provides none. Do not parse it as a fixed format.

Limits & Constraints

• Query length: truncated to 200 characters
• Results per request: max_results parameter, 1–25 (default: 10)
• Rate limit: 10 requests/second, burst 20 (per API key; configurable at deploy time)
• Daily quota: 10,000 requests/day per API key (exceeding it returns HTTP 429; configurable at deploy time)
• Region: deployed in us-east-1 only (endpoint type is a deploy-time choice — regional by default, edge-optimized for dispersed non-US clients)
• Transport: HTTP POST to /mcp endpoint (GET returns 405)
• No-URL results: returned by default; deploy with FILTER_NO_URL=true to drop them (see Filter results with no URL)
• Domain filtering: admin-time denylist only (not per-call)

Acceptable Use

When displaying search results, you must retain and display source URLs (citations). This server is for augmenting conversational AI with web context, not for:

• Bulk data extraction or scraping
• Building a competing search index
• Re-publishing content without attribution

Respect the source websites' terms of service and robots.txt policies.

---

Operating the server

Everything below is for the person deploying and running the backend. Client users do not need any of it.

Architecture

MCP Client (Claude Desktop, etc.)
    ↓ HTTP + x-api-key header
API Gateway (native API key auth + usage plan)
    ↓ SigV4 signature
Lambda Function (MCP protocol handler)
    ↓ SigV4-signed JSON-RPC (httpx)
AgentCore Gateway (us-east-1)
    ↓
web-search connector

Endpoint type

The API endpoint type is chosen at deploy time via the ENDPOINT_TYPE env var, defaulting to regional:

ENDPOINT_TYPE=edge cdk deploy WebSearchApiStack

• regional (default) — lowest latency when clients are in the same Region (US) as this us-east-1 deployment.
• edge — fronts the API with an AWS-managed CloudFront distribution that terminates TLS at the nearest Point of Presence and carries the long haul over AWS's backbone (steadier than the public internet under jitter), at no extra API Gateway cost. Better for dispersed non-US clients.

Switching between the two is a no-interruption update: the API id and invoke URL are preserved, so existing clients keep working (an edge deploy is slower, as CloudFront propagates).

The server implements the MCP protocol version 2025-06-18 using stateless Streamable HTTP transport with JSON-response mode. Each request is authenticated via API Gateway native API keys, and the Lambda function translates MCP tool calls into signed AgentCore Gateway requests.

Deploy

Deploy requires AWS CDK CLI ≥ 2.1133.0 and Python 3.10+. The infrastructure deploys in us-east-1 only.

cd infra
pip install -r requirements.txt

# Deploy gateway stack first
cdk deploy WebSearchGatewayStack

# Deploy API stack second (depends on gateway)
cdk deploy WebSearchApiStack

After deployment, note the outputs:

• WebSearchGatewayStack.GatewayUrl — the AgentCore Gateway endpoint (internal use)
• WebSearchApiStack.EndpointUrl — your public MCP endpoint URL (hand this to client users)
• WebSearchApiStack.ApiKeyId — ID of the initial API key created (resolve its value as shown in Quick Start)

Optional: Domain denylist

To exclude specific domains from search results, set the EXCLUDE_DOMAINS environment variable when deploying the gateway stack:

EXCLUDE_DOMAINS="example.com,spam-site.net" cdk deploy WebSearchGatewayStack

This is an admin-time configuration; the denylist is not configurable per-call.

Optional: Filter results with no URL

By default, results without URLs are returned. To drop them, deploy with the FILTER_NO_URL environment variable set:

FILTER_NO_URL=true cdk deploy WebSearchApiStack

Authentication & Key Management

The server uses API Gateway native API keys for authentication. Keys are associated with a usage plan (simple-websearch-mcp-plan) that enforces, per key (each key gets its own bucket — limits are not shared across keys):

• Rate limit: 10 requests/second
• Burst limit: 20 requests
• Daily quota: 10,000 requests/day per key (bounds the cost a leaked key can drive)

Configure usage-plan limits

These limits default to the values above. Override them at deploy time — useful when a single key serves higher-volume traffic, or when issuing per-user keys (e.g. SaaS) that each need more headroom:

RATE_LIMIT=50 BURST_LIMIT=100 DAILY_QUOTA=250000 cdk deploy WebSearchApiStack

An invalid value (non-integer or ≤ 0) fails the deploy immediately rather than silently applying the default. These apply the same limit to every key on the plan; for genuinely different per-tenant tiers, create separate usage plans instead.

Key management

Manage keys using the scripts/manage_keys.py utility (run from the repository root, not infra/):

# Install dependencies (if not already)
pip install -e ".[dev]"

# Create a new API key (prints a ready-to-paste client config block)
python scripts/manage_keys.py create-key --name "my-client" --endpoint <EndpointUrl>

# List all keys
python scripts/manage_keys.py list-keys

# Revoke a key
python scripts/manage_keys.py revoke-key --key-id <key-id>

# Show per-key usage (auto-discovers the Lambda log groups)
python scripts/manage_keys.py show-usage --hours 24

The create-key command outputs a complete MCP client configuration block you can copy directly into a client's settings — the fastest way to onboard a new agent.

Usage Analysis

The Lambda emits a structured log line for every web_search call — with tool, apiKeyId, query_len, and result_count as top-level fields — so CloudWatch Logs Insights can query usage directly.

manage_keys.py show-usage runs this query for you and prints per-key totals:

fields @timestamp, apiKeyId, result_count
| filter tool = 'web_search'
| stats count(*) as searches, sum(result_count) as results by apiKeyId

To query CloudWatch Logs Insights directly, adjust the fields, time range, and grouping as needed — for example, | stats count(*) as requests by apiKeyId, bin(1d) for per-key daily counts.

Verify Deployment

Run the live smoke test to confirm end-to-end functionality (use the EndpointUrl output and a resolved key value):

python scripts/live_smoke.py \
  --endpoint <EndpointUrl> \
  --api-key <api-key-value>

Expected output:

initialize: {'name': 'simple-websearch-mcp', 'version': '0.1.0'}
web_search returned 10 results
  - Latest AWS Bedrock Updates :: https://...
  - Amazon Bedrock Announcements :: https://...
  - ...

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.