Forem: Ashita Prasad

How I built MCP Apps based Sales Analytics Agentic UI & deployed it on Amazon Bedrock AgentCore

Ashita Prasad — Wed, 01 Apr 2026 05:38:59 +0000

TL;DR: Learn how to add interactive forms, charts, visualization & PDF viewer - natively in your AI Agent chat window using MCP Apps.

AI Agents are getting smarter with each passing day. But, their interfaces? Not so much. But, what if there is a way to turn the AI chat from a place where you converse into a place where you can actually work?

That's where MCP Apps, an extension of Model Context Protocol, comes to our rescue.

In my previous article, we explored the foundational building blocks of MCP Apps in detail and witnessed how it provides a way to deliver rich, bidirectional UIs. Through a series of minimal examples, we covered various concepts such as the handshake protocol and host-aware theming, to CSP policies and calling tools from within an iframe.

Now, it's time to stitch those pieces together into something real.

In this article, we'll walk through a complete, production-style MCP Apps chatflow (chat + workflow) and build an interactive sales analytics UI where a user can select sales region, pick a metric like revenue or conversion rate, fetch live data, visualize it with charts, and create & download a PDF report - all without ever leaving the AI Agent chat window. We will also learn how to deploy the developed TypeScript MCP server powering our sales analytics MCP Apps on Amazon Bedrock AgentCore Runtime.

You can find the entire source code of this article in the Github repo link provided below 👇

ashitaprasad / sample-mcp-apps-chatflow

Sample MCP Apps Chatflow

Sample MCP server that renders interactive sales analytics UIs inside an MCP Apps-compatible chat client. It includes a sales metric selector, chart-based visualization, and PDF report generation.

Articles

This project is part of the MCP Apps article series published on dev.to:

Part 1: How I render interactive UI in my AI Agent chatflows using MCP Apps - Covers the core architectural patterns for declaring UI resources, practical design principles, and how to handle sandboxed host–server communication.
Part 2: How I built MCP Apps based Sales Analytics Agentic UI & deployed it on Amazon Bedrock AgentCore - Walks through a complete, production-style MCP Apps chatflow (chat + workflow) and build an interactive sales analytics UI where a user can select sales region, pick a metric like revenue or conversion rate, fetch live data, visualize it with charts, and create & download a PDF report - all without…

View on GitHub

The Problem: When chat isn't enough!

It all started when my friend, who is a sales analyst, started exploring AI Agents after reading everywhere that agents can unlock productivity by automating workflows and are also capable of performing data analysis.

He prepared sales analytics reports on a monthly and quarterly basis and felt AI Agents could accelerate this workflow greatly. He started his Agentic journey by uploading CSVs, interacting with the AI Agent & assigning it tasks. The agent would frequently ask him clarifying questions, like the required sales metrics, sales regions he was interested in and more follow-up questions. Often, the AI agent would assume certain parameters and produce random results which meant he had to start the entire workflow all over again.

Although the resulting analysis was accurate, but from the presentation standpoint a simple markdown result was quite underwhelming. After discussing his entire Agentic Experience (AX), I realised that the core friction was due to the limitations of plain chat. While my friend kept answering and re-prompting, the model kept guessing and re-analyzing. The experience never quite graduated from "assistant response" to an actual "working interface".

And, MCP Apps solved exactly this gap!

Instead of returning only text, the server returns a rich, interactive HTML interface rendered directly inside the chat which lets the user drive the experience like an application, not just an answer.

Let's see how.

The Solution: A Chatflow powered by MCP Apps

An end-to-end demo of the complete chatflow is shown below:

Our chatflow involves three MCP Apps (UI resources) orchestrated by four tools. Each MCP App is a self-contained HTML page served by the MCP server, running in a sandboxed iframe, communicating with the host via postMessage JSON-RPC.

The new Agentic experience (AX) unfolds like a real workflow:

User asks for sales insights.
AI agent opens a Sales Metric Selector MCP App which allows user to easily select the sales metric, reporting period, reporting year & sales regions, instead of forcing the user to specify everything in text.
On clicking Submit, the app fetches data through an internal MCP tool and adds it as a structured JSON data in the context.
With the relevant data added in context, user can prompt to generate a visualization or prepare a PDF report.
Upon requesting for a visualization, the Sales Visualization MCP App is rendered which presents the entire data in an insightful & interactive visualization dashboard.
Upon requesting for a PDF report, the AI agent triggers a tool which creates a PDF report server side, and then displays it via a PDF Report Viewer MCP App. The MCP app displays the pdf in the form of an interactive PDF and allows the user to download the report.

The most important thing about this whole new experience is not just that these steps happen, but they happen inside one continuous chat experience.

Let us now go through the individual tools and take a look at some of their salient features:

1. `select-sales-metric` tool

Code - Tool Registration and MCP App

This is where the interactive chatflow begins. When the user prompts - "get sales data", instead of asking the user to specify every parameter via text, the agent calls this tool. VS Code (Host) then reads the linked resource and renders a rich HTML form with dropdown menus, toggle buttons, search region & multi-select state cards inside an iframe.

The Sales metric selector MCP App resides in sales-form.ts, where server-side data such as the list of valid sales regions (Indian states), sales metric and top sales regions are serialized directly into the HTML template:

...
<select id="metricSelect">${metricOptions}</select>
..
..
const indianStates = ${JSON.stringify(indianStates)};
const topStates = ${JSON.stringify(topStates)};

The makes the UI entirely self-contained as the page arrives already primed with the valid states and metrics. And, no further external API calls are required just to render the form or for data validation.

1.1. `get-sales-data` tool

Code - Tool Registration

When the user clicks "Submit" button in the Sales metric selector MCP App, the form doesn't just update the context — it calls another MCP tool from within the iframe itself by executing the below communication:

const toolResult = await sendRequest("tools/call", {
  name: "get-sales-data",
  arguments: {
    states: Array.from(selectedStates),
    metric: currentMetric,
    period: currentPeriod,
    year: currentYear,
  },
});
report = toolResult.structuredContent || null;

We trigger the data fetch manually via this tool as it allows us to have a deterministic control over the most critical element ("data") and we can explicitly define inputs without relying on agent reasoning. The tool is only visible to the app, and not the agent so it cannot call it accidentally. Only the MCP App iframe can invoke it via tools/call. This is a pattern I introduced in my previous article, and here you can see how powerful it becomes in a real workflow.

After fetching the result, ui/update-model-context request is sent to the host with the entire structured data (user input + data obtained for report) is added into the conversation context, so the agent can use it in subsequent turns.

await sendRequest("ui/update-model-context", {
  structuredContent: {
    selections: {
      metric: currentMetric,
      period: currentPeriod,
      year: currentYear,
      states: Array.from(selectedStates),
      selectedStateNames: selectedStateNames,
    },
    report: report,
  },
});
updateStatus("✅ Context updated successfully.");

2. `visualize-sales-data` tool

Code - Tool Registration & MCP App

Once the Agent has the structured data in its context, when the user prompts "visualize", the agent calls visualize-sales-data tool which renders a visualization dashboard inside the chat highlighting some key stats. Three additional complementary chart views are also presented in the dashboard for identifying deeper trends:

A stacked bar or line view for period-by-period comparison.
A doughnut chart to gauge a state's contribution share (%) in the sales metric.
A horizontal bar chart for ranked state comparison.

Two implementation details are especially worth noticing:

i) CSP is not a footnote, it is part of the Security Contract

The visualization MCP App depends on chart.js from a CDN:

<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.7/dist/chart.umd.min.js"><\/script>

As we discussed it in our previous article, the resource domain dependency is declared explicitly in the UI resource metadata while registering it.

csp: {
resourceDomains: ["https://cdn.jsdelivr.net"],
},

Without this declaration, the host sandbox will block the script. This demonstrates one of the most practical aspects of MCP Apps - the app states what it needs, and the host enforces that contract. An app cannot silently inherit broad network access just because it is an embedded HTML.

ii) MCP App receives tool input through notification

When the host invokes the visualize-sales-data tool, it forwards the structured payload to the iframe:

if (msg.method === "ui/notifications/tool-input") {
  const sc = msg.params?.structuredContent || msg.params?.arguments;
  if (sc && sc.report) {
    reportData = sc.report;
    selections = sc.selections;
    renderDashboard();
  }
}

This hydrates the UI with all the data it needs to render summary cards and charts. There is no string parsing or scraping of the tool response text. Just clean structured data flowing from tool to host to app.

3. `show-sales-pdf-report` tool

Code - Tool Registration & MCP App

Once the user has explored the interactive visualization dashboard, a PDF report generation can be triggered via show-sales-pdf-report tool using "generate pdf" prompt.

The following actions happen after the tool is triggered:

The server generates a PDF report using jsPDF and jspdf-autotable, and sends it to the client as a base64 string via structuredContent.
The PDF viewer MCP App decodes the base64 payload and renders it using PDF.js (from CDN). This interactive PDF viewer includes page navigation (previous/next) & zoom controls (keyboard shortcuts included).

The user also has the option to save the PDF report via a "Download PDF" button as shown below:

On clicking the "Download PDF" button a ui/download-file request is triggered which sends the resource (PDF) to VS Code which displays the save dialog.

const result = await request("ui/download-file", {
  contents: [
    {
      type: "resource",
      resource: {
        uri: "file:///" + pdfFileName,
        mimeType: "application/pdf",
        blob: pdfBase64,
      },
    },
  ],
});

That pattern is important as sandboxed iframes should not get to ability to save any file without informing the host which thereby informs the end user. Thus, the host stays in control, and the user gets a normal, expected download flow.

Serving MCP Apps Over HTTP

Currently, we are running the MCP server locally using Express with the Streamable HTTP transport - a departure from the stdio approach demonstrated in the previous article. This lets us run the server as an HTTP endpoint as we are moving closer to a deployable shape, making it ideal for web-based clients and remote deployments.

We can run the MCP server locally on node by executing:

cd /path/to/sample-mcp-apps-chatflow

# Install dependencies
npm install

# Development mode (with hot reload)
npm run dev

# Test with MCP Inspector
npm run inspector:http

which successfully displays

> sample-mcp-apps-chatflow@1.0.0 dev
> tsx src/index.ts

🚀 MCP Apps Chatflow server running at http://localhost:3000
📡 MCP endpoint: http://localhost:3000/mcp

To connect to this endpoint from VS Code Insiders, add the following config to .vscode/mcp.json:

{
  "servers": {
    "sample-mcp-apps-chatflow": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Deploying to Amazon Bedrock AgentCore Runtime (AgentCore CLI)

What is the value of building an awesome MCP server if you can't take it beyond the localhost? To be truly useful, it needs to be hosted so that your team or your users can connect to it from anywhere, without having to run it on their own system.

That's where Amazon Bedrock AgentCore Runtime comes in. It provides a managed, scalable runtime for your MCP server with built-in OAuth and session isolation.

Let us go ahead and deploy our TypeScript MCP server to Amazon Bedrock AgentCore Runtime.

Note: This guide uses the AgentCore CLI (@aws/agentcore), the current Node.js-based CLI. If you have the older Python-based bedrock-agentcore-starter-toolkit installed, uninstall it first to avoid command conflicts -- both tools use the agentcore command name.
pip uninstall bedrock-agentcore-starter-toolkit   # if installed via pip
pipx uninstall bedrock-agentcore-starter-toolkit  # if installed via pipx

Software prerequisites

Make sure you have the following softwares installed in your system:

AWS CLI with configured credentials (aws sts get-caller-identity must work)
Node.js 20+ and npm
Docker (or podman/finch) for container builds
AWS CDK bootstrapped in your target account/region (npx cdk bootstrap aws://ACCOUNT_ID/REGION)
VS Code or any other MCP Apps compatible Host or even terminal for testing the deployed MCP server

Step 1 - Prepare the server for AgentCore Runtime

AgentCore Runtime expects your MCP server to bind to 0.0.0.0:8000 and expose a POST /mcp endpoint using Streamable HTTP transport. The container must target linux/arm64.

In src/index.ts, update the port and host:

const port = parseInt(process.env.PORT || "8000");
const host = process.env.HOST || "0.0.0.0";

app.listen(port, host, () => {
  console.log(`🚀 MCP Apps Chatflow server running at http://${host}:${port}`);
  console.log(`📡 MCP endpoint: http://${host}:${port}/mcp`);
});

Step 2: Add a Dockerfile

Create a Dockerfile in the project root:

# Build stage
FROM --platform=linux/arm64 node:22-slim AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --ignore-scripts
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

# Production stage
FROM --platform=linux/arm64 node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev --ignore-scripts
COPY --from=builder /app/dist/ ./dist/
ENV PORT=8000
ENV HOST=0.0.0.0
EXPOSE 8000
CMD ["node", "dist/index.js"]

Add a .dockerignore:

node_modules
dist
agentcore
.git
*.md

Verify it builds and starts locally:

docker build --platform linux/arm64 -t sales-mcp-apps .
docker run --platform linux/arm64 -p 8000:8000 sales-mcp-apps
# Test with MCP Inspector:
npx @modelcontextprotocol/inspector http://localhost:8000/mcp

Step 3: Install the AgentCore CLI

npm install -g @aws/agentcore
agentcore --version

Step 4: Create the AgentCore project

From the project root, scaffold the AgentCore configuration:

agentcore create \
  --name salesmcpapps \
  --protocol MCP \
  --build Container \
  --no-agent \
  --skip-python-setup \
  --skip-git

This generates:

agentcore/
  agentcore.json      # Project and runtime configuration
  aws-targets.json    # AWS account and region target
  .cli/               # CLI state (deployed-state.json)
  cdk/                # CDK app for deployment

Configure the runtime

The agentcore create --no-agent command creates an empty runtimes array. You must manually add the runtime configuration to agentcore/agentcore.json. The important fields are:

codeLocation - path to the directory containing your Dockerfile, relative to the project root (the parent of agentcore/). If your Dockerfile is in the project root, use ".". If you isolate your app code in a subdirectory (recommended to avoid CDK bundling issues), use that path (e.g., "app").
entrypoint - the file that starts your server (e.g., "dist/index.js"). Required even for Container builds.
runtimeVersion - must be "NODE_22" for Node.js projects.
protocol - "MCP" for MCP servers.

Example agentcore/agentcore.json:

{
  "$schema": "https://schema.agentcore.aws.dev/v1/agentcore.json",
  "name": "salesmcpapps",
  "version": 1,
  "managedBy": "CDK",
  "tags": {
    "agentcore:created-by": "agentcore-cli",
    "agentcore:project-name": "salesmcpapps"
  },
  "runtimes": [
    {
      "name": "salesmcpapps",
      "build": "Container",
      "entrypoint": "dist/index.js",
      "codeLocation": ".",
      "runtimeVersion": "NODE_22",
      "protocol": "MCP",
      "tags": {}
    }
  ],
  "memories": [],
  "credentials": [],
  "evaluators": [],
  "onlineEvalConfigs": [],
  "agentCoreGateways": [],
  "policyEngines": []
}

Configure deployment target

Edit agentcore/aws-targets.json with your account ID and region:

[
  {
    "name": "default",
    "description": "Production deployment",
    "account": "YOUR_ACCOUNT_ID",
    "region": "us-east-1"
  }
]

Tip: If your Dockerfile is in the project root alongside agentcore/, the CDK asset bundler may hit path-length errors because it recursively copies the cdk.out directory into itself. To avoid this, put your application code (Dockerfile, package.json, src/, tsconfig.json) in a subdirectory (e.g., app/) and set "codeLocation": "app".

Step 5: Set up Cognito authentication

The AgentCore CLI does not have a built-in command to set up Cognito (unlike the deprecated toolkit's agentcore identity setup-cognito). You need to create the Cognito resources manually.

Create a Cognito User Pool

export REGION=us-east-1

# Create user pool
POOL_ID=$(aws cognito-idp create-user-pool \
  --pool-name "salesmcpapps-pool" \
  --region $REGION \
  --query 'UserPool.Id' --output text)
echo "Pool ID: $POOL_ID"

# Add a domain for the OAuth token endpoint
aws cognito-idp create-user-pool-domain \
  --user-pool-id $POOL_ID \
  --domain "salesmcpapps-auth" \
  --region $REGION

Create a Resource Server and App Client

For machine-to-machine authentication (client_credentials flow):

# Create resource server with a custom scope
aws cognito-idp create-resource-server \
  --user-pool-id $POOL_ID \
  --identifier "salesmcpapps-auth" \
  --name "Sales MCP Apps" \
  --scopes '[{"ScopeName":"invoke","ScopeDescription":"Invoke MCP server"}]' \
  --region $REGION

# Create app client with client_credentials flow
CLIENT_OUTPUT=$(aws cognito-idp create-user-pool-client \
  --user-pool-id $POOL_ID \
  --client-name "salesmcpapps-client" \
  --generate-secret \
  --explicit-auth-flows ALLOW_USER_PASSWORD_AUTH ALLOW_REFRESH_TOKEN_AUTH \
  --allowed-o-auth-flows client_credentials \
  --allowed-o-auth-scopes "salesmcpapps-auth/invoke" \
  --allowed-o-auth-flows-user-pool-client \
  --supported-identity-providers COGNITO \
  --region $REGION)

CLIENT_ID=$(echo $CLIENT_OUTPUT | python3 -c "import sys,json; print(json.load(sys.stdin)['UserPoolClient']['ClientId'])")
CLIENT_SECRET=$(echo $CLIENT_OUTPUT | python3 -c "import sys,json; print(json.load(sys.stdin)['UserPoolClient']['ClientSecret'])")

echo "Client ID: $CLIENT_ID"
echo "Client Secret: $CLIENT_SECRET"
echo "Discovery URL: https://cognito-idp.$REGION.amazonaws.com/$POOL_ID/.well-known/openid-configuration"

Add JWT auth to agentcore.json

Update the runtime in agentcore/agentcore.json to add authorizerType and authorizerConfiguration:

{
  "name": "salesmcpapps",
  "build": "Container",
  "entrypoint": "dist/index.js",
  "codeLocation": ".",
  "runtimeVersion": "NODE_22",
  "protocol": "MCP",
  "authorizerType": "CUSTOM_JWT",
  "authorizerConfiguration": {
    "customJwtAuthorizer": {
      "discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/YOUR_POOL_ID/.well-known/openid-configuration",
      "allowedClients": ["YOUR_CLIENT_ID"]
    }
  },
  "tags": {}
}

Step 6 - Deploy

agentcore deploy --target default --yes

This will:

Synthesize a CloudFormation template via CDK
Build your Docker container via AWS CodeBuild and push it to Amazon ECR
Create the AgentCore Runtime

The deployment takes roughly 5-10 minutes. On completion, the Runtime ARN is saved to agentcore/.cli/deployed-state.json.

Step 7 - Test the deployment

Get a Bearer token

TOKEN=$(curl -s -X POST \
  "https://salesmcpapps-auth.auth.$REGION.amazoncognito.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&scope=salesmcpapps-auth/invoke" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

Invoke the MCP server

URL-encode the Runtime ARN and call the invocations endpoint:

# Get runtime ARN from deployed state
RUNTIME_ARN=$(python3 -c "
import json
with open('agentcore/.cli/deployed-state.json') as f:
    state = json.load(f)
rt = list(state['targets']['default']['resources']['runtimes'].values())[0]
print(rt['runtimeArn'])
")

# URL-encode the ARN
ENCODED_ARN=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$RUNTIME_ARN', safe=''))")

# Test MCP initialize
curl -s -X POST \
  "https://bedrock-agentcore.$REGION.amazonaws.com/runtimes/${ENCODED_ARN}/invocations" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $TOKEN" \
  -H "User-Agent: test-client/1.0" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' \
  | python3 -m json.tool

You should see a response with serverInfo, capabilities including resources and tools.

List tools and resources

After initialize, you can send tools/list and resources/list requests (include the mcp-session-id header from the initialize response).

Step 8 - Connect from VS Code

In VS Code with an MCP Apps-compatible client, create a .vscode/mcp.json in your workspace:

{
  "servers": {
    "sales-mcp-apps": {
      "type": "http",
      "url": "https://bedrock-agentcore.REGION.amazonaws.com/runtimes/DOUBLE_ENCODED_ARN/invocations",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Important: double-encode the / in the ARN. VS Code's URL parser decodes %2F back to / before sending the request, which breaks the ARN path segment. Use %252F instead of %2F so that after VS Code decodes once, the server receives the correct %2F.

For example, if your ARN is:
arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my-server-abc123
The URL in mcp.json should be:
https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/arn%3Aaws%3Abedrock-agentcore%3Aus-east-1%3A123456789012%3Aruntime%252Fmy-server-abc123/invocations
Note %252F (not %2F) before the runtime name.

Once connected, VS Code will discover the tools and render the MCP Apps UIs (sales metric selector, visualization charts, PDF report viewer) as interactive HTML panels in the chat as shown below:

Clean up

To remove deployed resources, delete the CloudFormation stack:

aws cloudformation delete-stack \
  --stack-name AgentCore-salesmcpapps-default \
  --region $REGION

Also clean up Cognito:

aws cognito-idp delete-user-pool-domain \
  --user-pool-id $POOL_ID \
  --domain "salesmcpapps-auth" \
  --region $REGION

aws cognito-idp delete-user-pool \
  --user-pool-id $POOL_ID \
  --region $REGION

Final Words

MCP Apps is no longer a theoretical specification - it's a practical framework for building rich, interactive experiences inside AI chatflows. This sales analytics case study demonstrates the full spectrum: forms for structured input, Chart.js for visualization, jsPDF for document generation, and the MCP Apps protocol gluing it all together.

The patterns described here — app-only tools, structured content flow, CSP declarations, server-side PDF generation - are directly transferable to your own use cases. Whether you're building a CRM dashboard, a data annotation tool, or an interactive report builder, the approach remains the same. We also saw how Amazon Bedrock AgentCore can be used for deploying MCP remote servers securely.

I would love to hear your experience with MCP Apps or about any issues you faced while going through this article. Please mention it in the comment section below and I will definitely address it. Also, in case you have any other suggestion, feel free to add it in the comments.

by Ashita Prasad (GitHub, LinkedIn, X, Instagram)

Disclaimer: The opinions expressed here are my own and do not necessarily represent those of current or past employers. Please note that you are solely responsible for your judgement on checking facts. This post does not monetize via any advertising.

How I render interactive UI in my AI Agent chatflows using MCP Apps

Ashita Prasad — Thu, 12 Mar 2026 01:59:36 +0000

You know the feeling of building an incredibly smart AI agent that chats flawlessly, but the second your user needs to interact with a complex dataset, fill out a structured form, or view a real-time chart, that conversation hits a dead end.

And you realize - Plain text just isn't enough!

Right now, the only way around this is forcing users out of the chat and into an external web app. For you, that means suddenly wrestling with custom APIs, building redundant authentication layers, and taping together fragile state management. Whereas, for your users, the seamless conversational flow shatters, context vanishes, and the experience instantly feels disjointed.

And, instead of building something magical, you end up buried in development overhead just to show a simple graph.

I was going through a similar experience recently while building an Agentic chatflow and then I came across MCP Apps. Built as an extension of the open-source Model Context Protocol (MCP), MCP Apps give you a standardized escape route from the plain-text trap and let your MCP server deliver rich, bidirectional UIs - like interactive dashboards, data collection forms, and real-time visualizations—rendered securely and natively right inside your AI host.

Are you ready to fix your AI Agent Chat-flow? In this 2-part step-by-step tutorial series, I will explain:

The Foundations of MCP Apps (This article) - Covering the core architectural patterns for declaring UI resources, practical design principles, and how to handle sandboxed host–server communication.
How you can deploy a real-world TypeScript MCP App Server on Amazon Bedrock AgentCore. 👇

How I built MCP Apps based Sales Analytics Agentic UI & deployed it on Amazon Bedrock AgentCore

Ashita Prasad
Ashita Prasad

Ashita Prasad

Follow

for AWS
Apr 1

How I built MCP Apps based Sales Analytics Agentic UI & deployed it on Amazon Bedrock AgentCore

#ai #javascript #typescript #mcp

9 reactions
Comments Add Comment

15 min read

Getting started

1. Project directory structure

Let us create the following directory structure for our MCP server project:

src/
  index.ts
  ui/
    greeting.ts
    host-style-variables.ts
    ...
    tools-call.ts
  utils/
    apply-host-context.ts
    message-handler.ts
    rpc-client.ts
    shared-styles.ts

I have created this practical directory structure for building MCP Apps so that it is not just functional, but coherent and maintainable, where:

src/index.ts is the MCP server entry point where we register all tools and UI resources,
src/ui contains UI resources for each MCP App, and
src/utils contains the shared utilities for design and communication used across UI resources, making them maintainable and consistent.

2. Shared design system for consistency & maintainability

As MCP Apps provide the visual interface to interact with MCP tools, a consistent design system across all UI resources provides a better user experience. In this project, utils/shared-styles.ts contains:

Design tokens for background, text, border, etc.
light-dark(...) fallbacks so the same app can adapt cleanly across themes.
Typography tokens, spacing utilities, and border radius primitives.
Reusable UI components for cards, badges, buttons, inputs, textareas, logs, and tables.

A snapshot of shared-styles.ts file is provided below:

In absence of shared-styles.ts, each app would feel disconnected and require re-implementation of styling, spacing, components and form controls.

3. Other utilities

We also define some more utility files that contain the common scripts used across all MCP apps defined in the server:

utils/rpc-client.ts (Link to code file): Creates the JSON-RPC client embedded in each HTML template that manages request IDs, tracks pending promises, and provides request and notify helpers.
utils/message-handler.ts (Link to code file): Handles inbound messages, resolves pending RPC calls, and responds to host context changes.

A deeper look into MCP Apps via examples

Now, we are ready to dive deeper into the various concepts involved while building an MCP App.

1. Anatomy of a minimal MCP App

Let us get started with creating our first MCP App.

Step 1 - Resource and Tool Registration

Add the following code in the index.ts file:

In this file,

const URI = "ui://mcp-apps-spec-examples";

is the base URI of the UI resources.

const MIME = "text/html;profile=mcp-app" as const;

is the official mime-type of the HTML content which is loaded by the host as a sandboxed iframe.

const server = new McpServer({
  name: "mcp-apps-spec-examples",
  version: "1.0.0",
});

initializes a new Model Context Protocol (MCP) Server instance.

server.registerResource(
  "greeting",
  `${URI}/greeting`,
  { mimeType: MIME, description: "A static greeting with no interaction." },
  async (uri) => ({
    contents: [{ uri: uri.href, mimeType: MIME, text: GREETING_HTML() }],
  }),
);

registers a new UI resource named "greeting" with the unique identifier "ui://mcp-apps-spec-examples/greeting". The HTML content is provided by GREETING_HTML() which we will cover shortly.

server.registerTool(
  "greeting",
  {
    description: "A greeting tool with no interaction.",
    _meta: { ui: { resourceUri: `${URI}/greeting` } },
  },
  async () => {
    return { content: [{ type: "text" as const, text: "Greeting executed." }] };
  },
);

registers a tool linked to the resource "ui://mcp-apps-spec-examples/greeting" through _meta.ui.resourceUri.

This pattern is the backbone of MCP Apps as the server declares the view, the tool points at the view, and the host knows exactly what to load.

Step 2 - UI Resource Creation (App Template)

Let us now define the MCP App resource GREETING_HTML() in ui/greeting.ts. It is a static HTML with no user interaction.

This UI runs in a sandboxed iframe and communicates with the host through auditable JSON-RPC messages.

When the UI calls ui/initialize as shown below:

request('ui/initialize', { protocolVersion: '2025-11-21' }).then((res) => {
  notify('ui/notifications/initialized');
  document.getElementById('status').textContent = '✅ Handshake complete – UI is live.';
});

The host returns hostContext and capabilities (covered later in detail), post which the UI sends ui/notifications/initialized to complete the handshake.

This is the minimum viable MCP App which is just HTML + the MCP Apps handshake.

Step 3 - Running the MCP App

To witness the MCP app in action,

We will first compile the TypeScript code via:

npm run build

Download a host that supports MCP Apps extension. We will use VS Code Insiders to test our MCP Apps.
Open a new folder in VS Code Insiders and create .vscode/mcp.json file which runs the MCP server locally:

Now, using the chat prompt show greeting we can trigger the tool call rendering the MCP App as shown below.

2. Host-aware MCP App Theme

You can witness in the above demo that the MCP App card theme is currently not blending with the host theme. To provide a consistent user experience it is important to make an embedded app look native instead of bolted on iframe. The MCP Apps specification provides this provision during the MCP Apps protocol handshake - When the View (App) sends an ui/initialize request to the host, the host responds with its current hostContext (theme + style tokens) as shown below:

--color-background-primary = var(--vscode-editor-background)
--color-background-secondary = var(--vscode-sideBar-background)
....
--color-text-primary = var(--vscode-foreground)
--color-text-secondary = var(--vscode-descriptionForeground)
....
--font-weight-semibold = 600
--font-weight-bold = bold
....
--font-text-xs-line-height = 1.5
--font-text-sm-line-height = 1.5
....

These host-provided CSS variables are practical styling input that a UI can inspect and render using applyHostContextScript() function defined in utils/apply-host-context.ts.

Let us modify ui/greeting.ts to execute applyHostContext(res?.hostContext); to update the CSS theme and make it host-aware:

import { applyHostContextScript } from "../utils/apply-host-context.js";
...
...
${applyHostContextScript()}
...
    request('ui/initialize', { protocolVersion: '2025-11-21' }).then((res) => {
      applyHostContext(res?.hostContext);
      notify('ui/notifications/initialized');
      document.getElementById('status').textContent = '✅ Applied Host Context & Handshake complete.';
    });
...

(Link to full code)

Now, using the same chat prompt we can trigger the tool call rendering the MCP App with host theme applied on it.

3. Discovering Host Capabilities

An MCP App should not assume that every host supports the same set of features. hostCapabilities are sent to the View when it sends an ui/initialize request to the host which describes the capabilities the host supports like:

Capability	Description
`openLinks`	Host supports opening external URLs/links from within the MCP app in the host's browser or external application.
`serverTools`	Can proxy tool calls where the host will re-fetch the tool list and update its UI accordingly.
`serverResources`	Host can proxy resource reads and refresh its resource listing when the server's resource set changes.
`logging`	Host supports the MCP logging capability, allowing the server to emit structured log messages back to the host.
`sandbox.permissions.clipboardWrite`	App runs in a sandboxed environment, but has been granted the permission to copy content to the user's clipboard.
`updateModelContext`	Host can accept context updates pushed from the app. The supported content types can be - audio, image, structuredContent (JSON), etc.
`downloadFile`	App can trigger a file download in the host environment (e.g., save to Downloads).

Host capabilities can be obtained from the host response to 'ui/initialize' as shown below:

request('ui/initialize', { protocolVersion: '2025-11-21' }).then((res) => {
  applyHostContext(res?.hostContext);
  notify('ui/notifications/initialized');
  const caps = res?.hostCapabilities || {}; // host capabilities
});

Let us add the UI Resource (ui/host-capabilities.ts) and register the resource & tool as shown here. On calling the tool, the MCP app will get rendered showing all the host capabilities as shown below:

4. Example Host Capability - Open Link

Let us explore the host capability of directly navigating from the iframe by opening an external URL.

Create the App UI resource ui/open-link.ts (code).

It contains the openLink() function which triggers the ui/open-link request with the URL parameter. This lets the host know that the app is requesting it to open the specified URL.

async function openLink() {
  const url = document.getElementById("urlInput").value;
  try {
    await request("ui/open-link", { url });
    el.textContent = "✅ Host accepted the request for:\n" + url;
  } catch (err) {
    el.textContent = "❌ Host denied or error:\n" + JSON.stringify(err);
  }
}

Let us register this resource and the corresponding tool "open-link-from-app" (code).

After entering the prompt, the agent displays the MCP App as shown below:

On clicking the Open button, the MCP App requests the host to open the URL and the host opens a confirmation dialog which demonstrates the security-first approach where "apps request, hosts decide".

Upon pressing the Open confirmation button, the requested website is opened in the default browser.

5. Updating Model Context via MCP App

Interactions with an MCP App can often generate useful context (of various content types) that can be directly added to the host's model context. This helps with preference capture, session refinement, and app-guided workflows.

Let us create ui/update-model-context.ts (code), which adds the text entered by the user to the model context via ui/update-model-context request:

await request("ui/update-model-context", {
  content: [{ type: "text", text }],
});

Let us register the resource & tool (code).

Upon triggering the tool, the MCP App is displayed as shown below:

Once the user enters the text and presses the Update Context button, the updated context can be seen in the chat box.

6. Adding Message to the Chat Box

MCP App also provides the ability to send content back into the host's chat box, to enable user to edit it before sending it to the chat flow.

Let us create ui/ui-message.ts (code).

To send the message to chat box, ui/message request can be triggered with the text content.

await request("ui/message", {
  role: "user",
  content: [{ type: "text", text }],
});

Let's register the resource & tool (code).

Upon triggering the tool, the MCP App gets displayed as shown below:

It allows user to communicate a text message from the MCP App to the host's chat box. This opens up new possibilities as the App is no longer a visual tool, and is a part of the conversation loop.

7. Resizing the iframe

As the content of an MCP App expands, there is a provision to send a size-changed notification to the host to ensure that the frame is sized correctly.

Let us create ui/size-changed.ts (code).

We will use ResizeObserver to report any changes to the dimensions of an Element's content or border box and send ui/notifications/size-changed so the host can resize the frame.

const ro = new ResizeObserver(() => {
  notifyCount++;
  const w = document.documentElement.scrollWidth;
  const h = document.documentElement.scrollHeight;
  notify('ui/notifications/size-changed', { width: w, height: h });
  document.getElementById('sizeInfo').textContent =
    'Notifications sent: ' + notifyCount + '  (current: ' + w + '×' + h + ')';
});
ro.observe(document.body);

Let us now register the resource & the tool (code).

We can press the +Add Item button to add new data rows. The updated value of scroll width and scroll height are notified to the host so that it can update the iframe height accordingly.

This feature solves a real UX pain point as the host can get the required size and grow or shrink the iframe accordingly.

8. Content Security Policy (CSP)

So far we have been working with Apps that have self-contained CSS & JS, and are not making any request to fetch data using external API.

As MCP Apps are executed inside a sandbox by the host to avoid any security risks, Content Security Policy (CSP) is the mechanism for explicitly defining which resources the MCP App is allowed to load or execute. This prevents malicious scripts or external resources from being injected into the MCP App, which in turn protects the host.

The typical flow of applying CSP in an MCP App is as follows:

MCP server returns a tool response with UI metadata.
The host renders the MCP App in a sandboxed iframe.
The host applies CSP rules.
The MCP App can only access approved resources.

This external access is declared through the metadata during resource registration. The resource must include _meta.ui.csp so that the host can allow MCP App access to only the specific domains. Different types of domains that can be provided are:

Field	Purpose
`connectDomains`	Origins the MCP App can reach via network/data requests (`fetch`, `XHR`, or `WebSocket`).
`resourceDomains`	Origins allowed to load static assets like images, scripts, stylesheets, fonts, media.
`frameDomains`	Origins for nested iframes
`baseUriDomains`	Allowed base URIs for the document

Let us register csp-example, a sample resource and tool (code), where

csp: {
  connectDomains: ["https://httpbin.org"],
  resourceDomains: ["https://cdn.jsdelivr.net"],
},

registers the allowed domains.

Now create ui/csp-example.ts (code), where

<script src="https://cdn.jsdelivr.net/npm/dayjs@1/dayjs.min.js"><\/script>

loads the external dayjs javascript library that is used to format the current date using dayjs().format('dddd, MMMM D YYYY') method.

Also, when we press the button Fetch, the MCP App executes runDirectFetch() to fetch the latest content from REST API endpoint https://httpbin.org/get as shown below:

async function runDirectFetch() {
  const el = document.getElementById('result');
  el.textContent = 'Testing direct fetch from browser…';
  try {
    const res = await fetch('https://httpbin.org/get');
    const json = await res.json();
    el.textContent = '✅ Direct fetch successful! (CSP allows this)\\n\\n' + JSON.stringify(json, null, 2).substring(0, 800);
  } catch (err) {
    el.textContent = '❌ Direct fetch blocked: ' + err.message;
  }
}

Let us now execute tool which loads the MCP App as shown below:

9. Calling MCP Tools

One of the key innovations of MCP Apps is the ability provided to invoke another MCP tool using the tools/call method from inside an MCP App making it an interaction surface for broader tool orchestration.

Let us create and register a new tool eval-tool on the MCP server which evaluates a string expression:

Once you create a new build and restart the server, you can verify that this tool is now visible to the agent.

MCP Apps spec, provides a provision to restrict this visibility of any tool to only the MCP Apps available on the server using _meta.ui.visibility field which defaults to ["model", "app"] that means that the tool is visible to agent and the MCP Apps.

You can hide any tool from the agent but make it callable by MCP apps via tools/call, by setting its visibility value to ["app"] (code) as shown below:

_meta: {
  ui: {
    visibility: ["app"],
  },
},

Let us verify the same. The tool is no longer visible to the agent as shown below:

This feature now enables UI-only interactions (refresh buttons, form submissions) without exposing implementation details to the agent/model.

Let us create ui/tools-call.ts (code). When the user presses the Call tools/call button, it makes a tools/call request and populates the result as shown below:

const res = await request("tools/call", {
  name: "eval-tool",
  arguments: { expression },
});
el.textContent = res["structuredContent"]["result"];

Let us now run the MCP App to evaluate some mathematical expressions as shown below:

You can now witness how powerful the MCP App interface can be for invoking deeper tool workflows.

Final Words

Today, we deep dived into some of the foundational building blocks of an MCP App. With these learnings, in the next article we will look at a real world agentic workflow use case demonstrating the power of MCP Apps.

I would love to hear your experience with MCP Apps or about any issues you faced while going through this tutorial. Please mention it in the comment section below and I will definitely address it. Also, in case you have any other suggestion, feel free add it in the comments.

Do check out the next article in this series:

Ashita Prasad for AWS

Apr 1

How I built MCP Apps based Sales Analytics Agentic UI & deployed it on Amazon Bedrock AgentCore

#ai #javascript #typescript #mcp

Comments

15 min read

by Ashita Prasad (GitHub, LinkedIn, X, Instagram)

Flutter Gems - April 2022 Update 💙 🎉

Ashita Prasad — Wed, 20 Apr 2022 09:26:41 +0000

I am super excited to announce the latest major update of Flutter Gems.

In you are new to the Flutter ecosystem or have not heard about Flutter Gems before, it is a curated package guide for Dart + Flutter ecosystem where the packages are neatly segregated based on functionality.

👇👇👇👇👇👇

Flutter Gems - A Curated List of Top Dart and Flutter packages

Flutter Gems is a curated list of top Dart and Flutter packages that are categorized based on functionality. Flutter Gems is also a visual alternative to pub.dev

fluttergems.dev

So what’s new in this update:

1200+ new packages, 12 new categories

We have now added 1200+ new packages to Flutter Gems which brings the total package count to 4000+ 🎉.

These packages are spread across 157 categories, and the following 12 new categories have been introduced:

Storybook or Component Driven UI Development packages which help Flutter developers in building UI components and widgets in isolation so that you can easily design, test and iterate to build the perfect component.
Persistent Storage packages have now been split into SQL Database packages (embedded or on-device SQL database packages and utilities) & NoSQL Database packages (embedded or on-device Document Datastore & Key-Value Store packages).
Health & Fitness packages assist in connecting your Flutter app to HealthKit, GoogleFit and other APIs.
Web3, Crypto & Blockchain is the hottest new addition. Don’t forget to bookmark it, we will definitely see a lot of new developments in this field.
Image Cropping is one of the most commonly used Image manipulation activity that is undertaken in an app. We now have a dedicated category to solve all your cropping needs.
Dual Screen and Folding Device UI packages help you utilize the full potential of the extra screen so that you can craft wonderful User Experience.
Widget Rendering and UI Generation packages help you in building UI on the fly. Just supply the requisite JSON or specified format (cloud or device) and let the magic happen!
Device Preview, Screen Capture & Screenshot packages help you add the ability to capture screenshots via your app.
Packages which can help you add React like Hooks in Flutter, so that you can have a robust and simple way to manage the widget lifecycle by reducing duplication and increasing code sharing.
Code Generation & Serialization (JSON, other formats) packages
MS Word, ODT, Google Doc packages

Brand New UI

We have refreshed our website to provide better user experience on larger screens (reduced scrolling and better drawer navigation).

Improved Search

We introduced a new search tool in our mid-January update to filter categories based on keyword or package name. In this release we have made further improvements in the tool.

You can also follow us on Twitter for latest updates. 👇

// Detect dark theme var iframe = document.getElementById('tweet-1516445877556056067-97'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1516445877556056067&theme=dark" }

Forem: Ashita Prasad

How I built MCP Apps based Sales Analytics Agentic UI & deployed it on Amazon Bedrock AgentCore

ashitaprasad / sample-mcp-apps-chatflow

Sample MCP Apps Chatflow

Articles

The Problem: When chat isn't enough!

The Solution: A Chatflow powered by MCP Apps

1. select-sales-metric tool

1.1. get-sales-data tool

2. visualize-sales-data tool

i) CSP is not a footnote, it is part of the Security Contract

ii) MCP App receives tool input through notification

3. show-sales-pdf-report tool

Serving MCP Apps Over HTTP

Deploying to Amazon Bedrock AgentCore Runtime (AgentCore CLI)

Software prerequisites

Step 1 - Prepare the server for AgentCore Runtime

Step 2: Add a Dockerfile

Step 3: Install the AgentCore CLI

Step 4: Create the AgentCore project

Configure the runtime

Configure deployment target

Step 5: Set up Cognito authentication

Create a Cognito User Pool

Create a Resource Server and App Client

Add JWT auth to agentcore.json

Step 6 - Deploy

Step 7 - Test the deployment

Get a Bearer token

Invoke the MCP server

List tools and resources

Step 8 - Connect from VS Code

Clean up

Final Words

How I render interactive UI in my AI Agent chatflows using MCP Apps

How I built MCP Apps based Sales Analytics Agentic UI & deployed it on Amazon Bedrock AgentCore

Getting started

1. Project directory structure

2. Shared design system for consistency & maintainability

3. Other utilities

A deeper look into MCP Apps via examples

1. Anatomy of a minimal MCP App

Step 1 - Resource and Tool Registration

Step 2 - UI Resource Creation (App Template)

Step 3 - Running the MCP App

2. Host-aware MCP App Theme

3. Discovering Host Capabilities

4. Example Host Capability - Open Link

5. Updating Model Context via MCP App

6. Adding Message to the Chat Box

7. Resizing the iframe

8. Content Security Policy (CSP)

9. Calling MCP Tools

Final Words

How I built MCP Apps based Sales Analytics Agentic UI & deployed it on Amazon Bedrock AgentCore

Flutter Gems - April 2022 Update 💙 🎉

Flutter Gems - A Curated List of Top Dart and Flutter packages

1200+ new packages, 12 new categories

Brand New UI

Improved Search

1. `select-sales-metric` tool

1.1. `get-sales-data` tool

2. `visualize-sales-data` tool

3. `show-sales-pdf-report` tool