Templates

Choose from three official templates or use any GitHub repository as a custom template.

Official Templates

Starter

Full-featured with all examples

MCP Apps

OpenAI Apps SDK optimized

Blank

Minimal clean slate

Starter Template

The starter template is a comprehensive starting point with examples of all MCP features.

Use Case

Best for:

Learning MCP concepts
Exploring all features
Prototyping quickly
Building full-featured servers

What’s Included

Tools
Resources
Prompts
Widgets

Example tool implementations:

src/index.ts

// Weather fetching tool
server.tool(
  {
    name: "fetch-weather",
    description: "Fetch weather for a city",
    schema: z.object({
      city: z.string().describe("City name"),
    }),
  },
  async ({ city }) => {
    return text(`Weather in ${city}: Sunny, 72°F`);
  }
);

Example resource definitions:

src/index.ts

// Configuration resource
server.resource(
  {
    name: "config",
    uri: "config://settings",
    description: "Server configuration",
  },
  async () => object({
    theme: "dark",
    language: "en",
  })
);

Example prompt templates:

src/index.ts

// Code review prompt
server.prompt(
  {
    name: "review-code",
    description: "Review code for best practices",
    schema: z.object({
      language: z.string(),
      code: z.string(),
    }),
  },
  async ({ language, code }) => {
    return text(`
Reviewing ${language} code:

${code}

Check for:
- Best practices
- Security issues
- Performance problems
    `);
  }
);

Example React widgets:

resources/display-weather.tsx

import React from "react";
import { useMcp } from "mcp-use/react";
import { z } from "zod";

const propSchema = z.object({
  city: z.string(),
  temperature: z.number(),
});

export const widgetMetadata = {
  description: "Display weather information",
  props: propSchema,
};

export default function WeatherDisplay() {
  const { props } = useMcp<z.infer<typeof propSchema>>();

  return (
    <div className="p-4">
      <h1 className="text-2xl font-bold">{props.city}</h1>
      <p className="text-lg">{props.temperature}°F</p>
    </div>
  );
}

Features

All MCP Features

Tools with Zod validation
Resources (static and dynamic)
Prompts with argument templates
Both MCP-UI and OpenAI Apps SDK widgets

TypeScript

Full type safety
Proper tsconfig.json
Type declarations included

Development Ready

Hot reload configured
Auto-opening inspector
Example implementations
Comprehensive README

Create with Starter

npx create-mcp-use-app my-project --template starter

MCP Apps Template

The mcp-apps template is optimized for OpenAI Apps SDK integration and ChatGPT compatibility.

Use Case

Best for:

OpenAI ChatGPT integration
Apps SDK widgets
Ecommerce applications
ChatGPT-compatible UIs

What’s Included

OpenAI Widgets
Brand Info Tool
Theme Integration
Widget Capabilities

Pre-built OpenAI-compatible widgets:1. Display Weather

resources/display-weather.tsx

// Weather card with theme support
import { useWidget } from 'mcp-use/react';

export default function DisplayWeather() {
  const { props, theme } = useWidget();
  // theme is 'dark' or 'light' from ChatGPT
  return (
    <div className={theme === 'dark' ? 'bg-gray-800' : 'bg-white'}>
      {/* ... */}
    </div>
  );
}

2. Ecommerce Carousel

resources/ecommerce-carousel.tsx

// Product carousel with OpenAI SDK UI components
import { Card, Button } from '@openai/apps-sdk-ui';

export default function EcommerceCarousel() {
  const { props, sendFollowUpMessage } = useWidget();

  return (
    <div className="carousel">
      {props.products.map(product => (
        <Card key={product.id}>
          <img src={product.image} />
          <h3>{product.name}</h3>
          <Button onClick={() => sendFollowUpMessage(
            `Tell me more about ${product.name}`
          )}>
            Learn More
          </Button>
        </Card>
      ))}
    </div>
  );
}

3. Product Search

resources/product-search-result.tsx

// Search results with filters

4. Store Locations Map

resources/stores-locations-map.tsx

// Interactive map showing store locations

5. Order Confirmation

resources/order-confirmation.tsx

// Order summary and confirmation

Example API tool:

src/index.ts

// Fruits API endpoint
server.get("/api/fruits", (c) => {
  return c.json([
    { fruit: "mango", color: "bg-[#FBF1E1]" },
    { fruit: "apple", color: "bg-[#F9E7E4]" },
    // ...
  ]);
});

// Brand information tool
server.tool(
  {
    name: "get-brand-info",
    description: "Get brand information",
  },
  async () => {
    return object({
      name: "mcp-use",
      tagline: "Build MCP servers with UI widgets",
      features: [
        "Automatic widget registration",
        "React component support",
        "TypeScript support",
      ],
    });
  }
);

Theme detection from ChatGPT:

import { useWidget } from 'mcp-use/react';

export default function MyWidget() {
  const { theme } = useWidget();
  // theme is 'dark' or 'light'

  return (
    <div className={`
      ${theme === 'dark' 
        ? 'bg-gray-900 text-white' 
        : 'bg-white text-gray-900'
      }
    `}>
      Content adapts to ChatGPT theme
    </div>
  );
}

Full Apps SDK features:

import { useWidget } from 'mcp-use/react';

export default function MyWidget() {
  const { 
    props,              // Validated widget props
    theme,              // 'dark' | 'light'
    callTool,           // Call MCP tools
    sendFollowUpMessage, // Send message to chat
  } = useWidget();

  const handleClick = async () => {
    // Call MCP tool
    const result = await callTool('my-tool', {
      param: 'value',
    });

    // Send follow-up message
    sendFollowUpMessage(
      `Tool returned: ${result.content}`
    );
  };

  return <button onClick={handleClick}>Execute</button>;
}

Features

OpenAI Apps SDK

Full ChatGPT compatibility
Theme detection
Official UI components
Persistent state

Automatic Registration

Widgets auto-register from resources/
Props schema validation
Type-safe props

Ecommerce Examples

Product carousel
Search with filters
Store locator map
Order confirmation

Create with MCP Apps

npx create-mcp-use-app my-project --template mcp-apps

Blank Template

The blank template provides a minimal starting point for custom projects.

Use Case

Best for:

Custom implementations
Minimal dependencies
Learning from scratch
Specific use cases

What’s Included

Server Only
Configuration
Structure

Minimal server setup:

src/index.ts

import { MCPServer } from "mcp-use/server";

const server = new MCPServer({
  name: "my-server",
  version: "1.0.0",
});

// Add your tools, resources, and prompts here

server.listen(3000);

No example implementations - clean slate.

Basic configuration files:

package.json

{
  "name": "my-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "dev": "mcp-use dev",
    "build": "mcp-use build",
    "start": "mcp-use start"
  },
  "dependencies": {
    "mcp-use": "^2.0.0"
  },
  "devDependencies": {
    "@mcp-use/cli": "^2.0.0",
    "typescript": "^5.0.0"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true,
    "outDir": "./dist"
  }
}

Minimal project structure:

my-project/
├── package.json
├── tsconfig.json
├── .gitignore
├── README.md
├── src/
│   └── index.ts        # Empty server
├── public/            # Empty
└── resources/         # Empty

Add your own implementations.

Features

Minimal Dependencies

Only essential packages
No example code
Clean starting point

Full CLI Support

Dev server with hot reload
Build and deployment scripts
Inspector integration

Create with Blank

npx create-mcp-use-app my-project --template blank

Custom GitHub Templates

Use any GitHub repository as a template.

Syntax

npx create-mcp-use-app my-project --template owner/repo

# Example:
npx create-mcp-use-app my-project --template acme/mcp-template

Requirements

Git must be installed and available in your PATH to use GitHub templates.

Public Repository

Repository must be publicly accessible (or you must have access).

Valid Structure

Repository should contain:

package.json
src/ directory (or TypeScript files)
Optional: tsconfig.json, README.md

Template Variables

Files can include placeholders:

{{PROJECT_NAME}} - Replaced with your project name
{{mcp-use_version}} - Replaced with latest mcp-use version

Example Custom Template

Create your own template repository:

package.json

{
  "name": "{{PROJECT_NAME}}",
  "version": "1.0.0",
  "dependencies": {
    "mcp-use": "{{mcp-use_version}}"
  }
}

src/index.ts

// Your custom template code
import { MCPServer } from "mcp-use/server";

const server = new MCPServer({
  name: "{{PROJECT_NAME}}",
  version: "1.0.0",
});

// Your custom tools and resources

server.listen(3000);

Users can then use:

npx create-mcp-use-app my-project --template your-org/your-template

Template Comparison

Feature	Starter	MCP Apps	Blank
Tools	✅ Examples	✅ Brand info	❌ None
Resources	✅ Examples	❌ None	❌ None
Prompts	✅ Examples	❌ None	❌ None
Widgets	✅ Both types	✅ Apps SDK	❌ None
Documentation	✅ Comprehensive	✅ Apps-focused	✅ Minimal
Dependencies	Full	Medium	Minimal
Best For	Learning	ChatGPT	Custom

Choosing a Template

Learning?

Use starter template:

npx create-mcp-use-app my-project --template starter

See all features with examples.

Building for ChatGPT?

Use mcp-apps template:

npx create-mcp-use-app my-project --template mcp-apps

Get OpenAI Apps SDK integration.

Starting Fresh?

Use blank template:

npx create-mcp-use-app my-project --template blank

Build from scratch.

Have Custom Template?

Use GitHub repository:

npx create-mcp-use-app my-project --template owner/repo

Use your organization’s template.

Next Steps

Customization

Customize your generated project

CLI Commands

Learn about development commands

Inspector

CLI

Create App

Templates

Templates

Official Templates

Starter

MCP Apps

Blank

Starter Template

Use Case

What’s Included

Features

Create with Starter

MCP Apps Template

Use Case

What’s Included

Features

Create with MCP Apps

Blank Template

Use Case

What’s Included

Features

Create with Blank

Custom GitHub Templates

Syntax

Requirements

Example Custom Template

Template Comparison

Choosing a Template

Next Steps

Customization

CLI Commands

Build docs developers (and LLMs) love

Inspector

CLI

Create App

​Templates

​Official Templates

Starter

MCP Apps

Blank

​Starter Template

​Use Case

​What’s Included

​Features

​Create with Starter

​MCP Apps Template

​Use Case

​What’s Included

​Features

​Create with MCP Apps

​Blank Template

​Use Case

​What’s Included

​Features

​Create with Blank

​Custom GitHub Templates

​Syntax

​Requirements

​Example Custom Template

​Template Comparison

​Choosing a Template

​Next Steps

Customization

CLI Commands

Build docs developers (and LLMs) love

Templates

Official Templates

Starter Template

Use Case

What’s Included

Features

Create with Starter

MCP Apps Template

Use Case

What’s Included

Features

Create with MCP Apps

Blank Template

Use Case

What’s Included

Features

Create with Blank

Custom GitHub Templates

Syntax

Requirements

Example Custom Template

Template Comparison

Choosing a Template

Next Steps