# 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`):

```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:

  ```bash
  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](#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](#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:

```json
{
  "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](#optional-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`:

```bash
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**.

```bash
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](#quick-start-for-client-users))

### Optional: Domain denylist

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

```bash
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:

```bash
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:

```bash
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/`):

```bash
# 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):

```bash
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](CONTRIBUTING.md#security-issue-notifications) for more information.

## License

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