ext-apps/examples/basic-server-vanillajs/README.md

Example: Basic Server (Vanilla JS)

An MCP App example with a vanilla JavaScript UI (no framework).

Tip

Looking for a React-based example? See basic-server-react!

MCP Client Configuration

Add to your MCP client configuration (stdio transport):

{
  "mcpServers": {
    "basic-vanillajs": {
      "command": "npx",
      "args": [
        "-y",
        "--silent",
        "--registry=https://registry.npmjs.org/",
        "@modelcontextprotocol/server-basic-vanillajs",
        "--stdio"
      ]
    }
  }
}

Local Development

To test local modifications, use this configuration (replace ~/code/ext-apps with your clone path):

{
  "mcpServers": {
    "basic-vanillajs": {
      "command": "bash",
      "args": [
        "-c",
        "cd ~/code/ext-apps/examples/basic-server-vanillajs && npm run build >&2 && node dist/index.js --stdio"
      ]
    }
  }
}

Overview

• Tool registration with a linked UI resource
• Vanilla JS UI using the App class directly
• App communication APIs: callServerTool, sendMessage, sendLog, openLink
• Theme integration via applyDocumentTheme(), applyHostStyleVariables(), and applyHostFonts()

Key Files

• server.ts - MCP server with tool and resource registration
• mcp-app.html / src/mcp-app.ts - Vanilla JS UI using App class

Getting Started

npm install
npm run dev

How It Works

1. The server registers a get-time tool with metadata linking it to a UI HTML resource (ui://get-time/mcp-app.html).
2. When the tool is invoked, the Host renders the UI from the resource.
3. The UI uses the MCP App SDK API to communicate with the host and call server tools.

Build System

This example bundles into a single HTML file using Vite with vite-plugin-singlefile — see vite.config.ts. This allows all UI content to be served as a single MCP resource. Alternatively, MCP apps can load external resources by defining _meta.ui.csp.resourceDomains in the UI resource metadata.