# 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](https://docs.astral.sh/uv/) (Python package manager)
- AWS CDK CLI (`npm install -g aws-cdk`)
- AWS credentials configured (`aws configure`)

## Deploy

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

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

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

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

```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`](https://pypi.org/project/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:

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

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

```json
{
  "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

```bash
uv run pytest tests/ -v
```

## Destroy

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