{"id":275,"date":"2026-07-16T17:05:46","date_gmt":"2026-07-16T17:05:46","guid":{"rendered":"https:\/\/subashselvaraj.com\/?p=275"},"modified":"2026-07-16T17:06:33","modified_gmt":"2026-07-16T17:06:33","slug":"agentic-apps-using-app-builder-and-mcp","status":"publish","type":"post","link":"https:\/\/subashselvaraj.com\/index.php\/2026\/07\/16\/agentic-apps-using-app-builder-and-mcp\/","title":{"rendered":"Agentic Apps Using App Builder and MCP – Part 1"},"content":{"rendered":"\n

Getting started and creating your project \u2014 the foundations for building interactive AI experiences with Adobe App Builder and the Model Context Protocol.<\/p>\n\n\n\n

Introduction<\/h2>\n\n\n\n

AI assistants are moving beyond text-only chat. Users increasingly expect rich, interactive experiences \u2014 product carousels, detail views, carts, dashboards \u2014 rendered directly inside the conversation. Agentic Apps<\/strong> (built on the MCP Apps extension<\/a>) deliver exactly that: MCP tools paired with interactive HTML UIs that run inside compatible hosts like Cursor and Claude Desktop.<\/p>\n\n\n\n

In this series, we’ll build Agentic Apps on Adobe App Builder<\/strong>, deploying MCP servers to Adobe I\/O Runtime<\/strong> \u2014 Adobe’s serverless platform with enterprise auth, auto-scaling, and one-command deploys.<\/p>\n\n\n\n

Part 1<\/strong> covers the foundations, walks you through creating your App Builder project, deploys the scaffolded MCP server to I\/O Runtime, and connects it to an MCP host for verification. Later parts will cover building the Agentic App UI and extending tools and resources.<\/p>\n\n\n\n

\n\n\n\n

What Is an Agentic App?<\/h2>\n\n\n\n

A standard MCP server exposes tools<\/strong> (callable functions), resources<\/strong> (static content), and prompts<\/strong> (reusable templates). An Agentic App<\/strong> (MCP App) adds a third layer: an interactive UI.<\/p>\n\n\n\n

Every Agentic App has three linked pieces:<\/p>\n\n\n

\n
\"\"
The three linked pieces of an Agentic App \u2014 and how a request flows between them.<\/figcaption><\/figure><\/div>\n\n\n
    \n
  1. Tool<\/strong> \u2014 Called by the LLM or host; fetches data and returns structured results.<\/li>\n\n\n\n
  2. Resource<\/strong> \u2014 Serves bundled HTML (text\/html;profile=mcp-app<\/code>) that renders the UI.<\/li>\n\n\n\n
  3. Link<\/strong> \u2014 The tool’s _meta.ui.resourceUri<\/code> points at the resource URI.<\/li>\n<\/ol>\n\n\n\n

    When a user asks “Show me products matching vanilla candle”<\/em>, the host invokes your tool, receives product data, and renders your HTML UI inside the conversation \u2014 complete with images, filters, and click actions.<\/p>\n\n\n\n

    \n\n\n\n

    Why App Builder for Agentic Apps?<\/h2>\n\n\n\n

    Running MCP servers locally works for prototyping, but production Agentic Apps need:<\/p>\n\n\n\n

    Requirement<\/th>App Builder delivers<\/th><\/tr><\/thead>
    Serverless hosting<\/strong><\/td>Adobe I\/O Runtime with auto-scaling<\/td><\/tr>
    Secure credentials<\/strong><\/td>Encrypted env vars \u2014 no API keys in client configs<\/td><\/tr>
    Enterprise auth<\/strong><\/td>IMS token validation and API key support built in<\/td><\/tr>
    One-command deploy<\/strong><\/td>aio app deploy<\/code> ships to production<\/td><\/tr>
    Official MCP SDK<\/strong><\/td>@modelcontextprotocol\/sdk<\/code> + @modelcontextprotocol\/ext-apps<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    Adobe also provides an official App Builder template \u2014 @ad<\/code>obe\/generator-app-remote-mcp-server-generic \u2014 that scaffolds a production-ready MCP server with tools, resources, prompts, authentication, and Streamable HTTP transport.<\/p>\n\n\n\n

    \n\n\n\n

    Architecture at a Glance<\/h2>\n\n\n
    \n
    \"\"
    The MCP server runs as a stateless web action on I\/O Runtime; the host renders its bundled HTML as an MCP resource.
    <\/figcaption><\/figure><\/div>\n\n\n

    The MCP server runs as a web action<\/strong> on I\/O Runtime. Each request creates a fresh, stateless server instance \u2014 ideal for serverless. The bundled HTML is served as an MCP resource and rendered by the host.<\/p>\n\n\n\n

    \n\n\n\n

    Prerequisites<\/h2>\n\n\n\n

    Before creating your project, ensure you have:<\/p>\n\n\n\n

    Requirement<\/th>Details<\/th><\/tr><\/thead>
    Node.js<\/strong><\/td>Version 18.19 or later<\/td><\/tr>
    Adobe I\/O CLI<\/strong><\/td>App Builder command-line tool (aio<\/code>)<\/td><\/tr>
    Adobe Developer Console account<\/strong><\/td>developer.adobe.com\/console<\/a><\/td><\/tr>
    I\/O Runtime enabled<\/strong><\/td>A Developer Console project with Runtime added<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    \n\n\n\n

    1<\/strong>. Create an Adobe Developer Console Project<\/h2>\n\n\n\n
      \n
    1. Go to the Adobe Developer Console<\/a>.<\/li>\n\n\n\n
    2. Click Create new project<\/strong> \u2192 Create an empty project<\/strong>.<\/li>\n\n\n\n
    3. Name your project (e.g. my-agentic-app<\/code>).<\/li>\n\n\n\n
    4. Click Add API<\/strong> \u2192 select I\/O Runtime<\/strong> \u2192 Next<\/strong> \u2192 Save configured API<\/strong>.<\/li>\n\n\n\n
    5. Add a Workspace<\/strong> (e.g. Development<\/code>) if prompted.<\/li>\n<\/ol>\n\n\n\n

      Your project now has a serverless runtime namespace where MCP actions will deploy.<\/p>\n\n\n\n

      \n\n\n\n

      2<\/strong>. Install the Adobe I\/O CLI<\/h2>\n\n\n\n

      Install the CLI globally:<\/p>\n\n\n\n

      npm install -g @adobe\/aio-cli<\/code><\/pre>\n\n\n\n
      Verify the installation:<\/p>\n\n\n\n
      aio --version<\/code><\/pre>\n\n\n\n
      Log in to your Adobe account:<\/p>\n\n\n\n
      aio login<\/code><\/pre>\n\n\n\n
      This opens a browser for IMS authentication and links the CLI to your Developer Console projects.<\/p>\n\n\n\n
      \n\n\n\n
      3. Generate Your MCP Server Project<\/h2>\n\n\n\n
      Initialize a new App Builder project:<\/p>\n\n\n\n
      aio app init<\/code><\/pre>\n\n\n\n
      The CLI walks you through interactive prompts:<\/p>\n\n\n\n
        \n
      1. Select a project<\/strong> \u2014 Choose the Developer Console project you created in Step 1.<\/li>\n\n\n\n
      2. Select a workspace<\/strong> \u2014 Choose Development<\/code> (or your workspace name).<\/li>\n\n\n\n
      3. Select a template<\/strong> \u2014 Choose @adobe\/generator-app-remote-mcp-server-generic<\/code><\/strong> (Remote MCP Server).<\/li>\n\n\n\n
      4. Project folder name<\/strong> \u2014 e.g. my-agentic-app<\/code>.<\/li>\n\n\n\n
      5. App name<\/strong> \u2014 A display name for your application.<\/li>\n<\/ol>\n\n\n\n
        When complete, the CLI downloads the workspace configuration and scaffolds the project.<\/p>\n\n\n\n
        Alternatively, pass the folder name directly:<\/p>\n\n\n\n
        aio app init my-agentic-app<\/code><\/pre>\n\n\n\n
        \n\n\n\n
        What Gets Generated<\/h2>\n\n\n\n
        After aio app init<\/code>, your project directory looks like this:<\/p>\n\n\n\n
        my-agentic-app\/\n\u251c\u2500\u2500 actions\/\n\u2502   \u2514\u2500\u2500 mcp-server\/\n\u2502       \u251c\u2500\u2500 index.js          # Main MCP server action (entry point)<\/em>\n\u2502       \u251c\u2500\u2500 tools.js          # Tool, resource, and prompt registrations<\/em>\n\u2502       \u2514\u2500\u2500 validator.js      # IMS \/ API key authentication<\/em>\n\u251c\u2500\u2500 test\/                     # Jest test suite<\/em>\n\u251c\u2500\u2500 app.config.yaml           # I\/O Runtime deployment configuration<\/em>\n\u251c\u2500\u2500 package.json              # Dependencies (MCP SDK, Zod, aio-sdk)<\/em>\n\u251c\u2500\u2500 webpack.config.js         # Build configuration for the action bundle<\/em>\n\u251c\u2500\u2500 jest.config.js            # Test configuration<\/em>\n\u251c\u2500\u2500 .env.example              # Environment variable template<\/em>\n\u2514\u2500\u2500 .aio                      # Workspace config (gitignored)<\/em><\/code><\/pre>\n\n\n\n
        Key files to know<\/h3>\n\n\n\n
        app.config.yaml<\/code><\/strong> \u2014 Defines how your MCP server deploys to I\/O Runtime:<\/p>\n\n\n\n
        application:\n  actions: actions\n  runtimeManifest:\n    packages:\n      my-agentic-app:\n        actions:\n          mcp-server:\n            function: actions\/mcp-server\/index.js\n            web: 'yes'\n            runtime: 'nodejs:20'\n            annotations:\n              raw-http: true        # Required for MCP Streamable HTTP<\/em>\n              web-export: true<\/code><\/pre>\n\n\n\n
        actions\/mcp-server\/tools.js<\/code><\/strong> \u2014 Where you register MCP capabilities. The template ships with sample tools (echo, calculator, weather), resources, and prompts.<\/p>\n\n\n\n
        actions\/mcp-server\/index.js<\/code><\/strong> \u2014 The I\/O Runtime action entry point. It creates a stateless MCP server per request using Streamable HTTP transport.<\/p>\n\n\n\n
        package.json<\/code><\/strong> \u2014 Core dependencies:<\/p>\n\n\n\n
        {\n  \"dependencies\": {\n    \"@adobe\/aio-sdk\": \"^5.0.0\",\n    \"@modelcontextprotocol\/sdk\": \"^1.24.0\",\n    \"zod\": \"^3.23.8\"\n  }\n}<\/code><\/pre>\n\n\n\n
        Built-in capabilities (out of the box)<\/h3>\n\n\n\n
        The generated template includes working examples:<\/p>\n\n\n\n
        Capability<\/th>Name<\/th>Purpose<\/th><\/tr><\/thead>
        Tool<\/strong><\/td>echo<\/code><\/td>Test connectivity \u2014 echoes a message back<\/td><\/tr>
        Tool<\/strong><\/td>calculator<\/code><\/td>Evaluate math expressions<\/td><\/tr>
        Tool<\/strong><\/td>weather<\/code><\/td>Mock weather API (pattern for external integrations)<\/td><\/tr>
        Resource<\/strong><\/td>example:\/\/text<\/code><\/td>Static text content<\/td><\/tr>
        Resource<\/strong><\/td>example:\/\/docs<\/code><\/td>Markdown documentation<\/td><\/tr>
        Prompt<\/strong><\/td>weather-info<\/code><\/td>Reusable weather prompt template<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
        These are starting points you’ll replace or extend when building Agentic Apps.<\/p>\n\n\n\n
        \n\n\n\n
        Connect Your Workspace<\/h2>\n\n\n\n
        After generation, link the project to your Developer Console workspace (if not done automatically during init<\/code>):<\/p>\n\n\n\n
        cd my-agentic-app\naio app use<\/code><\/pre>\n\n\n\n
        Select your project and workspace. This writes a .env<\/code> file with runtime credentials (AIO_RUNTIME_NAMESPACE<\/code>, AIO_RUNTIME_AUTH<\/code>, etc.).<\/p>\n\n\n\n
        Install dependencies:<\/p>\n\n\n\n
        npm install<\/code><\/pre>\n\n\n\n
        At this point you have a fully scaffolded MCP server project, connected to your Adobe I\/O Runtime workspace, ready to deploy.<\/p>\n\n\n\n
        \n\n\n\n
        4<\/strong>. Deploy to Adobe I\/O Runtime<\/h2>\n\n\n\n
        The generated template includes a webpack build and deploy script. From your project directory:<\/p>\n\n\n\n
        npm run deploy<\/code><\/pre>\n\n\n\n
        This runs two steps:<\/p>\n\n\n\n
          \n
        1. Build<\/strong> \u2014 Webpack bundles actions\/mcp-server\/index.js<\/code> into dist\/<\/code> for I\/O Runtime<\/li>\n\n\n\n
        2. Deploy<\/strong> \u2014 aio app deploy<\/code> uploads the bundle and applies app.config.yaml<\/code><\/li>\n<\/ol>\n\n\n\n
          When deploy completes, the CLI prints your web action URLs. Note the URL for the mcp-server<\/code> action \u2014 you will need it for host configuration.<\/p>\n\n\n\n
          Deployed URL format<\/h3>\n\n\n\n
          I\/O Runtime web actions follow this pattern:<\/p>\n\n\n\n
          https://<namespace>.adobeioruntime.net\/api\/v1\/web\/<package-name>\/mcp-server<\/code><\/pre>\n\n\n\n
          Segment<\/th>Source<\/th><\/tr><\/thead>
          <namespace><\/code><\/td>Your I\/O Runtime namespace (from .env<\/code>, set by aio app use<\/code>)<\/td><\/tr>
          <package-name><\/code><\/td>The package key in app.config.yaml<\/code> (e.g. my-agentic-app<\/code>)<\/td><\/tr>
          mcp-server<\/code><\/td>The action name in app.config.yaml<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
          Example<\/p>\n\n\n\n
          https://123456-myproject-dev.adobeioruntime.net\/api\/v1\/web\/my-agentic-app\/mcp-server<\/code><\/pre>\n\n\n\n
          You can also list deployed actions at any time:<\/p>\n\n\n\n
          aio runtime action list<\/code><\/pre>\n\n\n\n
          \n\n\n\n
          5<\/strong>. Verify the Deployment<\/h2>\n\n\n\n
          Confirm the server is reachable before connecting an MCP host.<\/p>\n\n\n\n
          Health check (GET)<\/h3>\n\n\n\n
          The template responds to GET<\/code> requests with a JSON health payload:<\/p>\n\n\n\n
          curl https:\/\/<namespace>.adobeioruntime.net\/api\/v1\/web\/<package-name>\/mcp-server<\/code><\/pre>\n\n\n\n
          Expected response:<\/p>\n\n\n\n
          {\n  \"status\": \"healthy\",\n  \"server\": \"my-agentic-app\",\n  \"version\": \"1.0.0\",\n  \"transport\": \"StreamableHTTP\",\n  \"sdk\": \"@modelcontextprotocol\/sdk\",\n  \"timestamp\": \"2026-07-16T12:00:00.000Z\"\n}<\/code><\/pre>\n\n\n\n
          A 200<\/code> response with \"status\": \"healthy\"<\/code> confirms the action is deployed and responding.<\/p>\n\n\n\n
          Run the test suite<\/h3>\n\n\n\n
          The template includes Jest tests for health checks, CORS, and MCP protocol handling:<\/p>\n\n\n\n
          npm test<\/code><\/pre>\n\n\n\n
          Tests exercise the action locally by calling main()<\/code> with simulated I\/O Runtime parameters \u2014 no deploy required, but passing tests is a good signal before you connect a host.<\/p>\n\n\n\n
          MCP protocol check (optional)<\/h3>\n\n\n\n
          Send an MCP initialize<\/code> request directly to the deployed endpoint:<\/p>\n\n\n\n
          curl -X POST \\\n  https:\/\/<namespace>.adobeioruntime.net\/api\/v1\/web\/<package-name>\/mcp-server \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 1,\n    \"method\": \"initialize\",\n    \"params\": {\n      \"protocolVersion\": \"2024-11-05\",\n      \"capabilities\": {},\n      \"clientInfo\": { \"name\": \"curl-test\", \"version\": \"1.0.0\" }\n    }\n  }'<\/code><\/pre>\n\n\n\n
          A successful response includes \"protocolVersion\": \"2024-11-05\"<\/code> and serverInfo<\/code> in the result.<\/p>\n\n\n\n
          List the built-in tools:<\/p>\n\n\n\n
          curl -X POST \\\n  https:\/\/<namespace>.adobeioruntime.net\/api\/v1\/web\/<package-name>\/mcp-server \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 2,\n    \"method\": \"tools\/list\",\n    \"params\": {}\n  }'<\/code><\/pre>\n\n\n\n
          You should see echo<\/code>, calculator<\/code>, and weather<\/code> in the tool list.<\/p>\n\n\n\n
          \n\n\n\n
          6<\/strong> Configure Your MCP Host<\/h2>\n\n\n\n
          Connect Cursor or Claude Desktop to your deployed server using Streamable HTTP<\/strong> transport.<\/p>\n\n\n\n
          Replace <namespace><\/code> and <package-name><\/code> with your own values. For initial testing, leave authentication disabled in .env<\/code> (both AUTH_VALIDATE_IMS<\/code> and SERVICE_API_KEY<\/code> unset). See Part 2 for securing the server before production.<\/p>\n\n\n\n
          Cursor<\/h3>\n\n\n\n
          Open Cursor Settings \u2192 MCP<\/strong> (or edit your MCP config file) and add:<\/p>\n\n\n\n
          {\n  \"mcpServers\": {\n    \"my-mcp-server\": {\n      \"url\": \"https:\/\/<namespace>.adobeioruntime.net\/api\/v1\/web\/<package-name>\/mcp-server\",\n      \"type\": \"streamable-http\"\n    }\n  }\n}<\/code><\/pre>\n\n\n\n
          Restart Cursor after saving. The server should appear in the MCP panel with a green connected status.<\/p>\n\n\n\n
          Test prompt<\/p>\n\n\n\n
          \n
          What’s the weather in Noida right now?<\/p>\n<\/blockquote>\n\n\n\n
          Or something that exercises the echo tool:<\/p>\n\n\n\n
          \n
          Repeat this back to me: “Hello from App Builder”.<\/p>\n<\/blockquote>\n\n\n\n
          Claude Desktop<\/h3>\n\n\n\n
          Claude Desktop uses stdio by default, so route Streamable HTTP through mcp-remote<\/code>. Add to your Claude Desktop MCP config (claude_desktop_config.json<\/code>):<\/p>\n\n\n\n
          {\n  \"mcpServers\": {\n    \"my-mcp-server\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"https:\/\/<namespace>.adobeioruntime.net\/api\/v1\/web\/<package-name>\/mcp-server\"\n      ]\n    }\n  }\n}<\/code><\/pre>\n\n\n\n
          Restart Claude Desktop, then try:<\/p>\n\n\n\n
          \n
          What’s the weather like in London?<\/p>\n<\/blockquote>\n\n\n\n
          Troubleshooting host connections<\/h3>\n\n\n\n
          Symptom<\/th>Likely cause<\/th>Fix<\/th><\/tr><\/thead>
          Host shows disconnected<\/td>Wrong URL or namespace<\/td>Confirm URL from aio app deploy<\/code> output or aio runtime action list<\/code><\/td><\/tr>
          Health check works, host fails<\/td>Missing type: streamable-http<\/code> in Cursor<\/td>Add the transport type explicitly<\/td><\/tr>
          Claude Desktop cannot connect<\/td>Direct URL without mcp-remote<\/code><\/td>Use the npx mcp-remote<\/code> wrapper shown above<\/td><\/tr>
          CORS errors in browser clients<\/td>Preflight blocked<\/td>Template handles OPTIONS<\/code>; verify raw-http: true<\/code> in app.config.yaml<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
          \n\n\n\n
          What’s Next \u2014 Part 2 Preview<\/h2>\n\n\n\n
          In Part 2<\/strong>, we’ll transform this deployed MCP server into a full Agentic App:<\/p>\n\n\n\n