mcp-tool-resource-pattern

mcp-tool-resource-pattern

Implement the foundational Tool + Resource pattern that every MCP App requires: a Tool that returns data and references a Resource that serves the interactive UI.

Overview

Every MCP App is built on the Tool + Resource pattern:

1. Tool (registered via registerAppTool): Called by the LLM/host, returns data. Its _meta.ui.resourceUri tells the host which Resource provides the UI.
2. Resource (registered via registerAppResource): Serves a bundled HTML file that renders the interactive UI in a sandboxed iframe.
3. The tool passes data to the UI via structuredContent (available in ontoolresult handler).
4. The tool MUST also return a content array with text fallback for non-UI hosts.

Capabilities

registerAppTool Implementation

• Register tools with _meta.ui.resourceUri linking to a resource
• Pass data via structuredContent for rich UI rendering
• Always include content array with text fallback
• Configure tool input schemas via Zod

registerAppResource Implementation

• Register HTML resources with RESOURCE_MIME_TYPE
• Serve single-file bundled HTML
• Configure CSP domains in contents[] return
• Support multiple tools sharing the same resource URI

App-Only Helper Tools

• Create tools with visibility: ['app'] -- only callable from the UI iframe, not by the LLM
• Use cases: polling for updates, loading additional data, pagination, state mutations
• Implement via app.callServerTool() from client-side

Graceful Degradation

• Detect UI capability via getUiCapability() on the server
• Return richer responses when UI is available
• Always maintain text-only fallback path

Usage

Basic Tool + Resource Pattern

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import {
  registerAppTool,
  registerAppResource,
  RESOURCE_MIME_TYPE,
} from '@modelcontextprotocol/ext-apps';
import { z } from 'zod';
import fs from 'fs';
import path from 'path';

const server = new McpServer({ name: 'my-app', version: '1.0.0' });

// Read the bundled HTML (built by vite-plugin-singlefile)
const bundledHtml = fs.readFileSync(
  path.join(__dirname, '../dist/mcp-app.html'),
  'utf-8'
);

// 1. Register the Resource (serves the UI)
registerAppResource(server, {
  uri: 'app:///my-app',
  name: 'My App UI',
  mimeType: RESOURCE_MIME_TYPE,
  async read() {
    return {
      contents: [{
        uri: 'app:///my-app',
        mimeType: RESOURCE_MIME_TYPE,
        text: bundledHtml,
        // CSP domains (if needed)
        // resourceDomains: ['https://cdn.example.com'],
        // connectDomains: ['https://api.example.com'],
      }],
    };
  },
});

// 2. Register the Tool (returns data, references the resource)
registerAppTool(server, {
  name: 'show_dashboard',
  description: 'Show an interactive dashboard',
  inputSchema: {
    type: 'object' as const,
    properties: {
      query: { type: 'string', description: 'Search query' },
    },
    required: ['query'],
  },
  // _meta.ui.resourceUri is set automatically by registerAppTool
  resourceUri: 'app:///my-app',
  async handler(args) {
    const data = await fetchDashboardData(args.query);

    return {
      // Text fallback for non-UI hosts (REQUIRED)
      content: [
        {
          type: 'text' as const,
          text: `Dashboard results for "${args.query}":\n${formatAsText(data)}`,
        },
      ],
      // Rich data for the UI (available in ontoolresult handler)
      structuredContent: {
        query: args.query,
        results: data.results,
        metadata: data.metadata,
      },
    };
  },
});