DEV Community: Dennis Traub

8 Agents Wrote Perfect Components - And Nothing Worked

Dennis Traub — Fri, 27 Mar 2026 22:50:44 +0000

TL;DR: Parallel AI agents don't coordinate on shared contracts, such as column names, URL paths, parameter formats, or identifiers. Extract those contracts into a single reference file before generation, and run a review agent that traces end-to-end data flows once the parallel agents are done. This single step fixed all 17 bugs in one pass.

I launched 8 AI agents in parallel to build a full-stack app on AWS: infrastructure stacks, a React frontend, and a Java backend. Each agent owned one piece, and they all delivered clean, compiling code. The CDK type-checked, the Java backend followed Spring Boot conventions, the React UI looked nice.

But when I tried to wire them together I hit bugs at every single boundary.

The architecture

A full-stack app on AWS with a lot of moving parts. Multiple CDK stacks for the infrastructure (IAM, VPC, DB with seed functions, Cognito, CodePipeline, CloudFront/WAF), a Spring Boot backend on ECS Fargate, and a React frontend hosted on S3.

The implementation plan was thorough and covered every component. But it wasn't detailed enough for agents that need to agree on shared contracts.

The bugs

The first two block everything. Bugs 3 through 5 only show up after you fix the previous ones.

Bug 1: The Spring Boot app won't even start

The seed data function creates a schema with passenger_id and full_name, but the Spring Boot entity maps to id and name:

-- Agent 1: seed data function creates the schema
CREATE TABLE passengers (
    passenger_id   VARCHAR(64) PRIMARY KEY,
    full_name      VARCHAR(255) NOT NULL,
    ...
);

// Agent 2: The Spring Boot entity maps the table
@Column(name = "id")       // Schema says "passenger_id"
@Column(name = "name")     // Schema says "full_name"

With ddl-auto: validate, Hibernate checks the mapping on startup. But the columns don't exist, so the ECS task crashes before serving a single request.

Bug 2: Every call returns 404

The CDK stack registers ALB routes for /approve and /generate while the Java client sends requests to /voucher/approve and /voucher/generate:

CDK ALB routes:  /approve, /generate
Java client:     /voucher/approve, /voucher/generate

Both agents wrote correct, working code in isolation, but the CDK stack used clean paths while the Java client added a service prefix. Neither checked the other.

Bug 3: Missing request fields

A downstream service validates four required fields. The Java client sends three:

Lambda expects:  escalationId, passengerId, amount, situation
Java sends:      escalationId, passengerId, amount

Even with the URLs from bug 2 fixed, every approval returns 400.

Bug 4: User lookup doesn't work

This one was the most interesting: three systems work with the user, and each of them created their own identifier:

Cognito custom attribute:  custom:passenger_id = "pax-a1b2c3d4-e5f6-..."
RDS seed data:             passenger_id = "PAX-a1b2c3d4-e5f6-..."
JWT subject claim:         sub = "a1b2c3d4-e5f6-..."  (Cognito UUID)

The backend uses jwt.getSubject() to look up the user. That's a Cognito UUID - neither prefixed with pax- nor with PAX-. No user lookup ever returns a result.

Three agents. Three naming conventions. Zero coordination.

Bug 5: Every status lookup returns "not found"

A downstream service returns JSON. The Java client parses XML:

{"status": "FOUND_LOCAL", "location": "Warehouse-B-Shelf-47"}

String status = extractXmlElement(xml, "status");  // Looks for <status>...</status>

No XML tags in a JSON string. extractXmlElement returns empty for every single request.

The agent that wrote the downstream service followed one spec (JSON). The agent that wrote the Java client followed a different spec (XML).

Bugs 6 to 17: SSM parameter path mismatches

One CDK stack writes an SSM parameter. Another CDK stack reads it. But they never coordinated on paths:

Producer stack writes:  /${AppName}/test/data/rds-secret-arn
Consumer stack reads:   /${AppName}/${Env}/data/rds-password-secret-arn

...

Twelve SSM parameters mismatched between producer and consumer stacks. The app fails on every one of them.

Why parallel agents can't catch this

Each agent had context about the overall plan and its own component. But none of them could see the implementation details that the others came up with.

When I write an app, I hold the contracts in working memory. "The column is passenger_id, so I'll use that in both the migration and the entity." But an AI agent writing the migration doesn't know what the entity agent chose for its column name - and vice versa.

The plan contained all the high-level information, but the agents were reading different sections and making their own calls on the shared details.

Each agent wrote correct code that followed good conventions. But they never coordinated. Like digging a tunnel from two sides of a mountain - without ever checking in with each other.

How I found all of them at once

After generation, before actually deploying the app. I ran an architecture review agent with a simple instruction:

Trace the actual data flow from user login through form submission to the downstream service calls, following every cross-component boundary.

It found every one of the bugs in a single pass.

The review agent started at the user-facing entry point, traced the request through every boundary, and at each one checked whether what one component sent actually matched what the next one expected. Same thing integration tests do after deployment, but you catch it before deploying anything.

How to prevent seam bugs

Before launching parallel agents, pull every shared contract out of the plan into a single reference file and pass it to every agent as mandatory context.

Then, after your parallel agents did their thing, run a review agent that traces a few real user flows across all the boundaries.

Fix the seam bugs in one pass, then deploy.

FAQ

What are seam bugs in AI-generated code?

Seam bugs are integration defects at the boundaries between components built by different AI agents. Each agent writes correct, working code in isolation, but the components don't fit together because the agents each made their own decisions about shared details - things like what a column is called, what path an API lives at, or what format an identifier uses.

Why does parallel AI code generation produce integration bugs?

Each agent only sees its own component and the plan it was given. When two agents need to agree on something - say, what a database column is called - they each pick a reasonable name independently. Those names often don't match. The plan says what the column should represent, but not necessarily the exact string both sides should use.

How do you catch integration bugs from parallel AI agents?

Run a single review agent after generation that traces real user flows across all the boundaries. Give it a prompt like "trace the data flow from user login through the frontend, backend, to databases and downstream service calls, checking every boundary." It will catch the mismatches in one pass.

My 8 Agents Wrote Perfect Components - And Nothing Worked

Dennis Traub — Fri, 27 Mar 2026 22:50:44 +0000

But when I tried to wire them together I hit bugs at every single boundary.

The architecture

The implementation plan was thorough and covered every component. But it wasn't detailed enough for agents that need to agree on shared contracts.

The bugs

The first two block everything. Bugs 3 through 5 only show up after you fix the previous ones.

Bug 1: The Spring Boot app won't even start

The seed data function creates a schema with passenger_id and full_name, but the Spring Boot entity maps to id and name:

-- Agent 1: seed data function creates the schema
CREATE TABLE passengers (
    passenger_id   VARCHAR(64) PRIMARY KEY,
    full_name      VARCHAR(255) NOT NULL,
    ...
);

// Agent 2: The Spring Boot entity maps the table
@Column(name = "id")       // Schema says "passenger_id"
@Column(name = "name")     // Schema says "full_name"

With ddl-auto: validate, Hibernate checks the mapping on startup. But the columns don't exist, so the ECS task crashes before serving a single request.

Bug 2: Every call returns 404

The CDK stack registers ALB routes for /approve and /generate while the Java client sends requests to /voucher/approve and /voucher/generate:

CDK ALB routes:  /approve, /generate
Java client:     /voucher/approve, /voucher/generate

Both agents wrote correct, working code in isolation, but the CDK stack used clean paths while the Java client added a service prefix. Neither checked the other.

Bug 3: Missing request fields

A downstream service validates four required fields. The Java client sends three:

Lambda expects:  escalationId, passengerId, amount, situation
Java sends:      escalationId, passengerId, amount

Even with the URLs from bug 2 fixed, every approval returns 400.

Bug 4: User lookup doesn't work

This one was the most interesting: three systems work with the user, and each of them created their own identifier:

Cognito custom attribute:  custom:passenger_id = "pax-a1b2c3d4-e5f6-..."
RDS seed data:             passenger_id = "PAX-a1b2c3d4-e5f6-..."
JWT subject claim:         sub = "a1b2c3d4-e5f6-..."  (Cognito UUID)

The backend uses jwt.getSubject() to look up the user. That's a Cognito UUID - neither prefixed with pax- nor with PAX-. No user lookup ever returns a result.

Three agents. Three naming conventions. Zero coordination.

Bug 5: Every status lookup returns "not found"

A downstream service returns JSON. The Java client parses XML:

{"status": "FOUND_LOCAL", "location": "Warehouse-B-Shelf-47"}

String status = extractXmlElement(xml, "status");  // Looks for <status>...</status>

No XML tags in a JSON string. extractXmlElement returns empty for every single request.

The agent that wrote the downstream service followed one spec (JSON). The agent that wrote the Java client followed a different spec (XML).

Bugs 6 to 17: SSM parameter path mismatches

One CDK stack writes an SSM parameter. Another CDK stack reads it. But they never coordinated on paths:

Producer stack writes:  /${AppName}/test/data/rds-secret-arn
Consumer stack reads:   /${AppName}/${Env}/data/rds-password-secret-arn

...

Twelve SSM parameters mismatched between producer and consumer stacks. The app fails on every one of them.

Why parallel agents can't catch this

Each agent had context about the overall plan and its own component. But none of them could see the implementation details that the others came up with.

The plan contained all the high-level information, but the agents were reading different sections and making their own calls on the shared details.

Each agent wrote correct code that followed good conventions. But they never coordinated. Like digging a tunnel from two sides of a mountain - without ever checking in with each other.

How I found all of them at once

After generation, before actually deploying the app. I ran an architecture review agent with a simple instruction:

Trace the actual data flow from user login through form 
submission to the downstream service calls, following every 
cross-component boundary.

It found every one of the bugs in a single pass.

How to prevent seam bugs

Before launching parallel agents, pull every shared contract out of the plan into a single reference file and pass it to every agent as mandatory context.

Then, after your parallel agents did their thing, run a review agent that traces a few real user flows across all the boundaries.

Fix the seam bugs in one pass, then deploy.

FAQ

What are seam bugs in AI-generated code?

Why does parallel AI code generation produce integration bugs?

How do you catch integration bugs from parallel AI agents?

Missing from the MCP debate: Who holds the keys when 50 agents access 50 APIs?

Dennis Traub — Wed, 18 Mar 2026 12:35:57 +0000

There are two debates happening right now:

CLI vs MCP - should agents call existing CLIs or use an MCP server? And API vs MCP - does wrapping a REST API in an MCP server add value, or just complexity?

Both focus on how agents call tools. What both aren't asking is, who holds the credentials when they do.

Fifty agents, fifty sets of keys

When one developer runs one agent on one laptop, credentials are simple. You store them locally, maybe rotate them, and move on.

But that's not where we're heading. Dozens of agents per team, each needing access to Slack, GitHub, Jira, Office 365, that legacy CRM, multiple SaaS tools, and all your internal APIs.

Some of those have CLIs. Most don't - they're SaaS products with REST APIs. If you're lucky - who knows how many production systems still use a global, password-protected admin account.

So every agent needs a separate API key, OAuth token, or username/password pair. For each downstream system. On every machine. And if you've ever managed API keys for a team, you know where this goes. Keys in .env files, shared over Slack, committed to repos, never rotated.

Now hand that problem to fifty autonomous agents.

What happened to SSO?

Most organizations with any sense of security have established SSO, spent years consolidating identity. Every SaaS tool, every internal system, every third-party integration flows through one identity provider.

When someone leaves, you disable a single account. When compliance asks about access controls, there's one answer - and you know exactly where to find it.

And now, agents are about to blow a wide open hole into everything you've built. Whether your agent calls a CLI, hits a REST API, or talks to an MCP server, it needs credentials. And if those credentials live on the agent's machine, they live outside your identity boundary.

Imagine a contractor wrapping up on Friday. You disable their SSO account, but their laptop still has three agents with API keys for your CRM, your internal docs, and your deployment pipeline. Those keys don't expire with the SSO account. Those agents can continue calling your APIs long after the contractor has moved on.

Remote MCP servers are identity boundaries

This is where remote MCP servers earn their place in both debates.

The CLI vs MCP crowd argues about token efficiency. The API vs MCP crowd argues about unnecessary abstraction. Neither side is talking about the nightmare of decentralized credential management.

Charles Chen makes this point well in MCP is Dead; Long Live MCP!. Most of the debate ignores the difference between MCP over stdio (local, and yeah, mostly pointless compared to raw curl or a CLI) and MCP over streamable HTTP (remote, centralized). Once MCP runs as a centralized server, users authenticate via OAuth and never touch the downstream keys.

As he puts it: "An engineer leaves your team? Revoke their OAuth token and access to the MCP server; they never had access to other keys and secrets to start with."

Now take that one step further. In most organizations, that OAuth isn't standalone - it flows through SSO. The MCP server becomes an identity boundary. Your users never store any API keys, custom tokens, or service accounts. One auth mechanism instead of one per machine per agent per API.

Disable the SSO account, and every agent loses access. To everything.

But we already learned this, right? Every microservice managing its own database credentials was a nightmare until we centralized secrets management. Agent credentials are the same problem, just one layer up.

3 Things I Wish I Knew Before Setting Up a UV Workspace

Dennis Traub — Fri, 27 Feb 2026 17:57:09 +0000

I love uv, it's so much better than pip, but I'm still learning the ins and outs. Today I was setting up a Python monorepo with uv workspaces and ran into a few issues, the fixes of which were trivial once I knew about them.

1. Give the Root a Distinct Name

First, a virtual root (package = false) still needs a [project] name - and it can't match any member package.

I had both the root and my core package using the same name, e.g. my-app:

my-app/                   # workspace root
  pyproject.toml          # name = "my-app" <- problem!
  packages/
    core/
      pyproject.toml      # name = "my-app"
      src/core/
    cli/
      pyproject.toml      # name = "my-app-cli"
      src/cli/

When I ran uv sync, it refused outright:

$ uv sync
error: Two workspace members are both named `my-app`:
  `/path/to/my-app` and `/path/to/my-app/packages/core`

Even though the root has package = false, uv still registers its name as a workspace member identity. Same name, two members, no way to disambiguate.

The fix - give the root a workspace-specific name:

# Root pyproject.toml
[project]
name = "my-app-workspace"  # NOT "my-app"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = []

[tool.uv]
package = false

[tool.uv.workspace]
members = ["packages/*"]

[dependency-groups]
dev = [
    "pytest",
    "ruff",
]

Two things to note: package = false means "don't install me", not "don't need a name". And dev dependencies go in [dependency-groups] (PEP 735), not [project.dependencies] - the root is virtual, so project dependencies are just metadata.

2. Use `workspace = true` for Inter-Package Deps

When one workspace package depends on another, you need two things: a normal dependency declaration and a [tool.uv.sources] entry telling uv to resolve it locally.

# packages/cli/pyproject.toml
[project]
name = "my-app-cli"
dependencies = [
    "my-app",
]

[tool.uv.sources]
my-app = { workspace = true }

Without the [tool.uv.sources] entry, uv sync fails with a helpful but initially confusing error:

$ uv sync
  x Failed to build `my-app-cli @ file:///path/to/packages/cli`
  |-- Failed to parse entry: `my-app`
  \-- `my-app` is included as a workspace member, but is missing
      an entry in `tool.uv.sources`
      (e.g., `my-app = { workspace = true }`)

At least uv tells you exactly what to add.

The [project.dependencies] list stays PEP 621 compliant, so any standard Python tool can read it. The [tool.uv.sources] table is uv-specific and only affects resolution. And uv sync installs the local package as editable automatically - changes are immediately visible without reinstalling.

3. Use `importlib` Mode for pytest

When running pytest across a workspace where multiple packages have tests/ directories with same-named test files (e.g. both have test_helpers.py), pytest's default import mode breaks:

$ uv run pytest packages/ -v
collected 1 item / 1 error

ERROR collecting packages/core/tests/test_helpers.py
import file mismatch:
imported module 'test_helpers' has this __file__ attribute:
  /path/to/packages/cli/tests/test_helpers.py
which is not the same as the test file we want to collect:
  /path/to/packages/core/tests/test_helpers.py
HINT: remove __pycache__ / .pyc files and/or use a unique basename

Pytest's default prepend import mode treats both test_helpers.py as the same module. It imports the first one, caches it, then errors when the second file doesn't match.

The fix - add importlib mode to your root pyproject.toml:

# Root pyproject.toml
[tool.pytest.ini_options]
addopts = "--import-mode=importlib"

$ uv run pytest packages/ -v
packages/cli/tests/test_helpers.py::test_cli_helper PASSED    [ 50%]
packages/core/tests/test_helpers.py::test_core_helper PASSED  [100%]

Note: Don't add __init__.py to your test directories as a workaround - with importlib mode, that can actually cause a silent bug where pytest resolves both files to the same cached module and runs the wrong tests without any error.

This isn't uv-specific - it's a Python monorepo thing. But uv workspaces make monorepos easy to set up, so you're likely to hit it early.

References

How to Use Strands Agents' Built-In Session Persistence

Dennis Traub — Tue, 17 Feb 2026 16:41:10 +0000

Today I learned that the Strands Agents SDK has a built-in persistence layer for conversation history.

Pass a SessionManager to the Agent constructor, and every message and state change is persisted automatically through lifecycle hooks. No manual save/load calls.

The Code

Save this as session_demo.py and run it with uv run session_demo.py.

The # /// script block is PEP 723 inline metadata - uv run reads it to install dependencies automatically, no venv or pip needed. All you need is uv and AWS credentials configured.

# /// script
# requires-python = ">=3.10"
# dependencies = ["strands-agents"]
# ///

from strands import Agent
from strands.session.file_session_manager import FileSessionManager

SESSION_ID = "user-abc-123"
STORAGE_DIR = "./sessions"  # defaults to /tmp/strands/sessions

# First agent instance - ask a question
agent1 = Agent(
    model="global.anthropic.claude-haiku-4-5-20251001-v1:0",
    agent_id="assistant",
    session_manager=FileSessionManager(
        session_id=SESSION_ID, storage_dir=STORAGE_DIR
    ),
)
prompt1 = "What's the capital of France?"
print(f"Prompt: {prompt1}")
agent1(prompt1)
print()

# Second agent instance - same session_id, loads conversation from disk
agent2 = Agent(
    model="global.anthropic.claude-haiku-4-5-20251001-v1:0",
    agent_id="assistant",
    session_manager=FileSessionManager(
        session_id=SESSION_ID, storage_dir=STORAGE_DIR
    ),
)
prompt2 = "What did I just ask you?"
print(f"Prompt: {prompt2}")
agent2(prompt2)
print()

What's happening here:

agent1 and agent2 are separate Agent instances - they share no memory
agent2 can answer "What did I just ask you?" because FileSessionManager restored the conversation from disk when the second instance was created
The agent_id identifies which agent's state to save and restore - required when using a session manager

What Gets Persisted

The session manager saves three things:

Conversation history - all user and assistant messages (the messages/ directory)
Agent state - a JSON-serializable key-value dict you can use for your own data (agent.json)
Session metadata - timestamps and session type (session.json)

After running the script, here's what's on disk:

sessions/
└── session_user-abc-123
    ├── agents
    │   └── agent_assistant
    │       ├── agent.json
    │       └── messages
    │           ├── message_0.json
    │           ├── message_1.json
    │           ├── message_2.json
    │           └── message_3.json
    ├── multi_agents
    └── session.json

Each message is a separate JSON file:

{
  "message": {
    "role": "user",
    "content": [
      {
        "text": "What's the capital of France?"
      }
    ]
  },
  "message_id": 0,
  "created_at": "2026-02-17T14:45:31.439081+00:00"
}

User and assistant turns alternate through message_0.json to message_3.json.

Built-In Backends

The example uses FileSessionManager, but the SDK ships three backends:

Manager	Use Case
`FileSessionManager`	Local development, single-process
`S3SessionManager`	Production, distributed, multi-container
`RepositorySessionManager`	Custom backend (implement `SessionRepository`)

Tips and Notes

Troubleshooting tips

uv: command not found
Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows). See uv installation docs.

NoCredentialError or Unable to locate credentials
AWS credentials aren't configured. Run aws configure to set up a default profile, or export AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. See AWS CLI configuration.

AccessDeniedException when calling the model
Your AWS credentials don't have permission to invoke the Bedrock model. Make sure your IAM user or role has bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream permissions.

Good to know

FileSessionManager is not safe for concurrent same-session writes

Two API requests with the same session_id writing to FileSessionManager concurrently can corrupt the session data. The storage layer has no locking - it reads, appends, and writes the full JSON file without coordination.

For development, this is fine. Single-process, single-user development (CLI, local testing) will never hit this. Sequential requests to the same session are safe.

For production, you have three options:

Per-session locking in your API layer - serialize requests per session_id before they reach the Agent
S3SessionManager - uses atomic S3 operations for safe concurrent writes
A custom SessionRepository - implement your own with proper concurrency handling (database-backed, etc.)

agent_id is required with a session manager

If you omit agent_id when using a SessionManager, you'll get ValueError: agent_id needs to be defined. The session system uses it as a directory key to separate state for different agents within the same session.

FileSessionManager defaults to /tmp

Without an explicit storage_dir, sessions are written to /tmp/strands/sessions - which most operating systems wipe on reboot. Set it to a project-local path like ./sessions or .data/sessions.

References

[Boost]

Dennis Traub — Sun, 15 Feb 2026 11:20:33 +0000

From Zero to Agentic Coding: Running Claude Code with Amazon Bedrock

Gunnar Grosch for AWS ・ Feb 15

#aws #ai #beginners #productivity

Why Your Chatbot is the BlackBerry of the 2020s

Dennis Traub — Fri, 13 Feb 2026 01:58:38 +0000

This is my third major technological shift, and every time I hear the same question echo through the C-Suites:

"But where's the ROI?"

In the 90s, we put our print brochures and yellow pages on the web - and called it digital transformation. In the 2000s, we put tiny keyboards or a Windows start button on a phone and called it mobile computing.

Both times, the answer wasn't better brochures or smaller buttons. The answer was Google and Facebook. It was the iPhone and Android. New ideas, by companies that didn't try to replicate the old world - with all its constraints - on a new medium. They built something entirely new. They embraced the new medium and built what couldn't have existed before.

And now we're doing it again, with AI.

Every demo is a chatbot.
Every pilot is "adding AI to our existing workflow."
Every enterprise use case tries to optimize what already exists.

But this time, it kind of works. And that's the trap.

The web's brochureware visibly broke. The stylus on Windows Mobile was physically painful. But AI chatbots deliver just enough value to feel like progress.

We're settling for 10% of what's possible and call it "revolutionizing the [industry of your choice]".

But the real inflection point isn't better support agents or travel booking chatbots. It's when we stop replicating what's already there and start building something that never existed before.

How a subtle MCP server bug almost cost me $230 a month

Dennis Traub — Wed, 11 Feb 2026 18:23:12 +0000

An important part of my job is to collect and distill feedback into recommendations for product and engineering teams. Sure, not quite as glamorous as traveling the world, but it's a lot of fun: I'm getting paid to experiment with brand new tech - and I get to directly influence the developer experience of our products.

But - just like every job - there's also a lot of routine work involved, including the boring type. And if there's anything my ADHD brain hates - with a passion! - it's boring routine work. And there's one thing right at the top of the list: processing tasks in a project management tool.

So I built an AI agent to help me: triage tasks, add context, draft comments, move items around - all through an MCP server.

As I said. Routine work. Boring and predictable. Right?

Right. Until I noticed the time it needed for what should be simple updates.

Three Calls, Zero Updates

The MCP server has an update_task tool, and the agent called it with a custom_fields parameter. The server took the request, processed it, and returned success.

But when the agent continued, the custom fields were unchanged. It tried updating again - with a different format. Success. But nothing changed. Third attempt. Success. Still nothing.

3 success responses. Zero successful updates. And the API never told the agent that anything was wrong.

Tracking It Down

So after multiple failed attempts, the agent started investigating on its own. It checked whether it had the right access permissions. Or if it can use curl to bypass the MCP layer entirely.

curl worked, showing that the problem wasn't permissions. So it must be the tool itself.

After some more back and forth, the agent discovered that create_batch_request - a completely different MCP tool - is the only way to update custom fields. The update_task tool accepts the custom_fields parameter without complaint, but the parameter isn't actually in the tool's schema. The tool silently drops it, updates everything else, and returns a success message.

Maybe a small issue, if it happened only once.

But my logs showed 16 silently failed attempts across 7 tasks. The same cycle every time: try, get "success," see nothing changed, investigate, try again, finally find a workaround.

The agent kept hitting the same wall because the API never told it the wall existed.

A crash would have been so much better - the agent would see the error and immediately try a different tool. Instead, it got a success response and had to figure out through downstream verification that the "successful" call hadn't been sucessfull after all.

Each time a new agent instance worked on a task, it went through the same process, wasting ~93K tokens just to figure out that there is a problem - and how to solve it. Learning wasn't possible, because there was no error to learn from.

Let's Look at the Math

Every number below comes directly from my session logs.

Metric	Value
Wasted tokens per failed attempt	~93,000
Average failed attempts per task	2.3
Cost per attempt (Claude Opus at $5/MTok)	~$0.47
Cost per task	~$1.08

Now imagine a 5-person team with 10 tasks per person per day.

Timeframe	Per person	Team of 5
Per day (10 tasks)	$10.80	$54
Per month (22 working days)	$238	$1,190
Per year	$2,856	$14,280

This is one parameter, in one MCP tool, on a single workflow. And even that scales really fast.

Two things are worth mentioning: this models the cost before the workaround is discovered. Once you know to use create_batch_request, the waste drops to zero. And it assumes every task hits the bug - which was true in my case, since every triage task needed custom field updates.

The point isn't the exact dollar figure. It's that silent failures delay discovery - possibly indefinitely.

A crash costs one attempt. The agent sees the error, adjusts, moves on. But silent acceptance costs multiple attempts, every time, until you realize there's a problem - if you realize it at all.

In software engineering, there's a concept called "graceful degradation". But if your API - MCP server or not - accepts parameters it can't handle and returns success, you're not being graceful. You're being expensive.

What You can Do

If you build APIs or MCP tools: Add input validation. Reject or warn on unrecognized parameters. My data says that one check would have saved every token and every dollar in this story.

If you build agents: Verify state after every state-changing call. Don't trust success responses - confirm the change actually happened. And make sure your agent surfaces anything it didn't expect.

Some say we don't need to worry about architecture anymore, because AI agents are able to figure things out.

But I think it's the opposite: Software architecture principles become more important with AI, not less.

This is Part 1 of "The Inconsistency Tax" - a 3-part series on what happens when AI agents meet inconsistent APIs. Next: why these failures aren't random, and why "just wrapping an API in an MCP server" doesn't automatically make it agent-ready.

From Local MCP Server to AWS Deployment in Two Commands - The Code-Only Version

Dennis Traub — Mon, 26 Jan 2026 17:30:18 +0000

In this walkthrough, I'll show you the simplest way to deploy an MCP server on AWS, using the Amazon Bedrock AgentCore Runtime - and how to call it with your IAM credentials - no complicated OAuth setup required.

Note: This is a code-only walkthrough. For detailed explanations, see the full tutorial.

Prerequisites

Python and AWS setup

To follow this walkthrough, you'll need:

Python 3.11 or higher,
the uv package manager (or pip),
an AWS account,
and the AWS CLI installed and configured.

Run these commands to verify the prerequisites:

python --version
uv --version     
aws --version
aws sts get-caller-identity --no-cli-pager

To troubleshoot, please follow the links above.

The AgentCore Starter Toolkit

The Bedrock AgentCore Starter Toolkit will simplify the entire process to two commands, agentcore configure and agentcore deploy.

To install it, run:

uv tool install -U bedrock-agentcore-starter-toolkit

Step 1: Create a small MCP server

Prepare a new Python project for the MCP server:

# Start with an empty folder for your project
mkdir mcp-on-agentcore-runtime
cd mcp-on-agentcore-runtime

# Create and cd into a subdirectory for the MCP server
mkdir mcp-server
cd mcp-server

# Initialize a new Python project and add the `mcp` package:
uv init --bare
uv add mcp

Create the MCP server

# Create a simple MCP server in `server.py`:
cat << 'EOF' > server.py
import random
from mcp.server.fastmcp import FastMCP

mcp = FastMCP(host="0.0.0.0", stateless_http=True)

@mcp.tool()
def roll_d20(number_of_dice: int = 1) -> dict:
    """Rolls one or more 20-sided dice (d20)"""
    if number_of_dice < 1:
        return {
            "error": f"number_of_dice must be at least 1"
        }

    rolls = [random.randint(1, 20) for _ in range(number_of_dice)]
    return {
        "number_of_dice": number_of_dice,
        "rolls": rolls,
        "total": sum(rolls)
    }

def main():
    mcp.run(transport="streamable-http")

if __name__ == "__main__":
    main()

EOF

Step 2: Test Locally

In the first terminal:

# Start the MCP server:
uv run server.py

In a second terminal:

List the tools:

# Send a list tools request
curl -X POST http://127.0.0.1:8000/mcp \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{ 
           "jsonrpc": "2.0",
           "id": 1,
           "method": "tools/list"
         }'

# Response:
# event: message
# data: {"jsonrpc":"2.0","id":1,"result":{"tools":[{...}]}}

Call the tool:

# Send a tool call request
curl -X POST http://127.0.0.1:8000/mcp \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{
           "id": 1,
           "jsonrpc": "2.0",
           "method": "tools/call",
           "params": {
             "name": "roll_d20",
             "arguments": { "number_of_dice": 2 }
           }
         }'

# Response:
# event: message
# data: {"jsonrpc":"2.0","id":1,"result":{"content":[{...}]}}

If you see connection errors, ensure the server is running in the other terminal

In the first terminal:

Press Ctrl/Cmd+C to stop the server

Step 3: Configure the deployment AWS

# Navigate back up to the project root
cd ..

# Configure the MCP server deployment.
# This will use the account and region configured in the AWS CLI
agentcore configure \
   --entrypoint mcp-server/server.py \
   --requirements-file mcp-server/pyproject.toml \
   --disable-memory --disable-otel \
   --non-interactive \
   --deployment-type container \
   --protocol MCP \
   --name my_mcp_server

# Output:
# [...]
# Config saved to: .../.bedrock_agentcore.yaml
# [...]

# If you want to view the configuration, you can run:
agentcore status

Step 4: Deploy to AWS

# Now you can launch the deployment process
agentcore deploy

# Output:
# Launching Bedrock AgentCore (codebuild mode - RECOMMENDED)
# [...]
# Setting up AWS resources (ECR repository, execution roles)
# [...]
# Deployment completed successfully

This single command orchestrates the entire deployment process.

It creates an ECR Repository to store the container image,
an IAM Role with permissions for the runtime to pull images from ECR, execute your container, and write logs to CloudWatch,
and an IAM Role for CodeBuild to build the container and push it to ECR.
Then it zips and uploads your server files to S3,
runs the build process, pushes the image,
and deploys the MCP server to AgentCore Runtime

The server is now ready to accept MCP requests.

Step 5: Test with the AWS CLI

Get the MCP server ARN:

# Extract the server's ARN from `.bedrock_agentcore.yaml`:
export MCP_SERVER_ARN=$( \
  grep 'agent_arn:' .bedrock_agentcore.yaml | \
  awk '{print $2}' | tr -d \"\')

# To see if it worked, type:
echo "MCP_SERVER_ARN=\"$MCP_SERVER_ARN\""

List the tools:

# Create a file with the list tools request
cat > list-tools-request.json <<'EOF'
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/list"
}
EOF

# To list the tools, send the request to the AgentCore Runtime
# Note that, even though this is called `invoke-agent-runtime`,
# it will call the deployed MCP server.
aws bedrock-agentcore invoke-agent-runtime \
    --agent-runtime-arn $MCP_SERVER_ARN \
    --content-type "application/json" \
    --accept "application/json, text/event-stream" \
    --no-cli-pager \
    --payload fileb://list-tools-request.json \
    ./list-tools-output.txt

# Output:
# [...]
# mcpSessionId: [MCP Session ID]
# runtimeSessionId: [AgentCore Runtime ID - same as MCP Session ID]
# [...]

# View the results:
cat list-tools-output.txt

Call the tool:

# Create a file with the tool call request
cat > tool-call-request.json <<'EOF'
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "roll_d20",
    "arguments": { 
      "number_of_dice": 2 
    }
  }
}
EOF

aws bedrock-agentcore invoke-agent-runtime \
    --agent-runtime-arn $MCP_SERVER_ARN \
    --content-type "application/json" \
    --accept "application/json, text/event-stream" \
    --no-cli-pager \
    --payload fileb://tool-call-request.json \
     ./tool-call-output.txt

# Output:
# [...]
# mcpSessionId: [MCP Session ID]
# runtimeSessionId: [AgentCore Runtime ID - same as MCP Session ID]
# [...]

# View the results:
cat tool-call-output.txt

Note: We're using the AWS CLI because curl won't work anymore. The endpoint is protected by AWS IAM and can only be called with valid credentials.

Step 6: Connect an AI Agent

Extract the information required to build the MCP server URL:

# Extract the required information from `.bedrock_agentcore.yaml`:
export RUNTIME_ID=$( \
  grep 'agent_id:' .bedrock_agentcore.yaml | \
  awk '{print $2}' | tr -d \"\')
export ACCOUNT_ID=$( \
  grep 'account:' .bedrock_agentcore.yaml | \
  awk '{print $2}' | tr -d \"\')
export REGION=$( \
  grep 'region:' .bedrock_agentcore.yaml | \
  awk '{print $2}' | tr -d \"\')

# To see if it worked, type:
echo "RUNTIME_ID=\"$RUNTIME_ID\""
echo "AWS_ACCOUNT_ID=\"$ACCOUNT_ID\""
echo "AWS_REGION=\"$REGION\""

Prepare a new Python project for the AI agent:

# Create and cd into a subdirectory for the AI agent
mkdir agent
cd agent

# Initialize a new Python project:
uv init --bare

Add the MCP Proxy for AWS (this enables IAM-based auth for MCP - quick intro to using it with other frameworks, like LangChain, Llamaindex, etc.) and the Strands Agents SDK:

uv add mcp-proxy-for-aws strands-agents

Create the agent:

# Create a simple MCP server in `agent.py`:
cat << EOF > agent.py
from strands import Agent
from strands.tools.mcp import MCPClient
from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

runtime_id = "$RUNTIME_ID"
account_id = "$ACCOUNT_ID"
region = "$REGION"

def main():
    host = f"https://bedrock-agentcore.{region}.amazonaws.com"
    path = f"runtimes/{runtime_id}/invocations"
    query_params = f"qualifier=DEFAULT&accountId={account_id}"
    url = f"{host}/{path}?{query_params}"

    mcp_client_factory = lambda: aws_iam_streamablehttp_client(
        terminate_on_close=False,
        aws_service="bedrock-agentcore",
        aws_region=region,
        endpoint=url
    )

    prompt = "Roll 3 dice"

    with MCPClient(mcp_client_factory) as mcp_client:
        mcp_tools = mcp_client.list_tools_sync()
        agent = Agent(tools=mcp_tools)

        print(f"\nUser: {prompt}")

        print("\nAgent:")
        agent(prompt)

        print()

if __name__ == "__main__":
    main()

EOF

Now run the agent:

uv run agent.py

# Output:
# User: Roll 3 dice
# 
# Agent:
# The agent will call the roll_d20 tool and display the results

Note: You may see a deprecation warning: DeprecationWarning: Use 'streamable_http_client' instead. This warning can be safely ignored. The official MCP library recently renamed their client. By the time you read this, it may already be fixed.

Cleanup

When you're done experimenting, destroy the deployment to avoid ongoing costs:

# Navigate back to the project root
cd ..

# This command removes all resources created during deployment
agentcore destroy

If you learned something new, it would be great if you could like this post. For detailed explanations of each step, see the full tutorial.

From Local MCP Server to AWS Deployment in Two Commands

Dennis Traub — Thu, 22 Jan 2026 14:26:41 +0000

This is a full tutorial with detailed explanations. For a quick walkthrough, see the code-only version.

“What's the simplest way to deploy an MCP server on AWS?”

Last week a friend asked me this, and I realized: if you already have a local MCP server, it's really just two CLI commands - agentcore configure and agentcore launch. The entire workflow - from local development to production - takes just a few minutes.

Let me show you how.

To get started, we'll prepare a small example MCP server and test it locally to make sure it works. Once that's done, we're going to directly deploy it to Bedrock AgentCore Runtime, the serverless hosting environment for Agents and MCP servers on AWS.

In just a few minutes you'll have a working, scalable, and secure MCP server on AWS, directly accessible with valid IAM credentials - no complicated OAuth setup needed.

Why AgentCore Runtime?

Before we get started, let's have a quick look at AgentCore Runtime and why it is such an obvious choice.

Many MCP servers need to maintain session state between requests while keeping the individual sessions strictly isolated. Traditional serverless options like AWS Lambda provide session isolation, but they are stateless, which means you'd have to manage sessions yourself (typically via DynamoDB or similar). Container services like ECS can maintain state, but you'd have to implement session isolation yourself or run a separate container for every single session - which can become quite costly over time.

AgentCore Runtime solves both problems: it's serverless (you pay only for processing time), but unlike Lambda, it maintains session state across multiple calls. Every session runs in a completely isolated execution environment. It's specifically designed for agent workloads and handles the infrastructure automatically.

And with that, let's get started!

Prerequisites

To follow this tutorial, you'll need:

Python 3.11 or higher
The Astral uv package manager (or pip, but if you aren't using uv yet, I really recommend switching)
An AWS account with Bedrock AgentCore access (there's a free tier)
The AWS CLI installed and configured

Step 1: Create Your MCP Server

Let's start with a simple dice-rolling server to demonstrate the deployment process. We'll use FastMCP, which provides a decorator-based API for building MCP servers quickly.

# Setup your project directory ...
mkdir my-project 

# ... and a subdirectory for the server
mkdir my-project/mcp-server

# Then navigate to the subdirectory an initialize with uv
cd my-project/mcp-server
uv init --bare
uv add mcp

The uv init --bare command creates a minimal project structure without interactive prompts. This gives us a clean pyproject.toml for dependency management.

Here's what we're building: a simple dice-rolling MCP server that demonstrates the deployment workflow.

Create a new file called server.py inside the mcp-server directory

# mcp-server/server.py
import random
from mcp.server.fastmcp import FastMCP

mcp = FastMCP(host="0.0.0.0", stateless_http=True)

@mcp.tool()
def roll_d20(number_of_dice: int = 1) -> dict:
    """Rolls one or more 20-sided dice (d20)"""

    if number_of_dice < 1:
        return {
            "error": f"number_of_dice must be at least 1, got: {number_of_dice}"
        }

    rolls = [random.randint(1, 20) for _ in range(number_of_dice)]
    total = sum(rolls)

    return {
        "number_of_dice": number_of_dice,
        "rolls": rolls,
        "total": total
    }


def main():
    mcp.run(transport="streamable-http")

if __name__ == "__main__":
    main()

What's happening here:

FastMCP initialization: The host="0.0.0.0" binds to all network interfaces, which is necessary for containerized deployments. The stateless_http=True flag is critical - it tells FastMCP to use HTTP-based transport instead of maintaining persistent connections.

Tool registration: The @mcp.tool() decorator automatically registers your function as an MCP tool. The function's docstring becomes the tool description, and type hints define the input schema. MCP clients will discover this tool and can invoke it with structured arguments.

Transport: mcp.run(transport="streamable-http") starts the server using the streamable HTTP transport. This is the standard MCP transport for HTTP-based deployments and is compatible with AgentCore Runtime.

Step 2: Test Locally

Before deploying, let's verify the server works. Testing locally helps catch issues early and ensures your server logic is correct before dealing with deployment complexities.

Run the MCP server

uv run server.py

You should see:

INFO:     Started server process [55952]
INFO:     Waiting for application startup.
StreamableHTTP session manager started
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

FastMCP uses Uvicorn under the hood, which is why you see Uvicorn logs. The server is now listening on port 8000 and ready to accept MCP requests.

List the available tools

In another terminal, test the server using the MCP protocol. MCP uses JSON-RPC 2.0 over HTTP, so we can test it without an MCP client by sending JSON-RPC requests directly using curl.

The tools/list method is a standard MCP method that returns all available tools. The heredoc syntax (<< 'EOF') lets us inline the JSON payload without creating separate files:

curl -X POST http://127.0.0.1:8000/mcp \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d @- << 'EOF'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
EOF

You should see the roll_d20 tool in the response with its description and input schema.

Send a tool call request

Now let's call the tool. The tools/call method invokes a specific tool with the provided arguments:

curl -X POST http://127.0.0.1:8000/mcp \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d @- << 'EOF'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "roll_d20",
    "arguments": {
      "number_of_dice": 2
    }
  }
}
EOF

The response will contain the tool's return value - in this case, the dice rolls and total.

Stop the local server with CTRL+C when done. This local testing confirms your server works correctly before we package it for deployment.

Step 3: Configure for AgentCore Runtime

The Bedrock AgentCore Starter Toolkit handles the deployment configuration. It generates Dockerfiles, IAM roles, and all the infrastructure code needed to deploy your server. Install it in your project's root directory:

# Navigate to the project root
cd ..

# Initialize a new Python project
uv init --bare
uv add bedrock-agentcore-starter-toolkit

We're creating a new project at the project root because the toolkit needs to manage the deployment configuration separately from the MCP server. This separation keeps the MCP server code clean and makes it easier to manage multiple deployments.

Configure your agent:

uv run agentcore configure \
   --entrypoint mcp-server/server.py \
   --requirements-file mcp-server/pyproject.toml \
   --disable-memory --disable-otel \
   --non-interactive \
   --deployment-type container \
   --protocol MCP \
   --name my_mcp_server

Let's understand each parameter:

--entrypoint points to your server's main file. AgentCore runs this inside the container.
--requirements-file tells the toolkit where to find dependencies.
--disable-memory --disable-otel disables optional features. Memory persists state across sessions (not needed for MCP servers). OTEL enables observability. We're disabling both to keep this simple.
--non-interactive skips interactive CLI prompts and uses defaults.
--deployment-type container packages your server as a container image using CodeBuild - no local Docker required.
--protocol MCP tells AgentCore this is an MCP server.
--name sets the MCP server name.

Note: In some cases, you may see warnings about container engines or platform mismatches. These are safe to ignore - when using --deployment-type container, AgentCore will use CodeBuild for cloud-based builds. CodeBuild can run on ARM64 (the architecture AgentCore Runtime uses), so even if your local machine is x86_64, the cloud build will work correctly.

The configuration creates:

.bedrock_agentcore.yaml - The main configuration file that stores all deployment settings. Be very careful when editing this directly.
.bedrock_agentcore/my_mcp_server/Dockerfile - The container definition that packages your server. The toolkit generates this based on your entrypoint and dependencies.
mcp-server/.dockerignore - Build exclusions to keep the container image small.

Step 4: Deploy to AgentCore Runtime

Now let's deploy the server to AWS:

uv run agentcore launch --agent my_mcp_server

This single command orchestrates the entire deployment process.

Here's what happens under the hood:

1: ECR Repository Creation - Amazon Elastic Container Registry (ECR) stores your container images. The toolkit automatically creates a new repository.

2: IAM Role Setup - The toolkit creates two IAM roles:

Execution Role - Grants permissions for the runtime to pull images from ECR, execute your container, and write logs to CloudWatch.
CodeBuild Role - Allows CodeBuild to build your container and push it to ECR.

3: Container Build - CodeBuild builds your container in the cloud. This is why you don't need Docker locally - CodeBuild handles the build process.

The build:

Uses the generated Dockerfile
Installs dependencies from your pyproject.toml
Packages your server code
Creates an ARM64 image (AgentCore Runtime's architecture)
Pushes the image to your ECR repository

4: Runtime Deployment - AgentCore Runtime creates a new runtime instance using your container image.

The runtime is now ready to accept MCP requests.

The build takes about 25-30 seconds. When complete, you'll see:

╭────────────────────────────── Deployment Success ───────────────────────────────╮
│ Agent Details:                                                                  │
│ Agent Name: my_mcp_server                                                       │
│ Agent ARN: arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:runtime/RUNTIME_ID       │
│ ...                                                                             │
╰─────────────────────────────────────────────────────────────────────────────────╯

Important:

Note down the the following information - you'll need it to connect to your server:

Agent ARN - The Full ARN of your deployed server. This uniquely identifies your runtime across all AWS accounts and regions.

Then extract the following information from the ARN:

AWS Region - Directly after arn:aws:bedrock-agentcore:, e.g. us-west-2.
AWS Account ID - A 12-digit number, right next to the region. Region and account ID are required for IAM-based authentication when connecting clients.
Runtime ID - The last part of the ARN, directly following runtime/, e.g., my_mcp_server-abcde12345.

The ARN format is: arn:aws:bedrock-agentcore:{region}:{account-id}:runtime/{runtime-id}

Step 5: Test the Deployed Server

Test your deployed server using the AWS CLI. The invoke-agent-runtime command sends requests to your deployed server, similar to how we tested locally with curl.

We'll use process substitution (<(...)) to inline the JSON payloads without creating separate files:

# Set your server ARN
export SERVER_ARN="arn:aws:bedrock-agentcore:REGION:ACCOUNT:runtime/RUNTIME_ID"

# List available tools
aws bedrock-agentcore invoke-agent-runtime \
    --agent-runtime-arn $SERVER_ARN \
    --content-type "application/json" \
    --accept "application/json, text/event-stream" \
    --payload fileb://<(cat <<'EOF'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
EOF
) list-tools.txt

# Call the tool
aws bedrock-agentcore invoke-agent-runtime \
    --agent-runtime-arn $SERVER_ARN \
    --content-type "application/json" \
    --accept "application/json, text/event-stream" \
    --payload fileb://<(cat <<'EOF'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "roll_d20",
    "arguments": {
      "number_of_dice": 2
    }
  }
}
EOF
) call-tool.txt

What you'll see: The AWS CLI opens a pager showing HTTP response metadata (status codes, headers, including the MCP session ID). Press q to exit. The actual JSON-RPC response is written to the output files - check list-tools.txt for the tool list and call-tool.txt for the dice roll results.

Notice that the requests are identical to your local tests - the MCP request is the same whether running locally or on AgentCore Runtime. The only difference is the endpoint and authentication method.

Step 6: Connect an Agent (Optional)

Now we can connect an AI agent to the deployed server using the official IAM MCP client, which handles MCP request creation and IAM authentication automatically. This demonstrates how real-world agents would connect to your server.

We're going to use the Strands Agents SDK as an example framework, but this pattern works with any agent framework that supports MCP. Check out this post, where I show you how to use the IAM MCP client with LangChain, LlamaIndex, and Microsoft's Agent Framework.

While still in the project root, add the following packages:

uv add mcp-proxy-for-aws strands-agents

The mcp-proxy-for-aws is an official AWS wrapper around the standard MCP client. The standard client expects OAuth, but this one signs requests with AWS credentials using SigV4, making it compatible with IAM authentication on AWS. The strands-agents package provides the agent framework we'll use for this example.

Create test_agent.py and add the runtime ID, AWS account ID, and region:

# Using Strands Agents SDK for this example
from strands import Agent
from strands.tools.mcp import MCPClient
from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

# Set your MCP server details from Step 4
RUNTIME_ID = "[YOUR RUNTIME ID]"
ACCOUNT_ID = "[YOUR ACCOUNT ID]"
REGION = "[YOUR AWS REGION]"

def main():
    # Build the MCP server URL
    url = f"https://bedrock-agentcore.{REGION}.amazonaws.com/runtimes/{RUNTIME_ID}/invocations?qualifier=DEFAULT&accountId={ACCOUNT_ID}"

    print(f"\nInitializing MCP client with IAM-based auth for:\n{url}")

    mcp_client_factory = lambda: aws_iam_streamablehttp_client(
        aws_service="bedrock-agentcore",
        aws_region=REGION,
        endpoint=url,
        terminate_on_close=False
    )

    with MCPClient(mcp_client_factory) as mcp_client:
        mcp_tools = mcp_client.list_tools_sync()
        agent = Agent(tools=mcp_tools)

        query_1 = "What tools do you have available?"
        print(f"\nQ: {query_1}")
        agent(query_1)

        query_2 = "Roll three dice"
        print(f"\nQ: {query_2}")
        agent(query_2)

if __name__ == "__main__":
    main()

Let's understand the key parts:

Endpoint URL construction: The URL follows AgentCore's invocation endpoint pattern. The qualifier=DEFAULT parameter specifies which endpoint version to use (AgentCore supports multiple versions for gradual rollouts).

Client factory pattern: The Strands Agents SDK's MCPClient expects a factory function (a lambda that returns a client). This allows the framework to manage connection lifecycle - creating new connections when needed and cleaning them up properly.

The aws_iam_streamablehttp_client function creates an MCP client that automatically signs all requests with your AWS credentials as well as the region and AWS service the server is hosted in.

Tool discovery: mcp_client.list_tools_sync() fetches all available tools from your server. The agent then receives these tools and can invoke them based on user queries. When the agent sees "Roll three dice," it recognizes this matches the roll_d20 tool and calls it with number_of_dice=3.

Session management: The terminate_on_close=False parameter tells the client not to explicitly terminate the MCP session when closing. AgentCore Runtime manages session lifecycle automatically, so this isn't necessary.

Run it:

uv run test_agent.py

Note: You may see a deprecation warning: DeprecationWarning: Use 'streamable_http_client' instead. The official MCP client library recently renamed their HTTP client, and the IAM client is being updated to match. This warning can be safely ignored. By the time you read this, it may already be fixed.

The agent will connect using your AWS credentials and use the deployed MCP server's tools.

This demonstrates the complete flow: your server is deployed, accessible via IAM, and integrated with an AI agent framework.

The same pattern works with other frameworks like LangChain or LlamaIndex - just swap the agent framework while keeping the IAM MCP client.

Step 7: Cleanup

When you're done experimenting, destroy the deployment to avoid ongoing costs:

uv run agentcore destroy --agent my_mcp_server

This command removes all resources created during deployment:

AgentCore runtime - The running MCP server instance
ECR repository and images - Container images stored in ECR
CodeBuild project - The build configuration (builds are ephemeral, but the project definition persists)
IAM roles - Both the execution role and CodeBuild role
S3 artifacts - Build artifacts stored in S3 buckets created by CodeBuild

The toolkit is careful about cleanup - it won't delete resources that were created outside the toolkit. You'll be prompted to confirm before deletion, as this operation is irreversible.

What We've Learned

This tutorial covered the complete deployment workflow:

Local Development - Build and test MCP servers locally using FastMCP. Testing locally helps catch issues before deployment.
Configuration - The AgentCore Starter Toolkit generates all infrastructure code (Dockerfiles, IAM roles, etc.) from the configuration. This abstraction lets you focus on your server logic rather than deployment details.
Cloud Deployment - AgentCore Runtime uses CodeBuild for container builds, so you don't need Docker locally. The runtime automatically manages state, session isolation, and infrastructure - you just provide the container image.
Testing - The AWS CLI's invoke-agent-runtime command lets you test deployed servers using the same MCP protocol as local testing. IAM authentication happens automatically via your AWS credentials.
Integration - The IAM MCP client enables any agent framework to connect to AgentCore-hosted MCP servers using AWS credentials, eliminating the need for OAuth infrastructure.

Next Steps

Integrate with other frameworks - Check out No OAuth Required: An MCP Client For AWS IAM to learn how to connect LangChain, LlamaIndex, or other agent frameworks
Deploy via AgentCore Gateway - Use Bedrock AgentCore Gateway to turn existing APIs into MCP servers
Explore more complex MCP servers - Add multiple tools, resources, and prompts to your server

Key takeaway: Bedrock AgentCore Runtime provides serverless execution with stateful sessions. You pay only for processing time, even though your server maintains its state between requests. This session-based model makes it the perfect for agentic workloads, including MCP.

If you learned something new, it would be great if you could like this post. For a quick walkthrough without much explanation, see the code-only version.

Yay, I've been featured on the top 7 for the very first time! Thanks DEV ❤️

Dennis Traub — Tue, 25 Nov 2025 20:08:54 +0000

Jess Lee for The DEV Team

Nov 25 '25

No OAuth Required: An MCP Client For AWS IAM

Dennis Traub — Tue, 18 Nov 2025 19:17:50 +0000

When Anthropic published the Model Context Protocol (MCP), I immediately started experimenting with deployment options on AWS:

First, I tried running MCP servers as AWS Lambda functions. A great solution in terms of simplicity and cost, but it also meant I had to manually manage session state across invocations.

Next, I deployed them as containers on Amazon ECS, which immediately solved session state management for me, but I had to pay for a running server, even when it sat idle.

Then Amazon Bedrock AgentCore was released, which turned out to be exactly the solution I was looking for: A serverless runtime, automatically handling session state, while only charging for the actual processing time of MCP requests - the best of both worlds. And, as a native AWS service, it supports IAM, which perfectly fits into my existing stack.

But when I tried to actually connect an agent to a server, I ran into a wall:

No matter which agent framework I used, they all expected OAuth. This meant setting up a separate Cognito stack just to connect an agent to its tools. But I'd like to use IAM credentials like I do for everything else on AWS.

This is why I built the MCP client for IAM, a drop-in replacement that can be used with any Python framework using the official MCP SDK's streamablehttp_client.

No Cognito setup, no token management, no custom signing code. This client automatically signs MCP requests with your agent's existing AWS credentials.

In this post, I'll show you how to use it with popular AI agent frameworks like LangChain, Strands Agents, LlamaIndex, and Microsoft's Agent Framework.

What You Need to Get Started

The MCP client for IAM is open source and part of the official MCP Proxy for AWS. You can find it on GitHub and PyPI.

If you already have an MCP server with IAM auth on AWS, all you need is to install the package in your client:

pip install mcp-proxy-for-aws

That's it. Now you can replace MCP's default streamablehttp_client with the following import:

from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

If you don't have an MCP server on AWS yet, check out this quick tutorial: From Local MCP Server to AWS Deployment in Two Commands

Integration Patterns

Different frameworks manage MCP connections differently. The client supports two integration patterns to work with the following approaches:

Pattern 1: Client Factory Integration

Use with: Frameworks that accept a factory function returning an MCP client, like the Strands Agents SDK and Microsoft's Agent Framework. The aws_iam_streamablehttp_client is passed as a factory to the framework, which then handles the connection lifecycle internally.

Example - Strands Agents:

from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

mcp_client_factory = lambda: aws_iam_streamablehttp_client(
    endpoint=mcp_url,    # The URL of the MCP server
    aws_region=region,   # The region of the MCP server
    aws_service=service  # The underlying AWS service, e.g. "bedrock-agentcore"
)

with MCPClient(mcp_client_factory) as mcp_client:
    mcp_tools = mcp_client.list_tools_sync()
    agent = Agent(tools=mcp_tools, ...)

Example - Microsoft's Agent Framework:

from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

mcp_client_factory = lambda: aws_iam_streamablehttp_client(
    endpoint=mcp_url,    # The URL of the MCP server
    aws_region=region,   # The region of the MCP server
    aws_service=service  # The underlying AWS service, e.g. "bedrock-agentcore"
)

mcp_tools = MCPStreamableHTTPTool(name="MCP Tools", url=mcp_url)
mcp_tools.get_mcp_client = mcp_client_factory

async with mcp_tools:
    agent = ChatAgent(tools=[mcp_tools], ...)

Pattern 2: Direct MCP Session Integration

Use with: Frameworks that require direct access to the MCP sessions, like LangChain and LlamaIndex. The aws_iam_streamablehttp_client provides the authenticated transport streams, which are then used to create an MCP ClientSession.

Example - LangChain:

from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

mcp_client = aws_iam_streamablehttp_client(
    endpoint=mcp_url,    # The URL of the MCP server
    aws_region=region,   # The region of the MCP server
    aws_service=service  # The underlying AWS service, e.g. "bedrock-agentcore"
)

async with mcp_client as (read, write, session_id_callback):
    async with ClientSession(read, write) as session:
        mcp_tools = await load_mcp_tools(session)
        agent = create_langchain_agent(tools=mcp_tools, ...)

Example - LlamaIndex:

from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

mcp_client = aws_iam_streamablehttp_client(
    endpoint=mcp_url,    # The URL of the MCP server
    aws_region=region,   # The region of the MCP server
    aws_service=service  # The underlying AWS service, e.g. "bedrock-agentcore"
)

async with mcp_client as (read, write, session_id_callback):
    async with ClientSession(read, write) as session:
        mcp_tools = await McpToolSpec(client=session).to_tool_list_async()
        agent = ReActAgent(tools=mcp_tools, ...)

Running Examples

Explore complete working examples for different frameworks in the GitHub repository.

Benefits of Using this Client

Simple local development:
Use your AWS CLI credentials directly. No Cognito setup, no token management, no separate auth infrastructure.

Standard AWS patterns:
Cross-account access via IAM role assumption works the same way it does for every other AWS service.

IAM-based access control:
Control which agents can connect to which MCP servers using IAM policies. No changes to server code required.

Universal compatibility across AWS:
The MCP client for IAM works with AgentCore Gateway, AgentCore Runtime, and any other AWS service exposing MCP over HTTPS with IAM authentication.

Next Steps

Check out this simple way to deploy your own MCP server on AWS
Have a look at the complete examples on GitHub for working code with a selection of frameworks.

Further resources:

The package on PyPI - Installation and changelog
The source on GitHub - Contribute or report issues

What MCP servers are you planning to build? I'd love to hear about your use cases in the comments!

DEV Community: Dennis Traub

8 Agents Wrote Perfect Components - And Nothing Worked

The architecture

The bugs

Bug 1: The Spring Boot app won't even start

Bug 2: Every call returns 404

Bug 3: Missing request fields

Bug 4: User lookup doesn't work

Bug 5: Every status lookup returns "not found"

Bugs 6 to 17: SSM parameter path mismatches

Why parallel agents can't catch this

How I found all of them at once

How to prevent seam bugs

FAQ

What are seam bugs in AI-generated code?

Why does parallel AI code generation produce integration bugs?

How do you catch integration bugs from parallel AI agents?

My 8 Agents Wrote Perfect Components - And Nothing Worked

The architecture

The bugs

Bug 1: The Spring Boot app won't even start

Bug 2: Every call returns 404

Bug 3: Missing request fields

Bug 4: User lookup doesn't work

Bug 5: Every status lookup returns "not found"

Bugs 6 to 17: SSM parameter path mismatches

Why parallel agents can't catch this

How I found all of them at once

How to prevent seam bugs

FAQ

What are seam bugs in AI-generated code?

Why does parallel AI code generation produce integration bugs?

How do you catch integration bugs from parallel AI agents?

Missing from the MCP debate: Who holds the keys when 50 agents access 50 APIs?

Fifty agents, fifty sets of keys

What happened to SSO?

Remote MCP servers are identity boundaries

3 Things I Wish I Knew Before Setting Up a UV Workspace

1. Give the Root a Distinct Name

2. Use workspace = true for Inter-Package Deps

3. Use importlib Mode for pytest

References

How to Use Strands Agents' Built-In Session Persistence

The Code

What Gets Persisted

Built-In Backends

Tips and Notes

Troubleshooting tips

Good to know

References

[Boost]

From Zero to Agentic Coding: Running Claude Code with Amazon Bedrock

Gunnar Grosch for AWS ・ Feb 15

Why Your Chatbot is the BlackBerry of the 2020s

How a subtle MCP server bug almost cost me $230 a month

Three Calls, Zero Updates

Tracking It Down

Let's Look at the Math

What You can Do

From Local MCP Server to AWS Deployment in Two Commands - The Code-Only Version

Prerequisites

Step 1: Create a small MCP server

Step 2: Test Locally

Step 3: Configure the deployment AWS

Step 4: Deploy to AWS

Step 5: Test with the AWS CLI

Step 6: Connect an AI Agent

Cleanup

From Local MCP Server to AWS Deployment in Two Commands

Why AgentCore Runtime?

Prerequisites

Step 1: Create Your MCP Server

Step 2: Test Locally

Run the MCP server

List the available tools

Send a tool call request

Step 3: Configure for AgentCore Runtime

Step 4: Deploy to AgentCore Runtime

Step 5: Test the Deployed Server

Step 6: Connect an Agent (Optional)

2. Use `workspace = true` for Inter-Package Deps

3. Use `importlib` Mode for pytest