MCP App Studio Starter

Starter template for building interactive apps for AI assistants with MCP App Studio.

Note: This template is automatically downloaded when you run npx mcp-app-studio. You don’t need to clone this repo directly.

Supported Platforms

Build once, deploy anywhere:

• ChatGPT — as an MCP Apps host (standard ui/* bridge)
• Claude Desktop — as an MCP Apps host
• Any MCP Apps host — compatible with any MCP-supporting AI assistant

Quick Start

# npm (default)
npm install
npm run dev

Open http://localhost:3002 — you’re in the workbench.

This project also works with pnpm/yarn/bun (use the equivalent install + run commands).

If you switch package managers (e.g. pnpm → npm), delete node_modules/ first to avoid confusing the installer.

The MCP server (when server/ exists) runs at http://localhost:3001/mcp by default. If 3001 is already in use, it will select the next available port and write it to server/.mcp-port.

The workbench simulates an MCP Apps host in an iframe. It also installs a window.openai shim so you can exercise ChatGPT-only extensions during development (optional, non-standard).

Agent Workflow

Use .agent/skills/mcp-app-development/SKILL.md as the default coding-agent workflow for this repo. It defines the 80/20 capability-slice loop:

• Build UI and real MCP tool(s) in one chunk
• Use TDD (red -> green) for parity checks
• Never treat mock-only behavior as done

Commands

Project Structure

app/                        Next.js pages
components/
├── examples/               Example widgets (POI Map)
├── workbench/              Workbench UI components
└── ui/                     Shared UI components
lib/
├── sdk/                    SDK exports for production
├── workbench/              React hooks + dev environment
└── export/                 Production bundler
server/                     MCP server (if included)

Building Your Widget

1. Create a component

// components/my-widget/index.tsx
import {
  useToolInput,
  useCallTool,
  useTheme,
  useCapabilities,
  useUpdateModelContext,
  useWidgetState,
} from "@/lib/sdk";

export function MyWidget() {
  const input = useToolInput();
  const callTool = useCallTool();
  const theme = useTheme();
  const capabilities = useCapabilities();
  const updateModelContext = useUpdateModelContext();
  const [widgetState, setWidgetState] = useWidgetState();

  const handleSearch = async () => {
    const result = await callTool("search", { query: input.query });