内容
# AgentCore 기반 웹 검색 MCP
AgentCore 기반 웹 검색 MCP — Bedrock 경유 Claude Code/Codex에 웹 검색을 붙이는 방법.
## 왜 만들었나
Bedrock으로 쓰는 Claude Code에는 기본적인 웹 검색 기능이 없다. MCP로 AgentCore의 관리형 `웹 검색` 커넥터를 노출하면, 모델·클라이언트와 무관하게 웹 검색 능력을 붙일 수 있다 — Bedrock의 한계를 우회한다.
로컬 `mcp-proxy-for-aws`(stdio)가 요청에 AWS SigV4 서명을 붙여 AgentCore Gateway(AWS_IAM 인바운드)로 보내고, Gateway는 AWS 관리형 `웹 검색` 커넥터를 호출한다. 검색 쿼리는 AWS 밖으로 나가지 않는다.
## 아키텍처
```mermaid
flowchart LR
subgraph local["로컬 · MCP 클라이언트 호스트"]
client["MCP 클라이언트<br/>(Claude Code / Codex)"]
proxy["mcp-proxy-for-aws<br/>uvx · stdio"]
client -->|"tools/list · tools/call"| proxy
end
subgraph aws["Amazon Bedrock AgentCore · us-east-1"]
gw["AgentCore Gateway<br/>AWS_IAM 인바운드 · MCP"]
role{{"IAM 역할<br/>agentcore-websearch-gw-role"}}
tgt["Gateway 대상<br/>웹 검색 커넥터 v1.1.0"]
ws[["AWS 관리형 웹 검색<br/>웹 검색.v1<br/>자체 웹 인덱스 · 쿼리 외부 미유출"]]
gw -->|"sts:AssumeRole"| role
gw -->|"route"| tgt
tgt -->|"InvokeWebSearch"| ws
end
proxy ==>|"HTTPS · SigV4<br/>(로컬 AWS 자격증명)"| gw
```
MCP 클라이언트가 stdio로 보낸 요청을 로컬 프록시가 SigV4로 서명해 AWS_IAM 인바운드 Gateway로 전달하고, Gateway가 서비스 역할을 가정해 관리형 `웹 검색` 커넥터를 호출하는 구조다. 상세 설명은 [docs/architecture.md](./docs/architecture.md) 참조.
## 빠른 시작
두 가지 경로가 있다.
### A. 스크립트 (빠름)
AWS CLI만으로 gateway + target + IAM 역할을 만든다.
```bash
export AWS_REGION=us-east-1
export NAME_PREFIX=agentcore-web-search
./scripts/setup.sh
./scripts/test-search.sh
```
`setup.sh`는 멱등(이미 있으면 건너뜀)이며 마지막에 Gateway URL을 출력한다. 상세 CLI 절차는 [docs/setup.md](./docs/setup.md) 참조.
### B. CDK (정식 IaC)
팀·프로덕션에서 상태 관리하며 배포하려면 CDK 경로를 쓴다.
```bash
cd infra/cdk
npm install
npx cdk deploy
```
`namePrefix` 컨텍스트로 리소스 이름을 바꿀 수 있다: `npx cdk deploy -c namePrefix=my-web-search`. 상세는 [infra/cdk/README.md](./infra/cdk/README.md) 참조.
## MCP 클라이언트 설정
[config/mcp.json.example](./config/mcp.json.example)을 복사한 뒤 `<GATEWAY_ID>`와 `<REGION>`을 만들어진 gateway 값으로 바꾼다.
```json
{
"mcpServers": {
"agentcore-web-search": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-proxy-for-aws@1.6.3",
"https://<GATEWAY_ID>.gateway.bedrock-agentcore.<REGION>.amazonaws.com/mcp",
"--service",
"bedrock-agentcore",
"--region",
"<REGION>"
],
"env": {}
}
}
}
```
- **Claude Code**: `~/.claude.json`(전역) 또는 프로젝트 루트의 `.mcp.json`(프로젝트별)에 위 `mcpServers` 블록을 추가한다.
- **Codex**: Codex의 MCP 설정 파일에 동일한 서버 정의를 추가한다.
로컬 AWS 자격증명(예: `AWS_PROFILE` 또는 기본 자격증명 체인)이 SigV4 서명에 사용된다.
## 정리
만든 리소스를 지우려면 teardown 스크립트를 쓴다. 기본은 dry-run이며, 실제 삭제하려면 `--yes`가 필요하다.
```bash
./scripts/teardown.sh # dry-run: 삭제될 리소스만 출력
./scripts/teardown.sh --yes # 실제 삭제
```
## FAQ
**Q. 왜 IAM 인바운드 인증(AWS_IAM)인가?**
별도의 identity provider(OAuth/Cognito) 없이, 로컬에 이미 있는 AWS 자격증명으로 SigV4 서명만 하면 되기 때문이다. 추가 인증 인프라가 필요 없다.
**Q. 검색 쿼리가 외부로 나가나?**
아니오. AWS 관리형 웹 검색은 AWS 자체 웹 인덱스를 사용하며, third-party 검색 엔진을 경유하지 않는다. 쿼리는 AWS 밖으로 나가지 않는다.
**Q. 비용은?**
관리형 `웹 검색` 호출과 Gateway 호출에 대해 과금된다. 정확한 요금은 AWS 요금 페이지를 참조한다.
**Q. 다른 리전에서 쓸 수 있나?**
`AWS_REGION`(스크립트) 또는 `namePrefix`/`CDK_DEFAULT_REGION`(CDK)과 `config/mcp.json.example`의 `<REGION>`을 해당 리전으로 맞추면 된다. `bedrock-agentcore-control`이 제공되는 리전이어야 한다.
## 디렉터리 구조
```
agentcore-web-search/
├── README.md # 한국어 메인 (이 문서)
├── LICENSE # MIT
├── .gitignore
├── docs/
│ ├── architecture.md # 상세 아키텍처 + 다이어그램
│ └── setup.md # 수동 AWS CLI 구성 가이드
├── scripts/
│ ├── setup.sh # IAM 역할 → Gateway → 대상 생성 (멱등)
│ ├── teardown.sh # 역순 삭제 (기본 dry-run)
│ └── test-search.sh # tools/list + 검색 1회 스모크 테스트
├── infra/cdk/ # 정식 IaC (AWS CDK, TypeScript)
│ ├── bin/app.ts
│ ├── lib/websearch-gateway-stack.ts
│ ├── package.json
│ ├── tsconfig.json
│ ├── cdk.json
│ └── README.md
└── config/
└── mcp.json.example # Claude Code / Codex MCP 설정 스니펫
```
## 라이선스
MIT — [LICENSE](./LICENSE) 참조.
