option1-iam-credentials

Option 1: Local Access via AWS IAM Credentials

The simplest path. Your MCP server runs on AgentCore Runtime, and clients authenticate using AWS IAM credentials (SigV4) via mcp-proxy-for-aws.

Architecture

flowchart LR
    CC["Claude Code<br/>(MCP Client)"]
    PP["mcp-proxy-for-aws<br/>(local stdio proxy)"]
    RT["AgentCore Runtime<br/>(MCP Server)"]

    CC -- "stdio" --> PP
    PP -- "SigV4 / HTTPS" --> RT
    RT -. "responses" .-> PP
    PP -. "responses" .-> CC

Loading

How It Works

1. Claude Code spawns mcp-proxy-for-aws as a child process (stdio transport)
2. The proxy intercepts MCP requests, signs them with SigV4 using your local AWS credentials, and forwards to AgentCore Runtime
3. Runtime validates the SigV4 signature against IAM, then routes to your MCP server container
4. Responses flow back through the same path

Trade-offs

Pros	Cons
Simplest setup — 2 commands to deploy	Every user needs AWS credentials configured
No extra infrastructure beyond Runtime	Not suitable for non-AWS users or external sharing
Zero auth code in your server	Credential management is per-machine (profiles, SSO, env vars)
mcp-proxy-for-aws handles everything	Extra local process (the proxy) runs alongside Claude Code

When to Use This

• You're a developer with AWS credentials already configured
• Your team all has IAM access to the same account
• You want the fastest path from local MCP server to cloud deployment
• Security is handled at the IAM level (policies, roles, permission boundaries)

Prerequisites

• Completed common setup (server tested locally)
• AWS credentials configured (aws configure, AWS_PROFILE, or IAM role)
• uv or uvx installed

Step 1: Deploy to AgentCore Runtime

Run the setup script:

cd option1-iam-credentials
./setup.sh

The script will:

1. Install the AgentCore Starter Toolkit (if not present)
2. Run agentcore configure (interactive — accept defaults for execution role and ECR repo)
3. Run agentcore launch to build, push, and deploy
4. Build the invocation URL from the resulting Agent ARN
5. Configure Claude Code with the remote MCP server

See setup.sh for the full script.

Finch users: set export CDK_DOCKER=$(which finch) before running. You may also need finch vm start.

Step 2: Verify

Restart Claude Code (or start a new session), then:

1. Run /mcp — ddgs-search-remote should appear in the server list
2. Ask Claude: "Search the web for 'AgentCore MCP tutorial'"
3. Claude calls ddgs_search via the remote server and returns results

You can also test directly:

export AGENT_ARN="<your-arn-from-setup-output>"
python test_remote.py

Cleanup

./cleanup.sh

This destroys the AgentCore Runtime resources and removes the MCP server from Claude Code.

Troubleshooting

Symptom	Cause	Fix
SigV4 auth errors	Wrong profile or region	Set AWS_PROFILE and AWS_REGION
Container build fails	Docker/Finch not running	Start Docker or finch vm start
agentcore launch permission error	Missing IAM permissions	Need bedrock-agentcore:* and ecr:*
Timeout on first call	Cold start	AgentCore Runtime cold starts take 30-60s; retry
Slow first uvx run	Downloading proxy package	Normal; cached after first run