For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /guides/advanced-features/mcp-apps/index.md.
  • English

      • Overview

      What are MCP Apps?

      MCP (Model Context Protocol) lets AI applications call tools and access data through a shared protocol. MCP Apps adds interactive interfaces: a tool can associate its result with a UI that a compatible AI host displays in the conversation. The “host” is the client where users interact with AI; this guide calls the embedded UI a “card.”

      For example, a sales query tool could display a chart with filters. When the user changes a filter, the card calls a tool through the host to retrieve new data. Forms and result lists can similarly let users act directly on an interface instead of describing each input and result across multiple messages.

      Cards require a host that supports MCP Apps; an ordinary MCP client may not render them. See the official MCP Apps overview for the protocol and host connection model.

      What does Modern.js provide?

      Modern.js integrates MCP tools and React cards into the application development workflow. Write business functions and React components, connect them through mcp_apps.ts, and use the familiar development, build, and deployment commands.

      • Project creation: CLI templates for MCP Apps with UI and MCP servers without UI, with optional Module Federation (MF).
      • Server integration: A BFF MCP endpoint with TypeScript compilation, dependency tracking, and hot reload. The core package handles MCP tool calls and UI resource responses.
      • React UI integration: Build components within the application as card entries or load remote components through MF. The renderer connects to the host and passes tool arguments, result props, and mcpApp to the card.
      • Build and deployment: Develop and deploy the application and MCP server together, or publish UI assets and server code separately.

      This feature is experimental and does not include an AI chat host or DevTools. Connect to your target host to verify card rendering and interactions.

      Supported project types

      The Modern.js CLI provides two templates: mcp-apps and mcp-server. The mcp-apps template supports application React components and MF remote components, giving you the following three project options.

      MCP Apps: application React components

      The mcp-apps template includes an MCP server and React cards. Component source lives in the project and is compiled by the Modern.js application builder. Tools reference component files through view.module, so business tools and cards are developed and maintained within the same application.

      MCP Apps: MF remote components

      Adding --mf to the mcp-apps template exposes and loads React cards through Module Federation. The template includes component source and MF configuration, producing a manifest and component assets at build time. Tools reference components through remote and expose names, and can also use existing MF remote components.

      MCP Server: tools only

      The mcp-server template includes tool definitions, business functions, and an MCP endpoint, without card UI. Clients call tools through MCP to retrieve data or perform tasks.

      Choose a project type

      First decide whether users need an interface inside the AI conversation. Choose MCP Server for tools that only return data or perform tasks. Choose MCP Apps for forms, charts, or interactive cards. If you need UI, select the default or MF mode based on how you maintain and publish components.

      Project typeWhen to choose itCLI arguments
      MCP Apps: application React components (recommended starting point)Building new UI maintained within this application, without remote component reuse requirements--template mcp-apps
      MCP Apps: MF remote componentsReusing existing MF components or sharing versioned remote components across applications--template mcp-apps --mf
      MCP Server: tools onlyProviding tools such as queries and calculations without embedded UI--template mcp-server

      Application components versus MF remote components

      AspectApplication React componentsMF remote components
      UI definitionview.module points to a project component file, such as ./src/components/Greeting.tsxremote selects a remote, and view.module names an expose such as ./Greeting
      Build and loadingModern.js generates card HTML and application JS/CSS that the host loadsMF produces a manifest, remote entry, and chunks; the card renderer loads components through that manifest
      Component maintenanceComponents are built and maintained with the applicationComponents can be independently published and reused as remote modules; the starter still includes their source in the same project
      Configuration to maintainComponent paths and application asset URLsAdditional exposes, manifest URLs, shared dependencies, and asset origins

      Start with application React components unless you have a specific MF reuse requirement. Both UI modes support production deployment, CDN asset hosting, and separate UI and server releases. Choose MF when you need remote component reuse and independent version management.

      In this guide