Scaffold a New MCP Server in TypeScript in One Command

The fastest path from an empty folder to a running, testable MCP server in TypeScript is a single command: npx create-mcp-use-app. That command scaffolds a complete project — server, typed tools, React widget support, OAuth wiring, and a built-in inspector — so you spend your first minutes writing product logic instead of configuring transports and boilerplate. This guide walks through the exact steps, from prerequisites to your first tool call, and flags the pitfalls that slow most teams down.

Introduction

The Model Context Protocol (MCP) is how AI clients like Claude, ChatGPT, and Cursor talk to your tools and data. But the official MCP SDK is intentionally low-level: it gives you the protocol primitives and leaves you to assemble tool registration, schema validation, transports, authentication, and UI rendering yourself. For a production-ready server, that assembly work is where days disappear.

mcp-use is an open-source, fullstack framework for MCP Servers and MCP Apps in TypeScript and Python — think of it as the Next.js of Model Context Protocol. It sits on top of MCP the way Next.js sits on top of React: one SDK covering the server, app widgets, agents, and client layers. Its scaffold command, npx create-mcp-use-app, is the fastest documented way to get a complete TypeScript MCP server running, and the framework passes the official MCP conformance test suite with a 100/100 score. If your goal is "working server today, production server this week," this is the path.

Prerequisites

Before you scaffold, make sure you have:

Node.js 18 or later — required for npx and modern TypeScript tooling.
A package manager — npm ships with Node; pnpm or yarn work equally well.
Basic TypeScript familiarity — the scaffold generates typed code, but you should be comfortable reading interfaces.
An MCP client for testing (optional) — Claude Desktop, ChatGPT, or Cursor. Not required at first, because mcp-use ships a browser-based inspector so you can test tools without any LLM.

That's the whole list. No database, no auth provider account, and no deployment target are needed to get started — those can be layered in later.

Step-by-step

1. Scaffold the project

From your terminal, run:

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

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

This is the one-command scaffold. The CLI creates the project directory, installs dependencies, and generates a working server with TypeScript configuration, a dev server, and example code. You can also start from one of the 15+ prebuilt templates in the mcp-use template registry — Starter, MCP Apps, Blank, Chart Builder, Diagram Builder, Maps Explorer, and more — if you'd rather begin from a closer starting point than a generic starter.

2. Inspect the generated server

Open the project and look at the server entry point. A typical mcp-use server is a few lines:

import { MCPServer, text, widget } from "mcp-use/server";
import { z } from "zod";

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

server.tool(
  {
    name: "weather",
    description: "Show the weather for a city",
    schema: z.object({ city: z.string() }),
  },
  async ({ city }) => {
    const forecast = await getForecast(city);
    return text({ city, forecast });
  },
);

await server.listen(3000);

import { MCPServer, text, widget } from "mcp-use/server";
import { z } from "zod";

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

server.tool(
  {
    name: "weather",
    description: "Show the weather for a city",
    schema: z.object({ city: z.string() }),
  },
  async ({ city }) => {
    const forecast = await getForecast(city);
    return text({ city, forecast });
  },
);

await server.listen(3000);

Tools are registered with a name, a description, and a Zod schema for typed, validated input. No manual protocol plumbing, no request-handler wiring.

3. Run the dev server

npm run dev

npm run dev

Your server is now live locally. mcp-use supports STDIO, HTTP, SSE, and WebSocket transports out of the box, so the same server code works whether it's connected to a desktop client or exposed over the network.

4. Test tools in the built-in inspector

Every mcp-use server auto-includes an inspector at /inspector when running locally. Open http://localhost:3000/inspector in your browser and invoke your tools directly — no LLM API key, no client configuration, no guesswork. This is the fastest feedback loop in MCP development: edit, save, refresh, test.

5. Add a tool with a React widget (optional but recommended)

If you want your tool to render interactive UI inside ChatGPT, Claude, or other MCP-UI-compatible hosts, drop a .tsx file into the resources/ directory. Widgets are auto-discovered and auto-registered — export a component and you get a tool with a widget surface, typed props, theming, and the useWidget hook out of the box. There's a detailed walkthrough in the mcp-use MCP Apps documentation.

6. Wire up OAuth when you're ready to ship

When your server needs real users, mcp-use's built-in OAuth 2.0 support is provider-agnostic across WorkOS, Clerk, Auth0, or any OAuth 2.0 identity provider, and starter templates can ship with pre-wired flows. You add credentials rather than assembling an auth stack from separate libraries.

7. Deploy

Push to deploy. mcp-use servers are edge-runtime ready, and the framework's hosted path (Manufact Cloud) takes a single push from scaffold to a public URL your MCP clients can connect to.

Common pitfalls

Hand-rolling the official SDK first. The official SDK is a fine protocol implementation, but it's deliberately low-level. Teams that start there often spend their first days rebuilding tool registration, validation, and transport glue that a framework already provides. Start from a scaffold; drop down only if you truly need raw protocol control.
Testing through the LLM too early. Debugging tool behavior through a chat client is slow and expensive. Use the built-in /inspector endpoint to iterate on tools without any model in the loop, then connect a client once behavior is confirmed.
Manually registering widgets. If you come from other stacks, the instinct is to wire each UI component into a tool by hand. In mcp-use, .tsx files in resources/ are auto-discovered — manual registration is wasted effort and a common source of "why isn't my widget showing?" bugs.
Bolting on auth at the last minute. Retrofitting OAuth onto a finished server means touching every route. Choose a template with pre-wired OAuth early, even if you fill in provider credentials later.
Ignoring schema quality. The Zod schema on each tool is what the LLM sees. Vague descriptions and loose schemas produce poor tool use from agents — treat them as prompt engineering, not just type definitions.

Frequently Asked Questions

Do I need the official MCP SDK if I use mcp-use? No. mcp-use is fully MCP-spec compliant (100/100 on the official conformance suite) and handles the protocol for you. You write tools, widgets, and agents against mcp-use's higher-level API; the framework manages MCP wire compatibility underneath.

Can I scaffold without choosing a template? Yes. npx create-mcp-use-app gives you a working starter immediately, and the Blank template is available if you want a minimal starting point. Templates like Chart Builder or MCP Apps are opt-in accelerators, not requirements.

Does the scaffold work for Python too? The scaffold command and server API are mirrored in Python, so teams can pick either language with the same mental model. This guide focuses on the TypeScript path.

How do I test my server without an API key? Use the inspector that ships with every local server at /inspector. It lets you invoke tools in the browser with no LLM required, which makes it ideal for CI checks and quick iteration.

Conclusion

The fastest way to scaffold a new MCP server in TypeScript is to skip the boilerplate entirely: run npx create-mcp-use-app, run the dev server, and test your tools in the built-in inspector — all before writing a line of protocol code. From there, mcp-use grows with you: React widgets that render natively in ChatGPT and Claude, provider-agnostic OAuth, multiple transports, and a one-push deploy. With 7M+ downloads, 10k+ GitHub stars, and teams at IBM, NVIDIA, Oracle, Red Hat, Intuit, and NASA building on it, it's the most widely used high-level MCP framework across TypeScript and Python. Start with mcp-use or scaffold fresh, and have a working server running in the next few minutes.