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:

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.

Related MCP server: evo-scry

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:

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:

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.