Skip to content

CLAUDE.md

Latest commit

 

History

History
85 lines (60 loc) · 3.46 KB

CLAUDE.md

File metadata and controls

85 lines (60 loc) · 3.46 KB

CLAUDE.md

What This Repo Is

A tutorial for deploying a DuckDuckGo search MCP server to Amazon Bedrock AgentCore with three authentication options:

  • Option 1 (option1-iam-credentials/): IAM credentials via SigV4 + mcp-proxy-for-aws
  • Option 2 (option2-identity-inbound-auth/): OAuth login via Cognito + JWT authorizer on Runtime
  • Option 3 (option3-gateway-oauth/): Enterprise OAuth via Gateway + 2x Cognito + credential provider

The MCP server code in server/ is shared by all options. Each option folder has its own setup scripts, cleanup scripts, test client, and README walkthrough.

Deploying

When asked to deploy, ask which option the user wants. All options require:

  • python3 3.10+
  • aws CLI with credentials (aws sts get-caller-identity)
  • Docker or Finch running (docker info or finch vm status)
  • pip install bedrock-agentcore-starter-toolkit (provides agentcore CLI)

Option 1

cd option1-iam-credentials && ./setup.sh

Interactive — the agentcore configure prompts need a TTY. Let the user run it.

Option 2

cd option2-identity-inbound-auth
python setup_cognito.py --region us-east-1 --create-test-user
python deploy_runtime.py

deploy_runtime.py runs agentcore configure non-interactively by piping stdin. It uses these flags to avoid prompts: -n <name>, -rf requirements.txt, --ecr auto, --authorizer-config <json>, --disable-memory. After deploy, it prints the ~/.claude.json config block.

Option 3

cd option3-gateway-oauth
python setup.py --region us-east-1
python deploy_target.py

setup.py creates all infrastructure via boto3 (IAM role, 2 Cognito pools, Gateway, credential provider). deploy_target.py deploys the MCP server to Runtime and registers it as a Gateway target.

Cleaning Up

Always clean up after testing — these scripts create real AWS resources.

# Option 1
cd option1-iam-credentials && ./cleanup.sh

# Option 2
cd option2-identity-inbound-auth && python cleanup.py

# Option 3
cd option3-gateway-oauth && python cleanup.py

Key Technical Details

  • Server must bind to 0.0.0.0:8000 with stateless_http=True for AgentCore
  • agentcore configure is interactive by default — use piped stdin + explicit flags to automate
  • agentcore destroy requires confirmation — pipe y\n via input param in subprocess
  • Options 2/3 use Claude Code's native HTTP transport (type: http) with OAuth, not mcp-proxy-for-aws
  • Options 2/3 require authServerMetadataUrl in Claude Code config because AgentCore doesn't yet serve /.well-known/oauth-authorization-server (tracking: github.com/awslabs/agentcore-samples/issues/1056)
  • Gateway tool names use triple underscore separator: <target-name>___<tool-name>
  • list_gateway_targets API returns targets in items key (not targets)
  • Gateway targets must be deleted before the Gateway itself can be deleted
  • Config files (cognito_config.json, deploy_config.json, gateway_config.json) are gitignored — generated by setup scripts

Modifying the Server

If you change server/server.py:

  1. Test locally first: cd server && python server.py + python test_local.py
  2. Redeploy with the same option scripts — they rebuild the container

Do Not

  • Commit generated config files (*_config.json, .bedrock_agentcore.yaml)
  • Leave AWS resources running after testing — always run cleanup
  • Use agentcore configure in a subprocess without piping stdin or providing all flags