agentcore-search-mcp
An MCP server that exposes the Amazon Bedrock AgentCore Gateway WebSearch tool to any MCP client (Claude Code, Codex, Cursor, or your own agent).
中文文档 / Chinese documentation · Agent-executable install steps
What is this
AgentCore Gateway already speaks MCP (JSON-RPC over HTTPS) — but it requires AWS SigV4 request signing (service bedrock-agentcore), which MCP clients cannot do themselves. This server is a local bridge: it accepts plain MCP over stdio and signs every upstream call.
┌────────────────┐ stdio (MCP) ┌──────────────────────┐ SigV4-signed JSON-RPC ┌───────────────────────┐
│ MCP client │ ──────────────► │ agentcore-search-mcp │ ────────────────────────► │ AgentCore Gateway │
│ (Claude Code, │ ◄────────────── │ (this server) │ ◄──────────────────────── │ WebSearch target │
│ Codex, ...) │ └──────────────────────┘ └───────────────────────┘
└────────────────┘
Exposed tool: web_search(query, max_results=5) → {"results": [{"url", "title", "content", "published_date"}]}.
Prerequisites
- An AgentCore Gateway with a WebSearch target. No gateway yet? Deploy one with the bundled script (see below). Or create it manually in the AWS console: Amazon Bedrock AgentCore → Gateways → create a gateway and attach the Web Search connector target, then copy the gateway's MCP endpoint URL. Note: the Web Search connector is region-limited (us-east-1 at the time of writing).
- AWS credentials via any standard chain (environment variables,
AWS_PROFILE, or an instance role) with permission to invoke the gateway (e.g.bedrock-agentcore:InvokeGatewayor your account's equivalent policy for the gateway resource). - Python ≥ 3.10 and uv (recommended; pip also works).
Deploy the gateway with the bundled script
cd agentcore-search-mcp
uv sync # once — the script uses the venv's botocore
bash scripts/deploy_gateway.sh
The script is idempotent (re-runs reuse the existing role/gateway/target by name) and creates three things in your account:
- IAM service role
agentcore-search-mcp-service-role(trustsbedrock-agentcore.amazonaws.com; inline policy allowingInvokeGateway+InvokeWebSearch) - AgentCore Gateway
agentcore-search-mcp(MCP protocol,AWS_IAMauthorizer) - Web Search connector target
web-search-tool(created via the SigV4 control-plane REST API — the connector target shape isn't expressible in the aws CLI yet)
On success it prints the AGENTCORE_GATEWAY_URL, a ready-to-run claude mcp add command, and a smoke-test one-liner. Names are overridable via GATEWAY_NAME / TARGET_NAME / ROLE_NAME env vars. Requires deploy-time permissions for IAM role creation and bedrock-agentcore-control (gateway CRUD) — broader than the runtime invoke-only permission. Teardown is manual (console or aws bedrock-agentcore-control delete-gateway-target / delete-gateway, then delete the IAM role).
Installation
From this directory (agentcore-search-mcp/):
# (a) uv project install
uv sync
# (b) run ad hoc with uvx (no install)
uvx --from /abs/path/to/agentcore-search-mcp agentcore-search-mcp --version
# (c) pip
pip install /abs/path/to/agentcore-search-mcp
Verify: uv run agentcore-search-mcp --version prints agentcore-search-mcp 0.1.0.
Once the package is published to PyPI (see RELEASING.md), the path-free form uvx agentcore-search-mcp also works, and the client configs below can use "command": "uvx", "args": ["agentcore-search-mcp"] instead of the --directory form.
Configuration
All configuration is via environment variables:
| Variable | Required | Default | Description |
|---|---|---|---|
AGENTCORE_GATEWAY_URL |
yes | — | Gateway MCP endpoint: https://<gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com/mcp |
AGENTCORE_GATEWAY_REGION |
no | us-east-1 |
Region used for SigV4 signing (must match the gateway's region) |
AGENTCORE_SEARCH_TIMEOUT |
no | 30 |
Upstream HTTP timeout in seconds |
AWS_PROFILE / AWS_ACCESS_KEY_ID etc. |
yes (any chain) | — | Standard AWS credential chain used for signing |
Client setup
Claude Code
One-liner (project scope):
claude mcp add agentcore-search --scope project \
--env AGENTCORE_GATEWAY_URL=https://<gateway-id>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp \
--env AGENTCORE_GATEWAY_REGION=us-east-1 \
-- uv --directory /abs/path/to/agentcore-search-mcp run agentcore-search-mcp
Or add to .mcp.json (see .mcp.json.example):
{
"mcpServers": {
"agentcore-search": {
"command": "uv",
"args": ["--directory", "/abs/path/to/agentcore-search-mcp", "run", "agentcore-search-mcp"],
"env": {
"AGENTCORE_GATEWAY_URL": "https://<gateway-id>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp",
"AGENTCORE_GATEWAY_REGION": "us-east-1"
}
}
}
}
Codex
codex mcp add agentcore-search \
--env AGENTCORE_GATEWAY_URL=https://<gateway-id>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp \
-- uv --directory /abs/path/to/agentcore-search-mcp run agentcore-search-mcp
Or in ~/.codex/config.toml:
[mcp_servers.agentcore-search]
command = "uv"
args = ["--directory", "/abs/path/to/agentcore-search-mcp", "run", "agentcore-search-mcp"]
env = { AGENTCORE_GATEWAY_URL = "https://<gateway-id>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp" }
Cursor
.cursor/mcp.json in your project (same JSON shape as the Claude Code .mcp.json block above).
Generic MCP client
Spawn uv --directory /abs/path/to/agentcore-search-mcp run agentcore-search-mcp as a stdio subprocess with the env vars set; then initialize → tools/list → tools/call web_search.
Verify
claude mcp list(or your client's equivalent) showsagentcore-searchas connected.- In the client, ask: "Use the web_search tool to find the latest AWS Bedrock announcements."
- Direct smoke test without a client:
AGENTCORE_GATEWAY_URL=https://<gateway-id>.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp \
uv run python scripts/live_smoke.py
Transports
- stdio (default) — what all desktop MCP clients use.
- streamable-http —
agentcore-search-mcp --transport streamable-http --port 8900for shared/remote use. The HTTP listener has no auth of its own; bind it to localhost or front it with your own auth layer.
Troubleshooting
| Symptom | Cause / fix |
|---|---|
HTTP 403 from the gateway |
Credentials missing/expired, no permission on the gateway resource, or AGENTCORE_GATEWAY_REGION doesn't match the gateway's region (SigV4 scope mismatch) |
does not expose a 'WebSearch' tool |
Wrong gateway URL, or the Web Search connector target isn't attached to this gateway — the error lists the tools that ARE available |
Fewer results than max_results |
Intentional: results without a source URL (url: null) are filtered out |
| Timeouts | Raise AGENTCORE_SEARCH_TIMEOUT; check network egress to *.gateway.bedrock-agentcore.<region>.amazonaws.com |
AGENTCORE_GATEWAY_URL is not set |
Set the env var in the client's MCP server config (env block), not just your shell |
Limitations
- Queries are truncated to 200 characters (gateway limit).
- At most 25 results per call.
allowed_domains/blocked_domains/ user-location filtering are not supported by the AgentCore Web Search connector.
Metadata
Release files for agentcore-search-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentcore_search_mcp-0.1.0.tar.gz | 111.6 kB | Without provenance | Details for agentcore_search_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentcore_search_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agentcore_search_mcp-0.1.0-py3-none-any.whl |
Total release size: 121.7 kB
Release files / agentcore_search_mcp-0.1.0.tar.gz
| Download URL | agentcore_search_mcp-0.1.0.tar.gz |
|---|---|
| Size | 111.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
24c31a4b3030304ebd1fc27b359f40d2a438b4b3cb37eb20f0c6d2a573153538
|
|
BLAKE2b-256 checksum How to use checksums |
2d82bbfc7181858651dabe9e039e6b4998006beb0246b38a2f0c34f55b5e7878
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.8.15
|
Release files / agentcore_search_mcp-0.1.0-py3-none-any.whl
| Download URL | agentcore_search_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 10.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ffe65c4fd7580edcce7955f7ce9298ed8e98107722bafe28f9c6646bbefa1b00
|
|
BLAKE2b-256 checksum How to use checksums |
0f0b3503996d51f192c966f9c0469f485c4840824141f36ad9e3e4cf4e051d79
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.8.15
|
Security for agentcore-search-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.