#Existing applications

#Requirements and defaults

In integrated mode, Modern.js provides both the MCP endpoint and card builds. The following requirements apply:

mcp_apps.ts is a default filename, not a fixed requirement. For example, mcpAppsPlugin({ configPath: 'mcp/server.ts', endpoint: '/api/mcp' }) reads mcp/server.ts relative to the project root and mounts the endpoint at /api/mcp.

When Modern.js only builds the UI and a user-managed server provides MCP, use mode: 'ui-only'. This mode does not require bffPlugin(), but still needs a UI definition file. See User-managed MCP servers and the full options in the API reference.

#Installation and configuration

Install @modern-js/mcp-apps and @modern-js/plugin-mcp-apps in production dependencies, matching the installed app-tools version. Also install @modern-js/plugin-bff.

import { appTools, defineConfig } from '@modern-js/app-tools';
import { bffPlugin } from '@modern-js/plugin-bff';
import { mcpAppsPlugin } from '@modern-js/plugin-mcp-apps';

export default defineConfig({
  plugins: [appTools(), bffPlugin(), mcpAppsPlugin()],
});

import { defineMcpServer } from '@modern-js/mcp-apps/config';
import { withViewProps } from '@modern-js/mcp-apps/server'

export default defineMcpServer({
  name: 'greeting-server',
  version: '1.0.0',
  tools: [
    {
      name: 'greet',
      description: 'Greet someone.',
      inputSchema: {
        name: { type: 'string', minLength: 1 },
      },
      annotations: { readOnlyHint: true },
      handler: async ({ name }) => {
        const message = `Hello, ${name}!`;
        return withViewProps({
          content: [{ type: 'text', text: message }],
          structuredContent: { message },
        })
      },
    },
  ],
});

Include the definition and handler directory in tsconfig. Run modern dev and connect an MCP client to /mcp. A browser address-bar GET returns 405 because the current transport is stateless HTTP POST.

#Application component views

A view references a component with view: { module: './src/components/Greeting.tsx' } and can omit remotes.

The plugin registers standard Modern.js auto-mounted entries, inheriting the application build, CSS processing, aliases, preEntry and runtime plugins. Resource HTML references ordinary application JS/CSS/chunks. Deploy those assets alongside the server or configure dev/output assetPrefix for a CDN. Existing filesystem route layouts and loaders are not implicitly attached to a component entry.

#Interactive remote views

Publish an expose with existing MF tooling. Add its manifest URL to remotes and reference it from a tool with remote and view.module:

remotes: [
  {
    name: 'catalog',
    baseUrl: 'https://cdn.example.com/catalog/v1/mf-manifest.json',
    csp: {
      resourceDomains: ['https://cdn.example.com'],
      connectDomains: ['https://cdn.example.com'],
    },
  },
];
// Corresponding tool: remote: 'catalog', view: { module: './Results' }

The MF renderer loads the component inside the host iframe and passes tool arguments, handler viewProps, and the connected mcpApp. Use mcpApp.callServerTool() for interactions; do not create a second useApp connection. No additional UI-manifest format is introduced.

Keep the existing bff.prefix. The automatic MCP route uses endpoint directly, without adding the BFF prefix:

mcpAppsPlugin({ configPath: 'mcp_apps.ts', endpoint: '/api/mcp' });

The defaults are root mcp_apps.ts and /mcp. An existing BFF route at the same path causes a conflict error.

#Keep a manual entry

For custom endpoint options or an existing manual route, set mcpAppsPlugin({ endpoint: false }), then add:

import { mcpServer } from '@modern-js/plugin-mcp-apps/bff';
import definition from '../../mcp_apps';

export const { POST, GET, DELETE, PUT, PATCH, OPTIONS } = mcpServer(definition);

This manual route follows the BFF prefix: bff.prefix: '/api' produces /api/mcp. Definition name and version provide server identity; mcpServer can override it with serverInfo.