Build interactive MCP Apps using Amazon Bedrock AgentCore

As customers shift to interacting with digital services through AI hosts like ChatGPT and Claude, organizations need a way to make their services accessible across these applications with rich UI, not only plain text. They also need to do this without coupling to a single host. MCP Apps and Amazon Bedrock AgentCore provide exactly that. MCP Apps extends the Model Context Protocol (MCP) with interactive HTML widgets rendered directly inside AI hosts. Amazon Bedrock AgentCore is a platform to build, connect, and optimize agents at scale, with any framework or model. For MCP Apps specifically, AgentCore runtime, a capability of Amazon Bedrock AgentCore, provides a secure, serverless, session-isolated host with native MCP support. AgentCore Gateway, a capability of Amazon Bedrock AgentCore, exposes it through a single secure endpoint that MCP Apps-compatible hosts can reach. AgentCore takes care of this undifferentiated heavy lifting, so you can focus on your business logic and widget design.

In this post, we demonstrate how to build and deploy an MCP App with interactive HTML widgets on Amazon Bedrock AgentCore. Because MCP Apps is a host-agnostic standard, the app delivers the same rich experience across AI hosts that support the Apps extension. With the sample application, Unicorn Rentals, customers can browse available unicorns, book rentals, view active bookings, and return unicorns. Whether a customer opens Unicorn Rentals in ChatGPT, Claude, or another supported host, it looks and feels the same.

Here’s how it works

Before we get into the architecture, let’s see the app in action. Unicorn Rentals is deployed as an MCP App and connected to an AI host. The following examples use ChatGPT, but the same server works in Claude or other hosts that support the MCP Apps extension. We will walk through four steps, from browsing the fleet to returning a unicorn. Let’s get started.

Step 1: List the available unicorns

We start with a natural language question: “Can you show all unicorns?” The host interprets the question and renders an interactive card for each unicorn showing its image, name, description, hourly rate, and availability, rather than a plain text list.

Figure 1: The AI host renders the available unicorns as interactive cards.

Step 2: Book a unicorn

If your favorite unicorn is Stardust, you can rent it by saying “I would like to book Stardust unicorn”. The app records the booking and confirms it straight away, showing the booking ID, date, hourly rate, and the unicorn you booked.

Figure 2: The booking is confirmed and the details are shown in the chat.

Step 3: View your booking

To check what you currently have out, you can say “Show me my unicorn bookings”. The app returns your active rental along with the duration and cost incurred so far. This time the response comes back as text rather than a card, because not every request needs a rich interface.

Figure 3: The active rental is returned as text rather than a card.

Step 4: Return the unicorn

Finally, “I would like to return my unicorn” ends the rental. The app calculates the total cost from the duration and the hourly rate and reports it back in the conversation.

Figure 4: The rental ends and the total cost is reported.

Everything you just saw is served by a single MCP server running on Amazon Bedrock AgentCore runtime, fronted by an AgentCore Gateway. The rest of this post shows how it is built and how to deploy it yourself.

Solution overview

This solution deploys an MCP App on Amazon Bedrock AgentCore that exposes business logic and interactive HTML widgets through Model Context Protocol. Users interact with AI hosts which render interactive HTML widgets using the MCP Apps pattern. A dedicated AWS Lambda function implements the business logic with Amazon DynamoDB for persistence.

The following diagram shows how these components work together to serve interactive widgets to AI hosts.

Figure 5: Architecture of the MCP App on Amazon Bedrock AgentCore

Here’s what happens when you register an MCP App with an AI host:

1. You provide the App details including MCP Server URL.
2. The AI host makes tools/list and resources/list MCP calls to the MCP Server URL exposed by the AgentCore Gateway. The MCP server provides tools such as list_unicorns, book_unicorn, view_bookings, and return_unicorn, along with resources such as unicorn-list and booking-confirmation that supply the widget HTML for each response.
3. AWS WAF validates the request through its IP allowlist and managed rules, and the AgentCore Gateway routes it to the AgentCore runtime.
4. The AgentCore Gateway invokes the AgentCore runtime using its AWS Identity and Access Management (IAM) execution role. The MCP App hosted on it defines MCP tools and MCP resources.
5. The MCP App receives the request and responds with the list of tools or resources in it.
6. The AI host might cache that information for future use.

Here’s what happens when a user tries to access unicorn rental service from an AI host.

Phase 1 — Tool calls

1. The user makes a natural language request (for example, “Show me all unicorns”) from an AI host like ChatGPT or Claude.
2. The AI host translates the request into an MCP tools/call message (for example, list_unicorns) and sends it to the AgentCore Gateway endpoint.
3. AWS WAF screens the request before it reaches the AgentCore Gateway endpoint.
4. The AgentCore Gateway invokes the AgentCore runtime, which hosts the MCP App.
5. The MCP App receives the request and delegates business operations to the Unicorn Rental Service AWS Lambda.
6. The AWS Lambda executes the business logic against DynamoDB and returns the result.
7. The MCP App wraps the response in MCP format and returns it to the AI host.

Phase 2 — Widget rendering

1. If the tool has an associated resource URI (for example, ui://widget/unicorn-list), the AI host initiates this phase. Tools without an associated widget, such as view_bookings and return_unicorn, return text-only content and skip this phase entirely.
2. The host sends an MCP resources/read request for that URI.
3. The request reaches the MCP App through the AgentCore Gateway.
4. The MCP App resolves the resource URI and returns the self-contained HTML of the widget. The AI host might cache this data for better performance.
5. The host renders the HTML in a sandboxed iframe, injecting the structured data from the tool response through the MCP Apps lifecycle.
6. The widget fetches the images needed from Amazon CloudFront, which uses Amazon Simple Storage Service (Amazon S3) as the origin.

Build the MCP server using AgentCore runtime

This section covers how the MCP server is structured and how AgentCore runtime hosts it.

MCP App

The MCP App in this solution is a TypeScript application built on the official @modelcontextprotocol/sdk with the @modelcontextprotocol/ext-apps extension that provides a standard way to deliver interactive widgets from MCP servers. It runs as an Express.js HTTP server that AgentCore runtime manages internally. The MCP App provides the following capabilities:

MCP tools

The app registers the MCP tools like list_unicorns, book_unicorn, view_bookings, and return_unicorn that AI hosts can invoke. Tools are registered using registerAppTool by providing the tool name, tool config, and a handler function that contains the business logic of the tool. The app registers the list_unicorns tool. This handles the tools/list MCP requests for tools discovery and tools/call MCP requests for tool invocation from AI hosts.

The _meta.ui.resourceUri field in the tool config tells the AI host which widget to render for showing the tool’s response. The structuredContent in the tool/call response contains the data payload. AI hosts inject this data into the widgets while rendering them.

MCP App resources

The app registers widgets as MCP Resources that AI hosts can use. Resources are registered using registerAppResource, by providing the resource name, URI and a handler function that returns the HTML data of the widget. The app registers the unicorn-list-widget resource. This handles the resource/list MCP requests for resource discovery and resource/read MCP requests for getting widget HTML from AI hosts.

MCP App on AgentCore runtime

The solution deploys the MCP App on AgentCore runtime. The build process packages the MCP App code into a zip file. The deploy step uploads it to an Amazon S3 bucket and creates an AgentCore runtime resource that references it. The runtime configuration specifies the NODE_22 environment, the entry point, and the MCP protocol mode.

AgentCore runtime provides a secure, serverless, and purpose-built hosting environment for deploying and running the MCP App. It automatically scales based on incoming request volume. The MCP protocol configuration tells AgentCore this is an MCP server, which activates protocol-specific optimizations. Resource-based policies restrict which principals can invoke the runtime. In this solution, the policy allows only the AgentCore Gateway execution role and denies other principals.

Expose the MCP server through AgentCore Gateway

AgentCore runtime supports IAM (SigV4) and OAuth authentication for invocation. This solution places an Amazon Bedrock AgentCore Gateway in front of the runtime, so external AI hosts can reach the MCP server through a single managed endpoint. The Gateway accepts inbound requests with No Auth and invokes the runtime using its own IAM execution role over SigV4, so callers do not handle AWS credentials themselves. AWS WAF protects the AgentCore Gateway endpoint with IP allowlisting, managed threat-detection rules, and rate limiting.

Business logic layer

An AWS Lambda function implements the business logic of the unicorn rentals. It handles inventory queries and booking operations against Amazon DynamoDB. It knows nothing about MCP. In a real-world implementation, this could be your existing services running on Amazon Elastic Container Service (Amazon ECS), Amazon Elastic Kubernetes Service (Amazon EKS), or other compute services. The key point is that the MCP server acts as a thin protocol adapter. Your core business logic stays where it already lives and you connect it to the MCP layer through standard invocation patterns like HTTP calls or SDK clients.

Deployment walkthrough

The following section walks you through how to deploy the solution.

Prerequisites

Before you begin, verify that you have:

• An AWS account with appropriate permissions to deploy AgentCore runtime. For required IAM permissions, see IAM Permissions for AgentCore runtime.
• Node.js 22+.
• AWS Command Line Interface (AWS CLI) V2.0 or higher, installed and configured (aws configure).
• AWS Cloud Development Kit (AWS CDK) CLI installed globally. For instructions, see Getting started with the AWS CDK.

Deploy the solution

The deployment uses a single deploy.sh script that orchestrates building and CDK stack deployment.

Step 1: Download the solution code:

git clone https://github.com/aws-samples/sample-agentcore-mcp-apps.git
cd sample-agentcore-mcp-apps

Step 2: Deploy the required resources on your AWS account. Run the deployment script to deploy the CDK stacks:

bash deploy.sh

Note the outputs printed after deployment. You will need the GatewayResourceUrl to connect an AI host.

Connect from AI hosts

Because this MCP server implements the MCP Apps open standard, other AI hosts that support the MCP Apps extension can connect and render the full interactive widget experience.

The repository includes detailed setup guides for connecting specific AI hosts:

ChatGPT

1. Go to https://chatgpt.com/, choose User Profile, Plugins, Developer Mode, and turn on Developer mode.
2. Go to Plugins and choose New Plugin.
3. For Name, enter UnicornRentals.
4. For Description, enter: “Browse unicorns, book rentals, view active bookings, and return unicorns. Shows rich UI cards with pricing and booking confirmations”.
5. For Connection, enter the value of GatewayResourceUrl from the CDK outputs.
6. For Authentication, choose No Auth.
7. Choose Create.

Claude.ai

1. Go to https://claude.ai, choose Customize, then Connectors.
2. Choose Add Connector.
3. For Name, enter UnicornRentals.
4. For Remote MCP server URL, enter the value of GatewayResourceUrl from the CDK outputs.
5. Choose Save.

Production deployment considerations

When moving this solution to production, consider the following.

For monitoring and observability, use Amazon CloudWatch to monitor your AgentCore Gateway request metrics, Unicorn Service Lambda invocations, and AgentCore runtime container health. Set up alarms for error rates and latency thresholds, and turn on logging to track MCP method calls and response times.

For cost optimization, note that AgentCore runtime uses consumption-based pricing based on container runtime and invocations. To keep costs in check, right-size your container memory and CPU allocation, and review Lambda concurrency settings based on expected traffic patterns.

For responsible AI, add safety controls at your trust boundaries. Validate tool arguments with strict schemas in the MCP server and re-validate them in the Unicorn Service Lambda so business logic doesn’t trust unvalidated input. For unstructured text that crosses the boundary, use Amazon Bedrock Guardrails to filter harmful content, block denied topics, and redact sensitive data like personally identifiable information (PII) from responses before they reach the client.

Cleanup

To delete all the resources created by the CDK stack, run the following commands.

cd infrastructure/cdk
npx cdk destroy

Next steps

To view the source code and deployment instructions for this example solution, visit the GitHub repository in aws-samples. You can adapt the pattern by replacing the Unicorn Rental Service Lambda with your own business logic and adding new tools and widgets.

Conclusion

This post showed you how to build and deploy an MCP server with interactive widget UI on Amazon Bedrock AgentCore runtime. The architecture pattern is a thin MCP protocol layer on AgentCore runtime that delegates business logic to dedicated Lambda functions and serves self-contained widget HTML as MCP App resources. It exposes the stack through an AgentCore Gateway endpoint and gives you a scalable MCP Apps deployment with minimal operational overhead.

What makes this approach powerful is what you don’t need to build. AgentCore runtime handles the undifferentiated heavy lifting of scaling, session isolation, health monitoring, and infrastructure management, so your team stays focused on the business logic and widget experiences that matter to your customers. You write a thin protocol adapter, point it at your existing services, and AgentCore takes care of the rest.

Because the solution is built on the open MCP Apps standard, your investment isn’t locked to a single AI host. The same server, the same tools, and the same interactive widgets work across other hosts that support the MCP Apps extension. You build once and reach customers wherever they choose to interact with AI. And because the architecture cleanly separates protocol handling from business logic, you can evolve independently. Swap your data store, add new tools, redesign your widgets, or connect additional backend services. None of these changes require rearchitecting the deployment. The MCP layer stays thin, your services stay portable, and AgentCore runtime keeps everything running.

About the authors

​