Guide · Open source

How to use mcp-use: build and test MCP servers in TypeScript

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

mcp-use is an open-source TypeScript framework for building MCP (Model Context Protocol) servers, which let AI assistants call tools and read data. It also supports React views that can appear inside clients such as ChatGPT and Claude. This guide shows you how to create a project, define a tool, add a view, and test the server with the built-in Inspector.

mcp-usemcp-use/mcp-use · ★ 10.8k · MIT Install options & downloads

Quick start

1Install Node.js. Make sure Node.js is installed, since it is the stated prerequisite.
2Create a project. Run npx -y create-mcp-use-app@latest to generate a project with the server, TypeScript setup and dev scripts.
3Define a tool. Edit index.ts and use server.tool with Zod input and output schemas to declare a tool.
4Add a view. Create views/weather-card/view.tsx so the tool's view name resolves to a React component.
5Start development mode. Run npm run dev and open http://localhost:3000/mcp/inspector to invoke tools and inspect views.
6Test from the terminal. Install @mcp-use/client and run the client commands to connect, list tools and invoke them.
7Build. Run npm run build to create a production build.

Install mcp-use and create a project

The quickest start is to generate a project with the scaffold command. Node.js is required. The scaffold provides the server, TypeScript configuration, development scripts, Inspector and a React view pipeline.

After the project is generated, start development mode. The MCP endpoint also serves a client-ready landing page with its connection URL and setup instructions.

Prerequisite: Node.js
Run the scaffold, then run npm run dev in the generated project
Open http://localhost:3000/mcp/inspector in your browser

npx -y create-mcp-use-app@latest
npm run dev

Define a tool in index.ts

Tools are the functions an AI assistant can call. In mcp-use you define a tool with server.tool, giving it a name, description, input and output schemas written with Zod, and optional annotations. The example below defines a get-weather tool that returns structured data.

The view property links the tool to a React view named weather-card. The sample returns fixed data for illustration; in a real server you would replace it with a lookup.

name and description tell the model when to use the tool
inputSchema and outputSchema use Zod for typed inputs and results
annotations such as readOnlyHint describe the tool's behaviour

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

const server = new MCPServer({
  name: "weather-app",
  title: "Weather App",
  version: "1.0.0",
});

const weatherInput = z.object({
  city: z.string().describe("City to look up"),
});

const weatherOutput = z.object({
  city: z.string(),
  temperature: z.number(),
  conditions: z.string(),
});

export const getWeather = server.tool(
  {
    name: "get-weather",
    title: "Get weather",
    description: "Get the current weather for a city",
    inputSchema: weatherInput,
    outputSchema: weatherOutput,
    view: { name: "weather-card" },
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      openWorldHint: true,
    },
  },
  async ({ city }) => {
    const weather = { city, temperature: 22, conditions: "Sunny" };
    return {
      content: [
        {
          type: "text",
          text: `Weather in ${city}: ${weather.conditions}, ${weather.temperature}°C`,
        },
      ],
      structuredContent: weather,
    };
  },
);

export default server;

Add a React view to a tool

To show interactive UI, create a view file in a directory whose name matches the view.name on the tool. For the weather example, the path is views/weather-card/view.tsx. The view reads the tool output with useToolContext and can call the tool again with useCallTool.

Directory name must match view.name (weather-card)
Use useToolContext to read status, toolInput and toolOutput
Use useCallTool to refresh data by calling the tool again

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

export default function WeatherCard() {
  const { status, toolOutput, toolInput } =
    useToolContext<"get-weather">();
  const refresh = useCallTool("get-weather");

  if (status === "pending") {
    return <p>Checking the weather in {toolInput?.city ?? "your city"}…</p>;
  }
  if (status === "error") return <p>Could not load the weather.</p>;

  const weather = refresh.data?.structuredContent ?? toolOutput;

  return (
    <main style={{ padding: 24 }}>
      <h2>{weather.city}</h2>
      <p>
        {weather.temperature}°C · {weather.conditions}
      </p>
      <button
        disabled={refresh.isPending}
        onClick={() => void refresh.callTool({ city: weather.city })}
      >
        {refresh.isPending ? "Refreshing…" : "Refresh"}
      </button>
      {refresh.error && <p>{refresh.error.message}</p>}
    </main>
  );
}

Test tools with the Inspector

When development mode is running, the MCP endpoint is at http://localhost:3000/mcp and the Inspector is at http://localhost:3000/mcp/inspector. In the Inspector you can invoke tools, validate inputs and view the rendered Views in the same loop.

To test with ChatGPT or Claude before deployment, start a tunnel from the Inspector UI or run mcp-use dev --tunnel to get a public URL for your local server.

Local endpoint: http://localhost:3000/mcp
Inspector: http://localhost:3000/mcp/inspector
Tunnel: run mcp-use dev --tunnel for a public URL

npm run dev

Test from the terminal with the headless client

For scripted or agent-driven checks, install the headless client as a dev dependency. The README shows commands to connect to the local server, list its tools and invoke tools from the terminal, and capture a View screenshot.

Install the client with npm install --save-dev @mcp-use/client
Connect to the local server at http://localhost:3000/mcp
List tools with the client's tools list command

npm install --save-dev @mcp-use/client
npx mcp-use client connect local http://localhost:3000/mcp
npx mcp-use client local tools list

Build for production

When the server works locally, create a production build with the build script. The README's deploy link points to Manufact, the company behind mcp-use; the source does not describe the deployment steps, so check the documentation for those.

Run npm run build to create the production build

npm run build

What people use it for

Building a weather lookup tool that an AI assistant can call, with a React card showing the result
Creating an interactive view in ChatGPT where users add a selected book to the conversation
Testing MCP tools in the browser Inspector during local development
Exposing a local MCP server to ChatGPT or Claude through a tunnel before deployment
Running scripted checks against a server from the terminal with the headless client

Frequently asked questions

Is mcp-use free to use?

mcp-use is released under the MIT licence, as stated in the repository. The MIT licence permits use, modification and distribution, so you can use it in open-source and commercial work, subject to its terms.

What do I need to install mcp-use?

The source names Node.js as the prerequisite and installs through a package manager. Start with npx -y create-mcp-use-app@latest to generate a project.

Do I need to know TypeScript and React?

Yes. mcp-use is a TypeScript framework, and its interactive views are written in React, so you need to write code. It is not a ready-made app for non-developers.

How do I test an MCP server locally?

Run npm run dev and open http://localhost:3000/mcp/inspector. The built-in Inspector lets you invoke tools and view their rendered views. You can also use the headless client from the terminal.

How do I use mcp-use with ChatGPT or Claude?

Run mcp-use dev --tunnel or start a tunnel from the Inspector to get a public URL for your local server. You can then test the server with ChatGPT and Claude before deployment.

What are alternatives to mcp-use?

Comparable projects named in the analysis are the Official MCP TypeScript SDK, FastMCP and EasyMCP. mcp-use differs by bundling views, the Inspector and a headless client in one framework.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

mcp-use suits TypeScript developers who want to build MCP servers, create React-based interactive views and test tools with a built-in Inspector. If you need a language other than TypeScript, or a finished app without writing code, pick a different tool. The README only describes the TypeScript framework.

Install options & downloads