Bedrock Managed Knowledge Base with AgentCore MCP Gateway

A CDK project that deploys a fully managed Amazon Bedrock Knowledge Base backed by S3, exposed as an MCP server via AgentCore Gateway. This allows AI assistants like Claude Code and Kiro to query your documents through the standard MCP protocol.

Architecture

┌─────────────┐     ┌───────────────────────┐     ┌──────────────────────┐
│  S3 Bucket  │────▶│  Managed Knowledge    │────▶│  AgentCore Gateway   │
│  (Documents)│     │  Base (Bedrock)        │     │  (MCP Server)        │
└─────────────┘     │  - Managed embeddings │     │  - Retrieve          │
                    │  - Managed vector store│     │  - AgenticRetrieve   │
                    │  - Managed reranker    │     │    Stream             │
                    └───────────────────────┘     └──────────┬───────────┘
                                                             │
                                                    AWS IAM (SigV4)
                                                             │
                                                 ┌───────────┴───────────┐
                                                 │   MCP Clients         │
                                                 │   (Claude Code, Kiro) │
                                                 └───────────────────────┘

Project Structure

bedrock_kb/
├── app.py                  # CDK app entry point
├── cdk.json                # CDK configuration
├── pyproject.toml          # Python project (managed by uv)
├── .mcp.json.example       # MCP server config template for Claude Code
├── bedrock_kb/
│   ├── __init__.py
│   └── stack.py            # CDK stack definition
├── tests/
│   ├── __init__.py
│   └── test_stack.py       # Infrastructure tests
└── scripts/
    └── sync_and_ingest.sh  # Upload docs & trigger ingestion

Prerequisites

• Python 3.13+
• uv (Python package manager)
• AWS CDK CLI (npm install -g aws-cdk)
• AWS credentials configured (aws configure)

Deploy

# 1. Bootstrap CDK (one-time per account/region)
cdk bootstrap aws://<ACCOUNT_ID>/us-east-1

# 2. Deploy the stack
uv run cdk deploy --context account=<ACCOUNT_ID> --context region=us-east-1

Note the outputs after deployment:

• BucketName — where to upload your documents
• KnowledgeBaseId — the Bedrock KB identifier
• GatewayUrl — the MCP server endpoint
• GatewayIdentifier — the gateway ID

Upload Documents and Trigger Ingestion

Place your documents (PDF, TXT, MD, HTML, DOCX, CSV) in a local directory, then:

./scripts/sync_and_ingest.sh ./my-docs/

This syncs files to S3 and starts a Bedrock ingestion job. Monitor progress:

aws bedrock-agent get-ingestion-job \
  --knowledge-base-id <KB_ID> \
  --data-source-id <DS_ID> \
  --ingestion-job-id <JOB_ID>

Adding metadata for filtering

You can attach metadata to any document by placing a .metadata.json companion file next to it in S3. The metadata file must be named exactly <filename>.metadata.json and sit in the same directory. This enables filtering search results by custom attributes like department, document type, or date.

Folder structure:

my-docs/
├── compliance/
│   ├── company-policy.pdf
│   └── company-policy.pdf.metadata.json
└── technical/
    ├── architecture-guide.md
    └── architecture-guide.md.metadata.json

Metadata file format (company-policy.pdf.metadata.json):

{
  "metadataAttributes": {
    "department": "HR",
    "document_type": "Policy",
    "year": "2026",
    "public": "false"
  }
}

The metadataAttributes object contains key-value pairs that Bedrock indexes alongside the document content. When querying via the Retrieve tool, you can filter results using these attributes (e.g., only return documents where department = "Engineering").

Connect Claude Code

AgentCore Gateway requires AWS SigV4-signed requests (service bedrock-agentcore). Since Claude Code doesn't natively sign MCP requests with AWS credentials, we use mcp-proxy-for-aws — an AWS-provided stdio MCP proxy that:

1. Receives MCP requests from Claude Code over stdin/stdout
2. Signs them with your local AWS credentials (from ~/.aws/credentials, env vars, or SSO)
3. Forwards them to the AgentCore Gateway over HTTPS
4. Streams responses back to Claude Code

Option A: use it from anywhere (recommended)

Your knowledge base isn't tied to this repo, so register the MCP server at user scope — it becomes available in every project, not just this one. Use uvx (not uv run) so the proxy runs standalone without needing this project's venv:

claude mcp add bedrock-kb --scope user -- uvx mcp-proxy-for-aws https://<GATEWAY_URL>/mcp --region us-east-1

Replace <GATEWAY_URL> with the GatewayUrl output from your deploy. This is stored in your global Claude config (~/.claude.json), so re-run the command (it overwrites) any time you redeploy and the Gateway URL changes.

Option B: scope it to this project only

Copy the included .mcp.json.example template to .mcp.json and fill in the GatewayUrl output:

cp .mcp.json.example .mcp.json
# then edit .mcp.json, replacing <GATEWAY_URL> with the GatewayUrl output value

.mcp.json is gitignored since it embeds an account/region-specific endpoint. With this option Claude Code only loads the server when run inside this directory, and you'll need to approve the bedrock-kb MCP server when prompted.

IAM permissions for the caller

Your IAM identity (user or role) needs permission to invoke the gateway:

{
  "Effect": "Allow",
  "Action": "bedrock-agentcore:InvokeGateway",
  "Resource": "arn:aws:bedrock-agentcore:us-east-1:<ACCOUNT>:gateway/<GATEWAY_ID>"
}

Exposed MCP Tools

Once connected, your MCP client will have access to two tools:

Tool	Description
Retrieve	Simple semantic search — returns relevant document chunks
AgenticRetrieveStream	Advanced multi-hop reasoning with managed reranking — recursively decomposes complex queries

Run Tests

uv run pytest tests/ -v

Destroy

uv run cdk destroy --context account=<ACCOUNT_ID> --context region=us-east-1