mcp-use - The fullstack MCP framework to develop MCP Apps for ChatGPT / Claude and MCP Servers for AI Agents.

Use this quickstart to scaffold a working TypeScript MCP server, run it locally, and verify it with the Inspector.

This quickstart covers the mcp-use Server SDK.Building an AI agent or MCP Client instead? Head to the MCP Agent or MCP Client introductions instead.

Prerequisites

Node.js 20.19+ or 22.12+
Basic familiarity with React and TypeScript

Create your server

Scaffold a new project:

npx create-mcp-use-app

The CLI asks four questions. The first needs an answer; the rest have a default you accept by pressing Enter.

What is your project name? Sets the folder name and the server’s name. Enter . to scaffold into the current directory.
Select a template: Pick one of the three below with the arrow keys. mcp-apps is highlighted by default.
Install AI coding skills for Cursor, Claude Code, and Codex? Adds mcp-use skills so your coding agent understands the framework. Defaults to yes.
Install dependencies? Installs with the package manager you ran the command with (npm, pnpm, or yarn). Defaults to yes.

Template	What you get
`mcp-apps` (default)	A server plus an example React widget that renders in ChatGPT and Claude.
`starter`	A server with an example tool, resource, and prompt.
`blank`	A minimal server with no examples.

To skip the questions, pass the name and template as arguments:

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

Start the dev server

cd my-server
npm run dev

npm run dev runs mcp-use dev, which:

serves the MCP endpoint at http://localhost:3000/mcp
opens the Inspector at http://localhost:3000/inspector
hot-reloads tools, resources, prompts, and widgets as you edit, with no restart and no dropped connections

Open the Inspector, go to the Tools tab, and run a tool to see it respond. With the mcp-apps template, calling search-tools renders the widget inline. You can also test the running server from the terminal with the mcp-use client CLI. This is the quickest path for scripts and coding agents, which can’t drive the Inspector’s UI:

npx mcp-use client connect local http://localhost:3000/mcp
npx mcp-use client local tools list

The first command saves the server under the name local; later commands address it by that name. See the CLI client reference for the full command set.

Explore the project

my-server/
├── resources/                  # React widgets, auto-discovered
│   └── greeting-card/
│       └── widget.tsx
├── public/                     # Static assets (icons, images)
├── index.ts                    # Server entry: tools, resources, prompts
├── package.json
└── tsconfig.json

index.ts is where you register your tools, resources, and prompts. Each folder under resources/ is a widget; its folder name matches the widget.name a tool references.

Add a tool

Open index.ts and add a tool to the existing server. text, widget, and z are already imported at the top of the file:

server.tool(
  {
    name: "greeting-card",
    description: "Create a greeting card for someone",
    schema: z.object({
      name: z.string().describe("Who to greet"),
      message: z.string().describe("The message inside the card"),
    }),
    widget: {
      name: "greeting-card",
      invoking: "Designing the card...",
      invoked: "Card ready",
    },
  },
  async ({ name, message }) =>
    widget({
      props: { name, message },
      output: text(`Made a card for ${name}`),
    })
);

Instead of returning plain text, this tool returns a widget. widget.name (greeting-card) points at a folder under resources/, and widget({ props }) passes that data to the widget’s useWidget().props. The widget doesn’t exist yet, so build it next. Create resources/greeting-card/widget.tsx. The folder name must match the tool’s widget.name:

import { McpUseProvider, useWidget } from "mcp-use/react";

interface GreetingCardProps {
  name: string;
  message: string;
}

export default function GreetingCard() {
  const { props } = useWidget<GreetingCardProps>();

  return (
    <McpUseProvider autoSize>
      <div style={{ padding: "2rem", textAlign: "center" }}>
        <h2>Hello, {props.name}!</h2>
        <p>{props.message}</p>
      </div>
    </McpUseProvider>
  );
}

Save the file. The dev server discovers the new widget and hot-reloads, so reload the Tools tab in the Inspector and call greeting-card with { name: "Ada", message: "Welcome aboard!" }. The card renders inline.

See Tools, Resources, and Prompts for the full API, and MCP Apps to build widgets.

Deploy to Manufact Cloud

When you’re ready to share your server, deploy it with one command:

npm run deploy

This runs mcp-use deploy, which builds your server and deploys it to Manufact Cloud with a public MCP URL, logs, and metrics. The first run walks you through logging in and connecting your project.

Deployment guide

GitHub connection, environment variables, regions, and redeploys.

Next steps

MCP Server

Tools, resources, prompts, and server configuration.

MCP Apps

Build interactive widgets for ChatGPT and Claude.

Inspector

Test and debug your server interactively.

MCP 101

How clients, servers, and the three primitives fit together.

Need help? Join our Discord or check out GitHub.

Get Started

MCP Server

MCP Apps

MCP Client

MCP Agent

Tooling

Quickstart

Prerequisites

Create your server

Start the dev server

Explore the project

Add a tool

Add a widget

Deploy to Manufact Cloud

Deployment guide

Next steps

MCP Server

MCP Apps

Inspector

MCP 101

​Prerequisites

​Create your server

​Start the dev server

​Explore the project

​Add a tool

​Add a widget

​Deploy to Manufact Cloud

Deployment guide

​Next steps

MCP Server

MCP Apps

Inspector

MCP 101

Prerequisites

Create your server

Start the dev server

Explore the project

Add a tool

Add a widget

Deploy to Manufact Cloud

Next steps