🚀 Create mcp-use App is the fastest way to scaffold a new MCP (Model Context Protocol) application. With just one command, you get a fully configured TypeScript project with hot reload, automatic inspector, and UI widget support - everything you need to build powerful MCP servers.

📦 Related Packages

| Package | Description | Version | | ---------------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- | | mcp-use | Core MCP framework | | | @mcp-use/cli | Build tool for MCP apps | | | @mcp-use/inspector | Web-based MCP inspector | |

⚡ Quick Start

Create a new MCP application in seconds:

npx create-mcp-use-app my-mcp-server
cd my-mcp-server
npm run dev

That's it! Your MCP server is running at http://localhost:3000 with the inspector automatically opened in your browser.

🎯 What It Creates

Running create-mcp-use-app sets up a complete MCP development environment:

Project Structure

my-mcp-server/
├── package.json          # Pre-configured with all scripts
├── tsconfig.json         # TypeScript configuration
├── .env.example          # Environment variables template
├── .gitignore           # Git ignore rules
├── README.md            # Project documentation
├── src/
│   └── index.ts         # MCP server entry point with example tools
├── resources/           # UI widgets directory
│   └── example-widget.tsx  # Example React widget
└── dist/               # Build output (generated)

Pre-configured Features

| Feature | Description | | ----------------------- | ------------------------------------------------- | | 📝 TypeScript | Full TypeScript setup with proper types | | 🔥 Hot Reload | Auto-restart on code changes during development | | 🔍 Auto Inspector | Inspector UI opens automatically in dev mode | | 🎨 UI Widgets | React components that compile to standalone pages | | 🛠️ Example Tools | Sample MCP tools, resources, and prompts | | 📦 Build Scripts | Ready-to-use development and production scripts | | 🚀 Production Ready | Optimized build configuration |

📖 Usage Options

Interactive Mode

Run without any arguments to enter interactive mode:

npx create-mcp-use-app

You'll be prompted for:

• Project name
• Project template
• Package manager preference

Direct Mode

Specify the project name directly:

npx create-mcp-use-app my-project

With Options

# Use a specific template
npx create-mcp-use-app my-project --template apps-sdk
npx create-mcp-use-app my-project --template mcp-ui

# Use a specific package manager
npx create-mcp-use-app my-project --npm
npx create-mcp-use-app my-project --yarn
npx create-mcp-use-app my-project --pnpm

# Install deps automatically
npx create-mcp-use-app my-project --install

🎨 Available Templates

Starter Template (Default)

The starter template includes:

• Comprehensive MCP server setup with all features
• Example tool, resource, and prompt
• Both MCP-UI and OpenAI Apps SDK widget examples
• Full TypeScript configuration
• Development and production scripts

Perfect for getting started with all available features or building full-featured MCP servers.

Apps SDK Template

The apps-sdk template includes:

• MCP server setup focused on OpenAI Apps SDK integration
• OpenAI Apps SDK compatible widgets
• Example display-weather widget
• Optimized for OpenAI assistant integration

Ideal for building MCP servers that integrate with OpenAI's Apps SDK.

MCP-UI Template

The mcp-ui template includes:

• MCP server setup focused on MCP-UI resources
• Interactive UI components example
• Kanban board widget demonstration
• Clean, focused setup for UI-first applications

Best for building MCP servers with rich interactive UI components.

🏗️ What Gets Installed

The scaffolded project includes these dependencies:

Core Dependencies

• mcp-use - The MCP framework
• @mcp-use/cli - Build and development tool
• @mcp-use/inspector - Web-based debugger

Development Dependencies

• typescript - TypeScript compiler
• tsx - TypeScript executor for development
• @types/node - Node.js type definitions

Template-Specific Dependencies

Different templates may include additional dependencies based on their features:

• UI libraries (React, styling frameworks)
• Widget-specific utilities

🚀 After Installation

Once your project is created, you can:

Start Development

npm run dev
# or
yarn dev
# or
pnpm dev

This will:

1. Start the MCP server on port 3000
2. Open the inspector in your browser
3. Watch for file changes and auto-reload

Build for Production

npm run build

Creates an optimized build in the dist/ directory.

Start Production Server

npm run start

Runs the production build.

💡 First Steps

After creating your app, here's what to do next:

1. Explore the Example Server

Open src/index.ts to see how to:

• Define MCP tools with Zod schemas
• Create resources for data access
• Set up prompts for AI interactions

2. Try the Inspector

The inspector automatically opens at http://localhost:3000/inspector where you can:

• Test your tools interactively
• View available resources
• Debug tool executions
• Monitor server status

3. Create a UI Widget

Edit resources/example-widget.tsx or create new widgets:

import React from 'react'
import { useMcp } from 'mcp-use/react'

export default function MyWidget() {
  const { callTool } = useMcp()

  const handleClick = async () => {
    const result = await callTool('my_tool', {
      param: 'value',
    })
    console.log(result)
  }

  return (
    <div>
      <button onClick={handleClick}>Call MCP Tool</button>
    </div>
  )
}

4. Connect to AI

Use the MCP server with any MCP-compatible client:

import { MCPClient, MCPAgent } from 'mcp-use'
import { ChatOpenAI } from '@langchain/openai'

const client = new MCPClient({
  url: 'http://localhost:3000/mcp',
})

const agent = new MCPAgent({
  llm: new ChatOpenAI(),
  client,
})

const result = await agent.run('Use my MCP tools')

🔧 Configuration

Environment Variables

The created project includes a .env.example file:

# Server Configuration
PORT=3000
NODE_ENV=development

# OAuth (if using authentication)
OAUTH_CLIENT_ID=your_client_id
OAUTH_CLIENT_SECRET=your_client_secret

# Database (if using database)
DATABASE_URL=postgresql://localhost/myapp

# Observability (optional)
LANGFUSE_PUBLIC_KEY=your_public_key
LANGFUSE_SECRET_KEY=your_secret_key

Copy to .env and configure as needed:

cp .env.example .env

TypeScript Configuration

The tsconfig.json is pre-configured for MCP development:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

📚 Examples

Creating a Tool

server.tool('search_database', {
  description: 'Search for records in the database',
  parameters: z.object({
    query: z.string().describe('Search query'),
    limit: z.number().optional().default(10),
  }),
  execute: async ({ query, limit }) => {
    // Your tool logic here
    const results = await db.search(query, limit)
    return { results }
  },
})

Creating a Resource

server.resource('user_profile', {
  description: 'Current user profile data',
  uri: 'user://profile',
  mimeType: 'application/json',
  fetch: async () => {
    const profile = await getUserProfile()
    return JSON.stringify(profile)
  },
})

Creating a Prompt

server.prompt('code_review', {
  description: 'Review code for best practices',
  arguments: [
    { name: 'code', description: 'Code to review', required: true },
    { name: 'language', description: 'Programming language', required: false },
  ],
  render: async ({ code, language }) => {
    return `Please review this ${
      language || ''
    } code for best practices:\n\n${code}`
  },
})

🐛 Troubleshooting

Common Issues

Command not found:

# Make sure you have Node.js 20.19+ installed
node --version

# Try with npx
npx create-mcp-use-app@latest

Permission denied:

# On macOS/Linux, you might need sudo
sudo npx create-mcp-use-app my-app

Network issues:

# Use a different registry
npm config set registry https://registry.npmjs.org/

Port already in use:

# Change the port in your .env file
PORT=3001

🤝 Contributing

We welcome contributions! To contribute:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

See our contributing guide for more details.

📚 Learn More

• mcp-use Documentation
• Model Context Protocol Spec
• Creating MCP Tools
• Building UI Widgets
• Using the Inspector
• Supabase Edge Functions

📜 License

MIT © mcp-use