{"id":292,"date":"2026-08-26T14:23:42","date_gmt":"2026-08-26T14:23:42","guid":{"rendered":"https:\/\/subashselvaraj.com\/?p=292"},"modified":"2026-08-26T14:23:42","modified_gmt":"2026-08-26T14:23:42","slug":"agentic-apps-using-app-builder-and-mcp-part-2","status":"publish","type":"post","link":"https:\/\/subashselvaraj.com\/index.php\/2026\/08\/26\/agentic-apps-using-app-builder-and-mcp-part-2\/","title":{"rendered":"Agentic Apps Using App Builder and MCP\u200a\u2014\u200aPart\u00a02"},"content":{"rendered":"\n

Building the Agentic App\u200a\u2014\u200aturning a plain MCP tool into an interactive HTML experience the host renders inline.<\/p>\n\n\n\n

In Part 1<\/a>, we scaffolded an MCP server with aio app init<\/code> using the @adobe\/generator-app-remote-mcp-server-generic<\/code> template. That template ships three sample tools – echo<\/code>, calculator<\/code>, and weather<\/code> – but weather<\/code> only returns a text summary, there’s no UI.<\/p>\n\n\n\n

This part turns weather<\/code> into an Agentic App<\/strong>: a tool that still returns structured data, but also renders an interactive HTML card inside the MCP host – themed and animated to match the reported condition (sun, clouds, rain, snow), with a search box that lets you check another city without leaving the card.<\/p>\n\n\n\n

\n\n\n\n

1. Add MCP Apps Dependencies<\/h3>\n\n\n\n

Part 1 already gave you @adobe\/aio-sdk<\/code>, @modelcontextprotocol\/sdk<\/code>, and zod<\/code> from the generator template. Add the MCP Apps extension and the dev dependencies needed to build the UI:<\/p>\n\n\n\n

npm install @modelcontextprotocol\/ext-apps\nnpm install -D vite vite-plugin-singlefile typescript<\/code><\/pre>\n\n\n\n
Your package.json<\/code> should now include:<\/p>\n\n\n\n
{\n  \"dependencies\": {\n    \"@adobe\/aio-sdk\": \"^5.0.0\",\n    \"@modelcontextprotocol\/ext-apps\": \"^1.7.5\",\n    \"@modelcontextprotocol\/sdk\": \"^1.24.0\",\n    \"zod\": \"^3.23.8\"\n  },\n  \"devDependencies\": {\n    \"vite\": \"^8.1.5\",\n    \"vite-plugin-singlefile\": \"^2.3.3\",\n    \"typescript\": \"^7.0.2\"\n  }\n}<\/code><\/pre>\n\n\n\n
\n\n\n\n
2. Project Layout for the UI<\/h3>\n\n\n\n
Add an app-ui<\/code> source folder alongside your server action:<\/p>\n\n\n\n
actions\/mcp-server\/\n\u251c\u2500\u2500 index.js\n\u251c\u2500\u2500 tools.js\n\u251c\u2500\u2500 validator.js\n\u251c\u2500\u2500 embedded-ui.js             # Generated - do not edit (npm run embed:ui)\n\u251c\u2500\u2500 app-ui\/                    # MCP App UI source\n\u2502   \u251c\u2500\u2500 vite.config.mjs\n\u2502   \u251c\u2500\u2500 tsconfig.json\n\u2502   \u2514\u2500\u2500 src\/\n\u2502       \u251c\u2500\u2500 global.css\n\u2502       \u2514\u2500\u2500 weather\/\n\u2502           \u251c\u2500\u2500 weather.html\n\u2502           \u251c\u2500\u2500 weather.ts\n\u2502           \u2514\u2500\u2500 weather.css\n\u2514\u2500\u2500 static\/                    # Generated - single-file HTML bundles (gitignored)\n    \u2514\u2500\u2500 weather.html<\/code><\/pre>\n\n\n\n
Each MCP App view gets its own subfolder under app-ui\/src\/<\/code>. weather<\/code> is the only one the template ships with, but the build is set up so adding more is just a matter of adding another folder – see Extending to Multiple Views<\/a>.<\/p>\n\n\n\n
\n\n\n\n
3. Build the UI with\u00a0Vite<\/h3>\n\n\n\n
Create actions\/mcp-server\/app-ui\/vite.config.mjs<\/code>:<\/p>\n\n\n\n
import path from 'path'\nimport { fileURLToPath } from 'url'\nimport { defineConfig } from 'vite'\nimport { viteSingleFile } from 'vite-plugin-singlefile'\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url))\n\/\/ APP selects which UI to build. Each MCP App UI lives under src\/<app-name>\/<app-name>.html\n\/\/ (see scripts\/build-ui.js, which builds every one of them by setting this env var in turn).\nconst APP = process.env.APP || 'weather'\nconst appRoot = path.join(__dirname, 'src', APP)\nexport default defineConfig({\n  root: appRoot,\n  plugins: [viteSingleFile()],\n  build: {\n    outDir: path.join(__dirname, '..\/static'),\n    emptyOutDir: false,\n    rollupOptions: {\n      input: path.join(appRoot, `${APP}.html`)\n    }\n  }\n})<\/code><\/pre>\n\n\n\n
vite-plugin-singlefile<\/code> inlines all CSS and JavaScript into one HTML file. That matters on I\/O Runtime: the deployed action bundle is the only artifact that ships to production.<\/p>\n\n\n\n
Instead of hardcoding a build command per view, scripts\/build-ui.js<\/code> discovers every folder under app-ui\/src\/<\/code> and builds each one by setting APP<\/code> in turn:<\/p>\n\n\n\n
scripts\/build-ui.js<\/p>\n\n\n\n
const appUiSrcDir = path.join(__dirname, '..\/actions\/mcp-server\/app-ui\/src')\nconst configPath = path.join(__dirname, '..\/actions\/mcp-server\/app-ui\/vite.config.mjs')\nconst viteBin = path.join(__dirname, '..\/node_modules\/.bin\/vite')\n\nconst appNames = fs.readdirSync(appUiSrcDir, { withFileTypes: true })\n  .filter((entry) => entry.isDirectory())\n  .map((entry) => entry.name)\n  .filter((name) => fs.existsSync(path.join(appUiSrcDir, name, `${name}.html`)))\n  .sort()\nfor (const name of appNames) {\n  console.log(`\\n> Building ${name}`)\n  execFileSync(viteBin, ['build', '--config', configPath], {\n    stdio: 'inherit',\n    env: { ...process.env, APP: name }\n  })\n}<\/code><\/pre>\n\n\n\n
Add build scripts to package.json:<\/p>\n\n\n\n
{\n  \"scripts\": {\n    \"build\": \"npm run build:ui && npm run embed:ui && webpack\",\n    \"build:ui\": \"node scripts\/build-ui.js\",\n    \"embed:ui\": \"node scripts\/embed-ui.js\",\n    \"deploy\": \"npm run build && aio app deploy\",\n    \"start\": \"node local-server.js\"\n  }\n}<\/code><\/pre>\n\n\n\n
Why an embed script?<\/h4>\n\n\n\n
Adobe I\/O Runtime deploys a single webpack bundle. Static files in actions\/mcp-server\/static\/<\/code> are not<\/strong> deployed alongside the action. scripts\/embed-ui.js<\/code> solves this by discovering every built HTML file and inlining it into a JS module the server can require()<\/code>:<\/p>\n\n\n\n
scripts\/embed-ui.js<\/p>\n\n\n\n
const staticDir = path.join(__dirname, '..\/actions\/mcp-server\/static')\nconst outPath = path.join(__dirname, '..\/actions\/mcp-server\/embedded-ui.js')\nconst toCamelCase = (stem) => stem.replace(\/-([a-z0-9])\/gi, (_, c) => c.toUpperCase())\n\nconst embedded = {}\nfor (const filename of fs.readdirSync(staticDir).filter((f) => f.endsWith('.html'))) {\n  const key = `${toCamelCase(filename.replace(\/\\.html$\/, ''))}Html`\n  embedded[key] = fs.readFileSync(path.join(staticDir, filename), 'utf8')\n}\nfs.writeFileSync(outPath, `module.exports = ${JSON.stringify(embedded, null, 2)}\\n`)<\/code><\/pre>\n\n\n\n
weather.html<\/code> becomes the key weatherHtml<\/code> in embedded-ui.js<\/code> – the same key tools.js<\/code> passes to loadUiHtml()<\/code> (Step 6). At request time, the server prefers this embedded HTML; during local dev it falls back to reading files from static\/<\/code> if the embed step hasn’t run yet.<\/p>\n\n\n\n
\n\n\n\n
4. Create the HTML Shell<\/h3>\n\n\n\n
weather.html<\/code> is a minimal shell. The TypeScript entry point owns all dynamic behavior:<\/p>\n\n\n\n
<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"UTF-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n  <meta name=\"color-scheme\" content=\"light dark\">\n  <title>Weather<\/title>\n<\/head>\n<body>\n  <main class=\"main\" id=\"main\" data-category=\"loading\">\n    <div class=\"weather-fx\" id=\"fx\" aria-hidden=\"true\"><\/div>\n\n    <div class=\"search-row\">\n      <input type=\"text\" id=\"city-input\" class=\"city-input\" placeholder=\"Check another city\u2026\" aria-label=\"City name\">\n      <button type=\"button\" id=\"search-btn\" class=\"btn-search\">Search<\/button>\n    <\/div>\n\n    <section class=\"card\" id=\"card\" data-state=\"loading\">\n      <header class=\"card-header\">\n        <div class=\"location\">\n          <h1 class=\"city-name\" id=\"city-name\">\u2014<\/h1>\n          <p class=\"country-name\" id=\"country-name\"><\/p>\n        <\/div>\n        <div class=\"icon-wrap\" id=\"icon-wrap\">\n          <!-- one .icon per condition (sun\/cloud\/rain\/snow\/loading) - CSS shows only\n               the one matching main[data-category]; see weather.css -->\n        <\/div>\n      <\/header>\n\n      <div class=\"temp-row\">\n        <span class=\"temperature\" id=\"temperature\">--\u00b0<\/span>\n        <span class=\"condition\" id=\"condition\">\u2014<\/span>\n      <\/div>\n\n      <dl class=\"details-grid\" id=\"details-grid\">\n        <div class=\"detail\"><dt>Humidity<\/dt><dd id=\"detail-humidity\">\u2014<\/dd><\/div>\n        <div class=\"detail\"><dt>Wind<\/dt><dd id=\"detail-wind\">\u2014<\/dd><\/div>\n        <div class=\"detail\"><dt>Pressure<\/dt><dd id=\"detail-pressure\">\u2014<\/dd><\/div>\n        <div class=\"detail\"><dt>Visibility<\/dt><dd id=\"detail-visibility\">\u2014<\/dd><\/div>\n        <div class=\"detail\"><dt>UV Index<\/dt><dd id=\"detail-uv\">\u2014<\/dd><\/div>\n      <\/dl>\n\n      <p class=\"updated\" id=\"updated\"><\/p>\n    <\/section>\n\n    <p class=\"error-message\" id=\"error-message\" hidden><\/p>\n  <\/main>\n  <script type=\"module\" src=\".\/weather.ts\"><\/script>\n<\/body>\n<\/html><\/code><\/pre>\n\n\n\n
\n\n\n\n
5. Implement the MCP App Client<\/h3>\n\n\n\n
The client-side code uses the App<\/code> class from @modelcontextprotocol\/ext-apps<\/code>. Register lifecycle handlers before<\/strong> calling connect()<\/code>:<\/p>\n\n\n\n
import {\n  App,\n  applyDocumentTheme,\n  applyHostFonts,\n  applyHostStyleVariables,\n  type McpUiHostContext,\n} from \"@modelcontextprotocol\/ext-apps\";\nimport type { CallToolResult } from \"@modelcontextprotocol\/sdk\/types.js\";\nimport \"..\/global.css\";\nimport \".\/weather.css\";\n\nconst mainEl = document.getElementById(\"main\") as HTMLElement;\nconst cardEl = document.getElementById(\"card\") as HTMLElement;\nconst errorMessage = document.getElementById(\"error-message\") as HTMLParagraphElement;\nconst cityInput = document.getElementById(\"city-input\") as HTMLInputElement;\nconst searchBtn = document.getElementById(\"search-btn\") as HTMLButtonElement;\n\/\/ ...remaining detail-grid element refs (temperature, humidity, wind, pressure, etc.)\n\ntype WeatherStructured = {\n  city: string;\n  country: string;\n  category: \"sunny\" | \"cloudy\" | \"rain\" | \"snow\";\n  condition: string;\n  temperature: number;\n  humidity: number;\n  windSpeed: number;\n  pressure: number;\n  visibility: number;\n  uvIndex: number;\n  lastUpdated: string;\n};\n\n\/\/ Default\/reset state - shown from first paint and reapplied before any re-fetch, so a\n\/\/ request in flight always looks like \"loading\", never like stale or unrelated data.\nfunction setLoadingState() {\n  errorMessage.hidden = true;\n  cardEl.hidden = false;\n  cardEl.dataset.state = \"loading\";\n  mainEl.dataset.category = \"loading\";\n}\n\nfunction renderWeather(structured: WeatherStructured) {\n  errorMessage.hidden = true;\n  cardEl.hidden = false;\n  mainEl.dataset.category = structured.category; \/\/ CSS themes sun\/cloud\/rain\/snow off this\n  \/\/ ...populate temperature\/condition\/humidity\/wind\/pressure\/visibility\/uv text content\n  cardEl.dataset.state = \"ready\"; \/\/ flips the loading skeleton off\n}\n\nfunction showError(message: string) {\n  cardEl.hidden = true;\n  errorMessage.textContent = message;\n  errorMessage.hidden = false;\n}\n\nfunction applyToolResult(result: CallToolResult) {\n  if (result.isError) {\n    const content = result.content ?? [];\n    const textItem = content.find((c): c is { type: \"text\"; text: string } => c.type === \"text\");\n    showError(textItem?.text ?? \"An error occurred.\");\n    return;\n  }\n  const structured = result.structuredContent as WeatherStructured | undefined;\n  if (structured) renderWeather(structured);\n}\n\nfunction handleHostContextChanged(ctx: McpUiHostContext) {\n  if (ctx.theme) applyDocumentTheme(ctx.theme);\n  if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables);\n  if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);\n}\n\nconst app = new App({ name: \"Weather App\", version: \"1.0.0\" });\n\napp.onteardown = async () => ({});\napp.ontoolinput = () => setLoadingState();\napp.ontoolresult = applyToolResult;\napp.onerror = console.error;\napp.onhostcontextchanged = handleHostContextChanged;\n\nasync function searchCity() {\n  const city = cityInput.value.trim();\n  if (!city) return;\n  setLoadingState();\n  try {\n    const result = await app.callServerTool({ name: \"weather\", arguments: { city } });\n    applyToolResult(result);\n  } catch (e) {\n    showError(e instanceof Error ? e.message : \"Weather request failed.\");\n  }\n}\n\nsearchBtn.addEventListener(\"click\", () => void searchCity());\ncityInput.addEventListener(\"keydown\", (e) => { if (e.key === \"Enter\") searchBtn.click(); });\n\n\/\/ Connect to the host - triggers the initial tool invocation\napp.connect().then(() => {\n  const ctx = app.getHostContext();\n  if (ctx) handleHostContextChanged(ctx);\n});<\/code><\/pre>\n\n\n\n
\n\n\n\n
How the UI talks to the server<\/h3>\n\n\n\n
\"\"\/<\/figure>\n\n\n\n
callServerTool<\/code> is for UI actions that should re-run a tool without involving the agent. sendMessage<\/code> becomes useful once your Agentic App has more than one view and needs the agent to navigate between them.<\/p>\n\n\n\n
\n\n\n\n
6. Register the Tool on the Server<\/h3>\n\n\n\n
In actions\/mcp-server\/tools.js<\/code>, the weather<\/code> tool from Part 1 gets a _meta.ui.resourceUri<\/code> link and an outputSchema:<\/code><\/p>\n\n\n\n
const fs = require('fs\/promises')\nconst path = require('path')\nconst { z } = require('zod')\n\n\/\/ Adobe I\/O Runtime only deploys the bundled index.js - no sibling static\/ files - so the\n\/\/ weather UI must ride inside the bundle as a required JS string (see scripts\/embed-ui.js,\n\/\/ run via `npm run embed:ui` as part of `npm run build`). Falls back to reading\n\/\/ actions\/mcp-server\/static\/ on disk for local dev when the embed step hasn't run yet.\nlet embeddedUi = null\ntry {\n  embeddedUi = require('.\/embedded-ui.js')\n} catch {\n  \/\/ Local dev without embed step\n}\nasync function loadUiHtml(filePath, embeddedKey) {\n  const embedded = embeddedUi?.[embeddedKey]\n  if (typeof embedded === 'string' && embedded.length > 0) return embedded\n  return fs.readFile(filePath, 'utf-8')\n}\nconst WEATHER_RESOURCE_URI = 'ui:\/\/weather\/mcp-app.html'\nconst WEATHER_RESOURCE_MIME_TYPE = 'text\/html;profile=mcp-app'\nfunction registerTools(server) {\n  \/\/ ...echo and calculator tools from Part 1 stay as-is...\n  server.registerTool(\n    'weather',\n    {\n      title: 'Weather',\n      description: 'Get current weather information for any city.',\n      inputSchema: {\n        city: z.string().describe('Name of the city to get weather for (e.g., \"London\")')\n      },\n      outputSchema: {\n        city: z.string(),\n        country: z.string(),\n        category: z.enum(['sunny', 'cloudy', 'rain', 'snow']),\n        condition: z.string(),\n        temperature: z.number(),\n        humidity: z.number(),\n        windSpeed: z.number(),\n        pressure: z.number(),\n        visibility: z.number(),\n        uvIndex: z.number(),\n        lastUpdated: z.string()\n      },\n      \/\/ Links this tool's result to the weather app-ui resource registered below.\n      \/\/ Both keys point at the same URI - `ui\/resourceUri` is kept for hosts that\n      \/\/ haven't picked up the nested `ui.resourceUri` shape yet.\n      _meta: {\n        ui: { resourceUri: WEATHER_RESOURCE_URI },\n        'ui\/resourceUri': WEATHER_RESOURCE_URI\n      }\n    },\n    async ({ city = 'Unknown City' }) => {\n      \/\/ CUSTOMIZE: replace with a real weather API call. This generates mock data -\n      \/\/ a category (sunny\/cloudy\/rain\/snow, weighted so sun\/clouds are most common)\n      \/\/ and a plausible temperature\/humidity\/wind\/etc. within that category's range.\n      const structuredContent = generateMockWeather(city)\n      return {\n        content: [{ type: 'text', text: `Weather for ${city}: ${structuredContent.condition}, ${structuredContent.temperature}\u00b0C` }],\n        structuredContent\n      }\n    }\n  )\n}<\/code><\/pre>\n\n\n\n
The critical part is _meta.ui.resourceUri<\/code>. Without it, the host returns text only – no UI panel.<\/p>\n\n\n\n
Return both:<\/p>\n\n\n\n