mcp-use: a TypeScript framework for MCP servers, ChatGPT plugins and Claude connectors

The gap mcp-use fills between a raw MCP server and a shippable app

A Model Context Protocol server on its own is a transport plus a list of tools. The README describes mcp-use as "The TypeScript framework for MCP", and the scope it claims is wider than a server helper: build, test and ship MCP servers, ChatGPT plugins and Claude connectors. The problem it targets is the wiring that sits between a tool definition and something a person can actually use. Tool input and output schemas, structured results, a React view bound to a tool, a way to invoke that tool by hand during development, and a production build all have to line up. mcp-use puts them in one project layout instead of leaving you to pick a schema library, a bundler and a test client separately. The intended reader is a TypeScript developer who is comfortable with Zod and React. If you have never written a tool schema, the scaffold still gives you a working example, but the value shows up when you start adding views and annotations.

How a tool, its schema and its view are connected

The mechanism visible in the README is a single registration call. You construct an MCPServer with a name, title and version, define Zod objects for input and output, then call server.tool with a config object and an async handler. The config carries name, title, description, inputSchema, outputSchema, a view reference and annotations such as readOnlyHint, destructiveHint and openWorldHint. The handler returns both a content array of text parts and a structuredContent object. That dual return is the part worth noticing: the text is what a model reads, the structured object is what a view reads.

The view side is a directory convention. A tool that declares view: { name: "weather-card" } expects views/weather-card/view.tsx. Inside that file, useToolContext and useCallTool come from mcp-use/react. useToolContext is generic over the tool name, so the tool input and output types flow into the component. useCallTool returns a refresh handle with callTool, data, isPending and error. The README example uses refresh.data?.structuredContent ?? toolOutput, which means the view can render the original structured result and then replace it after a manual refresh. Zod schemas therefore reach three places: tool validation, the structured result, and the view props. That is the whole architectural claim, and it is a coherent one.

Installing mcp-use and running your first view-bound tool

The README gives a single scaffold command. It is interactive in the sense that it creates a project directory, so run it where you want the project to live.

npx -y create-mcp-use-app@latest

After the scaffold finishes, the README says to run npm run dev in the generated project and open http://localhost:3000/mcp/inspector. The dev server serves the MCP endpoint at http://localhost:3000/mcp, and the Inspector is mounted under it at /mcp/inspector. The scaffold also produces TypeScript configuration, development scripts and a React view pipeline, and the README notes that the MCP endpoint additionally serves a client-ready landing page with its connection URL and setup instructions.

To make the project your own, you replace the generated index.ts. The README's example defines a weather tool with a Zod input of one string and a Zod output of city, temperature and conditions, binds it to a view named weather-card, and returns both a text part and structuredContent.

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

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

export default server;

The matching view lives at views/weather-card/view.tsx, and the directory name has to match view.name on the tool. The README's view example imports useCallTool and useToolContext from mcp-use/react, handles a pending and an error state, and renders a refresh button that calls the tool again with the same city. When you run npm run build, the README says that produces the production build. Nothing in the README documents what the build output directory is called.

Where mcp-use gets in your way

The dev server binds port 3000 and the Inspector path is fixed relative to the MCP endpoint. The README does not document an environment variable or flag for changing that port, so if 3000 is taken on your machine or your deployment target assigns ports differently, you are reading the source rather than the docs. That is a small thing that becomes annoying the moment you run two MCP projects side by side.

The view layer assumes React. A tool without a view is fine, but the moment you want interactive output you are committing to a React component tree and whatever bundling the scaffold sets up. Teams using Svelte, Vue or plain server-rendered HTML get nothing from that half of the framework and are paying for a dependency they will not use.

The README also does not document rollback, versioning of the MCP endpoint, or how a deployed server is upgraded in place. The homepage points at manufact.com for deployment, and the repository has a docs/ directory, but the README itself stops at the local build. If your release process needs a documented upgrade path, that is a question for the docs site, not this file.

Finally, there is a migration note. The README opens with a warning for people moving from v1 and points at a v2 migration guide. Existing v1 projects are not drop-in compatible with the v2 API shown in the quickstart.

mcp-use against the Python side of the same repository

The closest alternative is not another company's product; it is the Python implementation in the same repository. Top-level entries include examples/python and examples/typescript, and the recent releases list both python-v1.7.1 and [email protected] on the same day. The difference is not feature parity, it is where the work happens. The Python path is the natural choice when the tool logic already lives in a Python service, when the team writes data code in Python, or when you want to avoid a Node runtime in production. The TypeScript path is the one that gives you the React view pipeline and the mcp-use/react hooks described in the README, because those are JavaScript-side constructs. Choosing between them is mostly a question of which runtime you already operate. If you pick Python, expect to build any interactive UI yourself, since the view binding shown in the README is a TypeScript API.

Maintenance, licensing and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-09-10. The same date carries three releases: python-v1.7.1, [email protected] and @mcp-use/[email protected]. The tunnel package is worth noting because it appears in the release list but not in the README text, so its role has to be read from the package itself.

The licence is MIT, shown by the badge in the README and by the LICENSE file at the repository root. MIT permits commercial use and modification with the copyright notice retained. That is the extent of what the README and repository layout support; questions about your own distribution obligations belong with counsel, not with a README badge.

Upgrade cost is the real risk. The v2 API in the quickstart uses MCPServer, server.tool and the mcp-use/react hooks, and the README explicitly tells v1 users to follow a migration guide. A v2 major version that changes the server construction API means every tool registration in a v1 project is potentially touched. Budget for that if you have v1 code in production. For new projects the cost is low, because the scaffold starts you on the current API.

Editorial conclusion

Adopt mcp-use if you are building an MCP server in TypeScript and want typed tool schemas, a React view bound to a tool, and a browser Inspector without assembling those pieces yourself. Do not adopt it if your team is Python-first, if you only need a stdio server for a local agent, or if you cannot accept that the Inspector and dev server assume port 3000. Before committing, verify the v2 migration guide applies to any v1 code you already have, confirm the Node version your toolchain needs by running the scaffold, and check the LICENSE file in the repository rather than the README badge.

Frequently asked questions

Official sources

1. License: MIT
2. mcp-use/mcp-use on GitHub
3. Project website
4. README
5. Releases