json-render/packages/mcp

@json-render/mcp

MCP Apps integration for json-render. Serve json-render UIs as interactive MCP Apps inside Claude, ChatGPT, Cursor, VS Code, and other MCP-capable clients.

What are MCP Apps?

MCP Apps is an extension to the Model Context Protocol that lets MCP servers return interactive HTML UIs rendered directly inside chat conversations. Instead of text-only tool responses, users get full interactive interfaces -- dashboards, forms, data visualizations -- embedded inline.

Installation

npm install @json-render/mcp @json-render/core @modelcontextprotocol/sdk

Quick Start

1. Define your catalog

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";

const catalog = defineCatalog(schema, {
  components: { ...shadcnComponentDefinitions },
  actions: {},
});

2. Create the MCP server

import { createMcpApp } from "@json-render/mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import fs from "node:fs";

const server = createMcpApp({
  name: "My Dashboard",
  version: "1.0.0",
  catalog,
  html: fs.readFileSync("dist/index.html", "utf-8"),
});

await server.connect(new StdioServerTransport());

3. Build the UI (iframe)

Create a React app that uses useJsonRenderApp from @json-render/mcp/app:

import { useJsonRenderApp } from "@json-render/mcp/app";
import { JSONUIProvider, Renderer } from "@json-render/react";

function McpAppView({ registry }) {
  const { spec, loading, connected, error } = useJsonRenderApp();

  if (error) return <div>Error: {error.message}</div>;
  if (!spec) return <div>Waiting for spec...</div>;

  return (
    <JSONUIProvider registry={registry} initialState={spec.state ?? {}}>
      <Renderer spec={spec} registry={registry} loading={loading} />
    </JSONUIProvider>
  );
}

Bundle with Vite + vite-plugin-singlefile into a single HTML file, then pass it to createMcpApp as the html option.

4. Connect to a client

Add to .cursor/mcp.json or Claude Desktop config:

{
  "mcpServers": {
    "my-app": {
      "command": "node",
      "args": ["./server.js", "--stdio"]
    }
  }
}

API Reference

Server Side (main export)

createMcpApp(options)

Creates a fully-configured McpServer with a json-render tool and UI resource.

Option	Type	Description
name	string	Server name shown in client UIs
version	string	Server version
catalog	Catalog	json-render catalog defining available components
html	string	Bundled HTML for the iframe UI
tool	McpToolOptions	Optional tool name/title/description overrides

registerJsonRenderTool(server, options)

Register a json-render tool on an existing McpServer.

registerJsonRenderResource(server, options)

Register a json-render UI resource on an existing McpServer.

Client Side (@json-render/mcp/app)

useJsonRenderApp(options?)

React hook for the iframe-side app. Connects to the MCP host, receives tool results, and maintains the current json-render spec.

Returns { spec, loading, connected, connecting, error, app, callServerTool }.

buildAppHtml(options)

Generate a self-contained HTML string from bundled JS/CSS for use as a UI resource.

Client Support

MCP Apps are supported by Claude, ChatGPT, VS Code (Copilot), Cursor, Goose, and Postman.