Skip to main content
skill CX Codex

mcp-visual-output — Claude Code skill: what it does, how to install

The mcp-visual-output skill for Claude Code transforms MCP tool JSON results into interactive dashboards. It activates when visual data presentation is more effective than plain text output.

MIT 105 installs ★ 305 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add yonatangross/orchestkit --skill mcp-visual-output -a claude-code
Open on GitHub

What mcp-visual-output does

The mcp-visual-output skill upgrades standard MCP tool responses, rendering them as interactive dashboards within AI conversations. It is built on @json-render/mcp, which connects the json-render specification system with MCP's tool and resource model.

The AI generates a typed JSON specification, and a sandboxed iframe renders it as an interactive user interface. This skill focuses on the visual output layer after your MCP server is already running, not on building the server itself. It requires compatibility with Claude Code version 2.1.277+.

What it helps with

  • Visualize MCP tool JSON results
  • Create interactive dashboards from structured data
  • Display metrics and statuses as tables or badges
  • Present data in an interactive UI within AI chat

Example prompts for the agent

  • Display the execution results as a dashboard.
  • Generate a report from this data using an interactive panel.
  • Show the project status as a set of widgets.

How to install mcp-visual-output

1Skills CLI (Vercel)

npx skills add yonatangross/orchestkit --skill mcp-visual-output -a claude-code

2Manually: put the files in place

~/.claude/skills/mcp-visual-output/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/mcp-visual-output/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about mcp-visual-output

How to install mcp-visual-output in Claude Code?

To install the skill in Claude Code, use the command: npx skills add yonatangross/orchestkit --skill mcp-visual-output -a claude-code.

What does the mcp-visual-output skill do?

The mcp-visual-output skill converts JSON responses from MCP tools into interactive dashboards, displayed within a sandboxed iframe in the AI interface. It allows for visualizing structured data using pre-built components.

What is needed for mcp-visual-output to work?

The mcp-visual-output skill requires compatibility with Claude Code version 2.1.277+. It is designed for the visual output layer once an MCP server is already operational.

Source text

SKILL.md · MIT
---
name: mcp-visual-output
compatibility: "Claude Code 2.1.277+"
description: "Renders MCP tool JSON results as dashboards via @json-render/mcp (stat grids, tables, badges). Use when a result reads better visually. Not for building the server."
user-invocable: false
disable-model-invocation: false
context: inherit
metadata:
  category: mcp
  upstream-package: "@json-render/mcp"
  upstream-version-tested: "0.21.3"
  version: "1.1.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "mcp, json-render, visual-output, dashboard, iframe, sandbox, interactive-ui, genui"
---

Upstream version reference: `@json-render/mcp` 0.21.3 (2026-10-24).

# MCP Visual Output

Upgrade plain MCP tool responses to interactive dashboards rendered inside AI conversations. Built on `@json-render/mcp`, which bridges the json-render spec system with MCP's tool/resource model -- the AI generates a typed JSON spec, and a sandboxed iframe renders it as an interactive UI.

> **Building an MCP server from scratch?** Use `ork-extras:mcp-patterns` for server setup, transport, and security. This skill focuses on the **visual output layer** after your server is running.
>
> **Need the full component catalog?** See `ork:json-render-catalog` for all available components, props, and composition patterns.

## Decision Tree -- Which File to Read

```
What are you doing?
|
+-- Setting up visual output for the first time
|   +-- New MCP server -----------> rules/mcp-app-setup.md
|   +-- Existing MCP server ------> rules/mcp-app-setup.md (registerJsonRenderTool section)
|
+-- Configuring security / sandbox
|   +-- CSP declarations ----------> rules/sandbox-csp.md
|   +-- Iframe permissions --------> rules/sandbox-csp.md
|
+-- Rendering strategy
|   +-- Progressive streaming -----> rules/streaming-output.md
|   +-- Dashboard layouts ----------> rules/dashboard-patterns.md
|
+-- API reference
|   +-- Server-side API -----------> references/mcp-integration.md
|   +-- Component recipes ----------> references/component-recipes.md
```

## Quick Reference

| Category | Rule | Impact | Key Pattern |
|----------|------|--------|-------------|
| **Setup** | `mcp-app-setup.md` | HIGH | createMcpApp() and registerJsonRenderTool() |
| **Security** | `sandbox-csp.md` | HIGH | CSP declarations, iframe sandboxing |
| **Rendering** | `streaming-output.md` | MEDIUM | Progressive rendering via JSON Patch |
| **Patterns** | `dashboard-patterns.md` | MEDIUM | Stat grids, status badges, data tables |

**Total: 4 rules across 3 categories**

## How It Works

1. **Define a catalog** -- typed component schemas using `defineCatalog()` + Zod
2. **Register with MCP** -- `createMcpApp()` for new servers or `registerJsonRenderTool()` for existing ones
3. **AI generates specs** -- the model produces a JSON spec conforming to the catalog
4. **Iframe renders it** -- a bundled React app inside a sandboxed iframe renders the spec with `useJsonRenderApp()` + `<Renderer />`

The AI never writes HTML or CSS. It produces a structured JSON spec that references catalog components by type. The iframe app renders those components using a pre-built registry.

## Quick Start -- New MCP Server

```typescript
import { createMcpApp } from '@json-render/mcp'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { buildAppHtml } from '@json-render/mcp/app'
import { catalog } from './catalog'

// Generate the iframe HTML from the bundled JS/CSS (docs-prescribed generator).
const bundledHtml = buildAppHtml({ entry: './app.tsx' })

// 1. Create the MCP app (async; returns an McpServer, no .start()/.close()).
//    name + version are required; tool config nests under `tool`
//    (default tool name is 'render-ui'). There is no top-level `csp`.
const server = await createMcpApp({
  name: 'my-app',
  version: '1.0.0',
  catalog,           // component schemas the AI can use
  html: bundledHtml, // pre-built iframe app (single HTML file)
  tool: {
    name: 'render-dashboard',
    description: 'Render an interactive dashboard from a json-render spec',
  },
})

// 2. Connect a transport -- stdio, Streamable HTTP, or any MCP transport
await server.connect(new StdioServerTransport())
```

## Quick Start -- Enhance Existing Server with Visual Output

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { registerJsonRenderTool, registerJsonRenderResource } from '@json-render/mcp'
import { buildAppHtml } from '@json-render/mcp/app'
import { catalog } from './catalog'

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

// Generate the iframe HTML from the bundled JS/CSS (docs-prescribed generator).
const bundledHtml = buildAppHtml({ entry: './app.tsx' })

const resourceUri = 'ui://my-server/dashboard'

// Register the render tool (lets the model return specs).
// name, title, description, and resourceUri are all required.
registerJsonRenderTool(server, {
  catalog,
  name: 'render-dashboard',
  title: 'Render Dashboard',
  description: 'Render an interactive dashboard from a json-render spec',
  resourceUri,
})

// Serve the bundled HTML iframe app as a resource (new in 0.15).
// resourceUri must match the tool's resourceUri.
registerJsonRenderResource(server, { resourceUri, html: bundledHtml })
```

`registerJsonRenderResource()` was added in 0.15 to separate **tool registration** from **UI resource serving** — useful when the host caches the bundled HTML (clients: Claude, ChatGPT, Cursor, VS Code Copilot, Goose, Postman). Transports: stdio **and** Streamable HTTP (Express) both supported. This skill is verified against `@json-render/mcp` **0.20.0**, which shipped zero code change: every published file is byte-identical to 0.19.0 apart from the version and its pinned `@json-render/core` dependency. New capability in that release therefore belongs to core and react, not to this package. What reaches an MCP-rendered iframe indirectly is named slots and nested repeats, plus a fix so named `onSuccess`/`onError` chained actions actually receive their configured `params`.

## Smallest Proof: One Tool, UI Resource Plus Text Fallback

`scripts/glyph-card-server.mjs` is a dependency-free MCP server (stdio, or `--http <port>` for Streamable HTTP) with one tool, `render_glyph_card`. The tool lists `_meta.ui.resourceUri` (plus the legacy `ui/resourceUri` and the ChatGPT alias `openai/outputTemplate`), serves a `ui://` resource as `text/html;profile=mcp-app`, and returns a glyph text card in `content` with the same rows in `structuredContent`. Hosts without UI use the text; MCP Apps hosts draw the card. One caveat: Claude Code passes `structuredContent` JSON to the model when it is present, so the text card is not what the model sees there. The HTTP mode refuses any non-local Host or Origin with 403 unless you name one host with `--allow-host <host>`, so a tunnel serves only that name. Unit tests: `tests/unit/test-mcp-glyph-card.mjs`.

## Client-Side Iframe App

The iframe app receives specs from the MCP host and renders them:

```typescript
import { useJsonRenderApp } from '@json-render/mcp/app'
import { Renderer } from '@json-render/react'
import { registry } from './registry'

function App() {
  const { spec, loading } = useJsonRenderApp()
  if (loading) return <Skeleton />
  return <Renderer spec={spec} registry={registry} />
}
```

## Catalog Definition

Catalogs define what components the AI can use. Each component has typed props via Zod:

```typescript
import { defineCatalog } from '@json-render/core'
import { schema } from '@json-render/react/schema'
import { z } from 'zod'

export const dashboardCatalog = defineCatalog(schema, {
  components: {
    StatGrid: {
      props: z.object({
        items: z.array(z.object({
          label: z.string(),
          value: z.string(),
          trend: z.enum(['up', 'down', 'flat']).optional(),
          color: z.enum(['green', 'red', 'yellow', 'blue']).optional(),
        })),
      }),
      children: false,
    },
    StatusBadge: {
      props: z.object({
        label: z.string(),
        status: z.enum(['success', 'warning', 'error', 'info', 'pending']),
      }),
      children: false,
    },
    DataTable: {
      props: z.object({
        columns: z.array(z.object({ key: z.string(), label: z.string() })),
        rows: z.array(z.record(z.string())),
      }),
      children: false,
    },
  },
})
```

## Example: Eval Results Dashboard

The AI generates a spec like this -- flat element map, no nesting beyond 2 levels:

```json
{
  "root": "dashboard",
  "elements": {
    "dashboard": {
      "type": "Card",
      "props": { "title": "Eval Results -- v7.21.1" },
      "children": ["stats", "table"]
    },
    "stats": {
      "type": "StatGrid",
      "props": {
        "items": [
          { "label": "Skills Evaluated", "value": "94", "trend": "flat" },
          { "label": "Pass Rate", "value": "97.8%", "trend": "up", "color": "green" },
          { "label": "Avg Score", "value": "8.2/10", "trend": "up" }
        ]
      }
    },
    "table": {
      "type": "DataTable",
      "props": {
        "columns": [
          { "key": "skill", "label": "Skill" },
          { "key": "score", "label": "Score" },
          { "key": "status", "label": "Status" }
        ],
        "rows": [
          { "skill": "implement", "score": "9.1", "status": "pass" },
          { "skill": "verify", "score": "8.7", "status": "pass" }
        ]
      }
    }
  }
}
```

## Key Decisions

| Decision | Recommendation |
|----------|----------------|
| New vs existing server | `createMcpApp()` for new; `registerJsonRenderTool()` to add to existing |
| CSP policy | Minimal -- only declare domains you actually need |
| Streaming | Always enable progressive rendering; never wait for full spec |
| Dashboard depth | Keep element trees flat (2-3 levels max) for streamability |
| Component count | 3-5 component types per catalog covers most dashboards |
| Visual vs text | Use visual output for multi-metric views; plain text for single values |

> **CC 2.1.113** fixed MCP concurrent-call timeout handling — hanging tool calls now error cleanly instead of blocking the queue. Parallel tool invocation from dashboards is safer; no workarounds needed.

## When to Use Visual Output vs Plain Text

| Scenario | Use Visual Output | Use Plain Text |
|----------|------------------|----------------|
| Multiple metrics at a glance | Yes -- StatGrid | No |
| Tabular data (5+ rows) | Yes -- DataTable | No |
| Status of multiple systems | Yes -- StatusBadge grid | No |
| Single value answer | No | Yes |
| Error message | No | Yes |
| File content / code | No | Yes |

## Common Mistakes

1. Returning raw HTML strings from MCP tools instead of json-render specs (breaks type safety, no streaming)
2. Deeply nested component trees that cannot stream progressively (keep flat)
3. Using `script-src 'unsafe-inline'` in CSP declarations (security risk, unnecessary)
4. Waiting for the full spec before rendering (defeats progressive rendering)
5. Defining 20+ component types in a single catalog (increases prompt token cost)
6. Missing `html` bundle in `createMcpApp()` config (iframe has nothing to render)

## Related Skills

- `ork-extras:mcp-patterns` -- MCP server building, transport, security
- `ork:json-render-catalog` -- Full component catalog and composition patterns
- `ork:multi-surface-render` -- Rendering across Claude, Cursor, ChatGPT, web
- `ork-extras:ai-ui-generation` -- GenUI patterns for AI-generated interfaces

© OrchestKit · MIT · yonatangross/orchestkit

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set86

The whole set →
chain-patterns chain-patterns — a set of patterns for multi-stage pipelines: MCP checks, handoff files, checkpoint recovery, isolated worktree agents, and cron monitoring. CX Codex +1 118installs design-to-code design-to-code — a skill for Claude Code that turns screenshots, descriptions, and URLs into React components. Assembles UI elements while reusing existing Storybook pieces and design tokens. CX Codex +1 116installs testing-unit The testing-unit skill provides patterns for unit tests, HTTP mocks, fixtures, and test data in Vitest, Jest, and pytest. It applies while writing tests or setting up test doubles. CX Codex +1 116installs design-context-extract design-context-extract extracts colors, typography, spacing, components, and motion from screenshots, URLs, or recordings. It returns tokens or Tailwind-ready output. CX Codex +1 112installs component-search The component-search Claude Code skill searches 21st.dev for React components and ranks the matches. It runs when a request asks for a UI component or a replacement. CX Codex +1 106installs cover Generates missing tests. Runs when new features lack test coverage across unit, integration, or e2e tiers. CX Codex +1 100installs json-render-catalog The json-render-catalog Claude Code skill defines component catalogs that constrain AI-generated interfaces. It comes into play when a project needs typed component definitions or catalog imports from Storybook. CX Codex +1 100installs OrchestKit Docs MCP OrchestKit Docs MCP — a read-only MCP server for OrchestKit documentation. It searches manuals with full-text queries and extracts Markdown pages without credentials. CX Codex +1 ★ 305repo stars

Project sponsors

Companies that keep this analytics open