Quickstart

Create an mcp-use app, run it locally, and render its View in the Inspector. The generated project includes a server, two tools, and a React View.

This quickstart uses the mcp-apps template. To build a tool-only server, use --template mcp-server. For an MCP client or agent, start with the MCP Client or MCP Agent documentation.

Prerequisites

Node.js 22.22.2 or later
npm, pnpm, or Bun

Scaffold an mcp-use app

npx create-mcp-use-app@latest my-mcp-app --template mcp-apps --install

pnpm dlx create-mcp-use-app@latest my-mcp-app --template mcp-apps --install

bunx create-mcp-use-app@latest my-mcp-app --template mcp-apps --install

With a project name and --template, the scaffolder does not prompt. --install installs dependencies with the package manager that ran the command; without it, run npm install, pnpm install, or bun install in the project before starting the server. The scaffolder also installs the mcp-apps-builder coding-agent skill, which requires Git. Pass --no-skills to skip it.

Run the development server

cd my-mcp-app
npm run dev

cd my-mcp-app
pnpm dev

cd my-mcp-app
bun run dev

mcp-use dev serves the MCP endpoint at http://localhost:3000/mcp and the Inspector at http://localhost:3000/mcp/inspector. The Inspector opens automatically in an interactive terminal.

Explore the generated project

my-mcp-app/
├── public/
│   ├── icon.svg
│   └── logo-mcp-use.svg
├── views/
│   └── my-view/
│       ├── view.tsx
│       ├── view.css
│       ├── icons.tsx
│       ├── MeshGradient.tsx
│       └── Tooltip.tsx
├── index.ts
├── mcp-env.d.ts
├── package.json
└── tsconfig.json

index.ts creates the server and registers the show-app and say-hello tools.
views/my-view/view.tsx contains the React View rendered by show-app.
mcp-env.d.ts connects exported tool definitions to typed React hooks.
public/ contains assets served by the framework.

Understand the View-bound tool

The generated show-app tool imports from mcp-use, declares inputSchema and outputSchema, and binds the View with view: { name: "my-view" }.

index.ts

import { MCPServer } from "mcp-use";
import { z } from "zod";

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

export const showApp = server.tool(
  {
    name: "show-app",
    description: "Display the starter MCP App",
    inputSchema: z.object({
      appName: z.string().optional().describe("Title shown in the MCP App"),
    }),
    outputSchema: z.object({
      message: z.string().describe("Message displayed by the View"),
    }),
    view: {
      name: "my-view",
      description: "Starter MCP App View",
    },
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      openWorldHint: false,
    },
  },
  async ({ appName }) => {
    const data = {
      message: `The MCP App for ${appName ?? "my project"} is ready!`,
    };

    return {
      content: [{ type: "text", text: data.message }],
      structuredContent: data,
    };
  },
);

export default server;

Assign statically declared tools to exported constants. The generated mcp-env.d.ts uses those exports to type View hooks. Export the server as the default value so the CLI can run, build, and deploy it.

Read tool results in the View

The View directory must match view.name. Use useToolContext() to read the invocation that rendered the View:

views/my-view/view.tsx

import { useToolContext } from "mcp-use/react";

export default function MyView() {
  const view = useToolContext<"show-app">();

  if (view.status === "pending") {
    return <p>Loading the app…</p>;
  }

  if (view.status === "error") {
    return <p role="alert">{view.error.message}</p>;
  }

  return <h2>{view.toolOutput.message}</h2>;
}

When the tool succeeds, view.toolOutput is the typed value returned in structuredContent. The host and model receive the text in content.

Check the project

Run the generated type check after changing tools or Views:

npm run typecheck

pnpm typecheck

bun run typecheck

The command refreshes mcp-env.d.ts and runs TypeScript without emitting build files. You can also call the server from the terminal:

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

Deploy the project

Sign in to Manufact, then deploy the generated project. deploy does not sign you in; without saved credentials or MCP_USE_API_KEY, it exits with Not logged in.

npx mcp-use login
npm run deploy

pnpm exec mcp-use login
pnpm run deploy

bunx mcp-use login
bun run deploy

The first deployment links the local project. See the Manufact deployment guide for environment variables, regions, and subsequent deployments.

Next steps

Tools

Define validated inputs, outputs, annotations, and View-bound results.

MCP Apps

Build production Views and integrate with MCP hosts.

Inspector

Test and debug your server interactively.

Deployment

Publish the server and configure production environments.

Need help? Join our Discord or visit GitHub.

Get Started

MCP Server

MCP Apps

MCP Client

MCP Agent

Tooling

Prerequisites

Scaffold an mcp-use app

Run the development server

Explore the generated project

Understand the View-bound tool

Read tool results in the View

Check the project

Deploy the project

Next steps

Tools

MCP Apps

Inspector

Deployment

​Prerequisites

​Scaffold an mcp-use app

​Run the development server

​Explore the generated project

​Understand the View-bound tool

​Read tool results in the View

​Check the project

​Deploy the project

​Next steps

Tools

MCP Apps

Inspector

Deployment

Prerequisites

Scaffold an mcp-use app

Run the development server

Explore the generated project

Understand the View-bound tool

Read tool results in the View

Check the project

Deploy the project

Next steps