Create mcp-use App

🚀 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:

``bash
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:

$3

`
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)
`

$3

| 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

$3

Run without any arguments to enter interactive mode:

`bash
npx create-mcp-use-app
`

You'll be prompted for:

- Project name
- Project template
- Package manager preference

$3

Specify the project name directly:

`bash
npx create-mcp-use-app my-project
`

$3

`bash


Use a specific template

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

Use a GitHub repository as a template

npx create-mcp-use-app my-project --template owner/repo
npx create-mcp-use-app my-project --template https://github.com/owner/repo
npx create-mcp-use-app my-project --template owner/repo#branch-name

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

$3

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.

$3

The mcp-apps 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.

$3

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.

$3

You can use any GitHub repository as a template by providing the repository URL:

`bash


Short format (owner/repo)

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

Full URL format

npx create-mcp-use-app my-project --template https://github.com/owner/repo

With specific branch

npx create-mcp-use-app my-project --template owner/repo#branch-name
npx create-mcp-use-app my-project --template https://github.com/owner/repo#branch-name
`

The repository will be cloned and its contents will be used to initialize your project. This is useful for:

- Using community templates
- Sharing custom templates within your organization
- Creating projects from existing repositories

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

---

🏗️ What Gets Installed

The scaffolded project includes these dependencies:

$3

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

$3

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

$3

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:

$3

`bash
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

$3

`bash
npm run build
`

Creates an optimized build in the dist/ directory.

$3

`bash
npm run start
`

Runs the production build.

---

💡 First Steps

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

$3

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

$3

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

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

`tsx
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 (



);
}
`

$3

Use the MCP server with any MCP-compatible client:

`typescript
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

$3

The created project includes a .env.example file:

`bash


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:

`bash
cp .env.example .env
`

$3

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

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

---

📚 Examples

$3

`typescript
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 };
},
});
`

$3

`typescript
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);
},
});
`

$3

`typescript
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

$3

Command not found:

`bash


Make sure you have Node.js 20.19+ installed

node --version

Try with npx

npx create-mcp-use-app@latest
`

Permission denied:

`bash


On macOS/Linux, you might need sudo


sudo npx create-mcp-use-app my-app
`

Network issues:

`bash


Use a different registry


npm config set registry https://registry.npmjs.org/
`

Port already in use:

`bash


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