Module Federation MCP Server

MCP Server for rendering Module Federation components as MCP Apps with interactive UIs.

Features

• ✅ Fully compliant with MCP Apps standard
• ✅ Dynamic tool registration from configuration
• ✅ CORS proxy for CDN resources
• ✅ Protocol-relative URL handling
• ✅ CSP configuration support
• ✅ AI-friendly Skills for configuration management

Architecture

┌─────────────────┐
│   Claude AI     │
└────────┬────────┘
         │ MCP Protocol
         ▼
┌─────────────────────┐
│  MF MCP Server      │
│  - Load config      │
│  - Register tools   │
│  - Generate URLs    │
└────────┬────────────┘
         │ Returns URL
         ▼
┌──────────────────────┐
│ mf_render_container  │ (iframe src)
│  - Load MF modules   │
│  - Render components │
└──────────────────────┘

Requirements

• Node.js 18+
• Claude Desktop

Try the Demo

The repo includes a ready-to-run Module Federation provider with a Deploy Wizard demo.

cd module-federation-examples/basic
pnpm install
pnpm run dev
# Runs on http://localhost:8080

Then register the MCP server with Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json:

Option 1: Using npx (recommended, once published)

{
  "mcpServers": {
    "module-federation": {
      "command": "npx",
      "args": [
        "-y",
        "@module-federation/mcp-server@latest",
        "--config",
        "/absolute/path/to/module-federation-mcp/module-federation-examples/basic/mcp_apps.json",
        "--stdio"
      ]
    }
  }
}

Option 2: Run from a local build

# In the module-federation-mcp directory
pnpm install && pnpm run build

{
  "mcpServers": {
    "module-federation": {
      "command": "/absolute/path/to/node",
      "args": [
        "/absolute/path/to/module-federation-mcp/dist/index.js",
        "--config",
        "/absolute/path/to/module-federation-mcp/module-federation-examples/basic/mcp_apps.json",
        "--stdio"
      ]
    }
  }
}

Replace /absolute/path/to/... with the actual absolute path on your machine. Restart Claude Desktop, then type:

Start a deployment

Claude will open the Deploy Wizard — a 3-step interactive UI running inside the chat.

Use with Your Own Project

1. Create mcp_apps.json

Create a config file for your project (see Configuration Reference below), or use the AI Skill to generate it automatically.

2. Configure with AI Assistance (optional)

Use the included Skill to set up your configuration. The skill will automatically detect if your project is a Module Federation project and parse the configuration:

For Module Federation Projects:

You: Set up MCP for my MF project
AI: ✅ Detected module-federation.config.ts
    📦 Found package: @scope/your-package
    🔧 Found 3 exposed components
    [Asks for: version, CDN URL, locale]
    [Automatically generates tools from exposes]

Supported Config Files:

• module-federation.config.ts
• rspack.config.js / webpack.config.js (with ModuleFederationPlugin)

For Non-MF Projects:

You: Add MF tools to MCP
AI: ℹ️ Not a Module Federation project
    [Asks for: package name, version, CDN URL, components manually]

Or manually create mcp_apps.json:

{
  "remotes": [
    {
      "name": "@scope/package",
      "version": "1.0.0",
      "baseUrl": "https://cdn.example.com/path",
      "locale": "en",
      "csp": {
        "connectDomains": ["cdn.example.com"],
        "resourceDomains": ["cdn.example.com"]
      }
    }
  ],
  "tools": [
    {
      "name": "my_tool",
      "title": "My Tool",
      "description": "Tool description",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "required": []
      },
      "remote": "@scope/package",
      "module": "./ComponentName",
      "exportName": "default"
    }
  ]
}

3. Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

Option 1: Using npx (recommended, once published)

{
  "mcpServers": {
    "module-federation": {
      "command": "npx",
      "args": [
        "-y",
        "@module-federation/mcp-server@latest",
        "--config",
        "/absolute/path/to/mcp_apps.json",
        "--stdio"
      ]
    }
  }
}

Option 2: Run from a local build

# In the module-federation-mcp directory
pnpm install && pnpm run build

{
  "mcpServers": {
    "module-federation": {
      "command": "/absolute/path/to/node",
      "args": [
        "/absolute/path/to/module-federation-mcp/dist/index.js",
        "--config",
        "/absolute/path/to/mcp_apps.json",
        "--stdio"
      ]
    }
  }
}

4. Restart Claude Desktop

Your tools are now available!

AI Skills

This package includes an Agent Skill for configuration management with automatic MF project detection.

The agent will:

• Auto-detect MF config files (module-federation.config.ts)
• Parse exposes and generate tool configs automatically
• Ask for CDN URL, version, locale
• Create complete mcp_apps.json
• Generate Claude Desktop config snippet

See docs/aiden/skill.mdx for the skill definition.

Configuration Reference

Remote Configuration

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | ✅ | Package name | | version | string | ✅ | Package version | | baseUrl | string | ✅ | CDN base URL | | locale | string | ❌ | Locale (default: 'en') | | csp | object | ❌ | CSP configuration |

Tool Configuration

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | ✅ | Tool identifier | | title | string | ❌ | Display name | | description | string | ❌ | Tool description | | inputSchema | object | ❌ | JSON Schema for input | | remote | string | ✅ | Remote name | | module | string | ✅ | Module Federation path | | exportName | string | ❌ | Export name (default: 'default') |

Usage

With Claude Desktop

Already configured above. Tools will appear in Claude after restart.

Development

# Install dependencies
npm install

# Build
npm run build

# Development with watch mode
npm run dev

# Type check
npm run typecheck

How It Works

1. Configuration Loading: Server loads mcp_apps.json defining remotes and tools
2. Tool Registration: Each tool is registered with MCP protocol
3. Resource Generation: Server generates bundled HTML with MF runtime
4. Component Loading: When tool is called:
   • MCP host renders the HTML resource
   • Module Federation loads remote component from CDN
   • CORS proxy handles cross-origin requests
   • Component renders with tool input as props

Troubleshooting

Tools Not Showing

1. Check configuration file path is absolute
2. Validate mcp_apps.json syntax
3. Restart Claude Desktop
4. Check logs: ~/Library/Logs/Claude/mcp-server-module-federation.log

Component Not Loading

1. Verify CDN URL is accessible
2. Check csp.connectDomains includes CDN domain
3. Verify module path matches Module Federation expose
4. Check browser console in Claude DevTools

Configuration Errors

Validate manually:

// Check remote exists
const remote = config.remotes.find(r => r.name === tool.remote);
if (!remote) {
  console.error('Remote not found');
}

Examples

See mcp_apps.example.json for a complete example configuration.

Using with Custom Agents (HTTP Mode)

The server also supports HTTP mode for agent frameworks that run the MCP client server-side and render UI in a browser. See docs/integration-guide.md for a detailed integration walkthrough.

Related

• MCP Apps SDK
• Module Federation
• MCP Protocol

License

MIT