Related Pages

Related topics: Building MCP Servers and Widgets (MCP Apps), MCP Client, Agents, and LLM Adapters, Inspector, CLI, Authentication, and Deployment

Framework Overview and Architecture

mcp-use is an open-source framework for building, running, and consuming servers and agents that speak the Model Context Protocol (MCP). The repository is organized as a polyglot monorepo that ships a TypeScript distribution, a Python distribution, and a set of shared developer tooling packages. The goal of this page is to describe the high-level architecture of the framework, the role of each package, and the workflows developers follow when building MCP servers or wiring MCP tools into LLM agents.

Repository Structure

The repository is split into two primary language trees: libraries/typescript/ and libraries/python/. The TypeScript tree is itself a workspace containing multiple npm packages (mcp-use, @mcp-use/cli, @mcp-use/inspector, create-mcp-use-app), each published independently with its own version. Source: libraries/typescript/README.md.

The Python distribution, mcp_use, focuses on the agent/client side: MCPAgent, MCPClient, and connector classes such as HttpConnector and StdioConnector. Source: libraries/python/README.md.

High-Level Architecture

The framework is layered. At the bottom sits the official MCP SDK; mcp-use wraps it with a friendlier authoring API. Above that, the CLI and inspector provide the developer surface for building, running, and debugging servers. The Python MCPAgent sits alongside as an alternative runtime that drives MCP servers through LangChain-compatible chat models.

flowchart TB
    A[User / LLM Client] --> B[mcp-use Inspector]
    A --> C[MCPAgent - Python]
    C --> D[MCPClient / Connectors]
    B --> E[MCPServer - TypeScript]
    C --> E
    D --> F[MCP Servers stdio / streamable HTTP]
    E --> F
    E --> G[Resources / Tools / Prompts / Widgets]
    F --> H[Underlying MCP SDK]
    H --> I[Transport: stdio, SSE, StreamableHTTP]

The TypeScript MCPServer class is the central authoring primitive. It accepts a name and version and exposes server.tool(), server.resource(), server.resourceTemplate(), and server.prompt() builders that delegate to the underlying MCP SDK. Source: libraries/typescript/packages/mcp-use/src/server/README.md.

Server Framework (TypeScript)

The server package is described as "a developer-friendly wrapper around the official Model Context Protocol (MCP) SDK for creating MCP servers in TypeScript." It adds type-safe schema validation (via Zod), ergonomic result helpers (text, object, array, mix, widget), and resource templates with completable arguments. Source: libraries/typescript/packages/mcp-use/src/server/README.md.

A minimal server boots in a few lines:

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

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

server.tool({
  name: "get_weather",
  schema: z.object({ city: z.string() }),
}, async ({ city }) => text(`Temperature: 72°F, City: ${city}`));

await server.listen(3000);

Source: README.md.

The "everything" example exercises the full surface area of this API: WidgetMetadata, useWidget, useWidgetProps, useWidgetState, useWidgetTheme, ErrorBoundary, callTool, displayMode, safeArea, and theme. Source: libraries/typescript/packages/mcp-use/examples/server/features/everything/README.md.

The server also exposes an elicitation API (ctx.elicit(message, zodSchema) and ctx.elicit(message, url)) for collecting structured or URL-based user input, with form mode for non-sensitive data and URL mode for credentials. Source: libraries/typescript/packages/mcp-use/examples/server/features/elicitation/README.md.

Development Workflow

The CLI orchestrates the dev loop. In dev mode it compiles TypeScript in watch mode, builds UI widgets with hot reload, restarts the server via tsx on changes, and auto-opens the inspector at http://localhost:3000/inspector with the MCP endpoint at /mcp. Source: libraries/typescript/packages/cli/README.md.

The CLI is also where server lifecycle operations live: mcp-use dev, mcp-use build, mcp-use start, and mcp-use deploy. The servers update subcommand mutates server configuration in place — production branch, name, description, build/start commands — preserving URL slug and environment variables. Source: release notes for @mcp-use/[email protected].

Scaffolding a new project is handled by create-mcp-use-app, which installs mcp-use, @mcp-use/cli, @mcp-use/inspector, typescript, tsx, and @types/node, and accepts GitHub repository templates (e.g., --template owner/repo#branch). Source: libraries/typescript/packages/create-mcp-use-app/README.md.

Agent Runtime (Python)

The Python distribution centers on MCPAgent and MCPClient. The agent reasons across multiple steps, selects and executes tools from MCP servers, and works with any LangChain chat model that supports tool calling. Connectors (HttpConnector, StdioConnector) handle transport-specific concerns, and the community has requested per-connector callbacks, auth, and middleware configuration as a unified refactor. Source: libraries/python/README.md; referenced in issue #947.

Known Issues and Community Considerations

Several recurring themes appear in the issue tracker:

• Transport hang in mcp-use dev — Stateful StreamableHTTP transport can drop SSE responses in dev mode; switching to enableJsonResponse works around it. Source: issue #1724.
• Empty resources/ noise — When a project has no resources/ directory, the widget mounting pipeline still emits logs. Source: issue #1727.
• Adapter duplication — AnthropicMCPAdapter, OpenAIMCPAdapter, and GoogleMCPAdapter share copy-pasted helpers like _sanitize_for_tool_name and the prompt-schema building loop. Source: issue #1726.
• OAuth metadata — Authorization servers with path-suffix issuers were broken under RFC 8414; fixed in [email protected] (commit 8d626cb). Source: release notes.
• Inspector OAuth error UX — Authorization errors render a raw stack trace instead of redirecting back to the inspector. Source: issue #1362.
• Inspector bundle bloat — @mcp-use/[email protected] introduced hard LangChain transitive dependencies, breaking Next.js and other bundlers. Source: issue #1371.

See Also

• TypeScript Server API (libraries/typescript/packages/mcp-use/src/server/README.md)
• CLI Reference (libraries/typescript/packages/cli/README.md)
• Inspector Guide (libraries/typescript/packages/inspector/README.md)
• Python Agent Quickstart (libraries/python/README.md)
• Release Notes ([email protected])

Related Pages

Related topics: Framework Overview and Architecture, Inspector, CLI, Authentication, and Deployment

Building MCP Servers and Widgets (MCP Apps)

Overview

MCP Apps is the umbrella term used by mcp-use for building Model Context Protocol (MCP) servers together with interactive, cross-client UI widgets. The framework is marketed as "write once, run everywhere" — a single TypeScript codebase is intended to render correctly in Claude, ChatGPT, and other MCP-compatible hosts (libraries/typescript/packages/mcp-use/README.md). The TypeScript distribution is organized into a small set of coordinated packages: the core mcp-use SDK, the @mcp-use/cli build tool, the @mcp-use/inspector debugger, and the create-mcp-use-app scaffolder (libraries/typescript/README.md). A parallel Python distribution exists for the client/agent side, but server + widget authoring is TypeScript-first.

The unit of delivery is an MCP server process that exposes tools, resources, prompts, and UI resources. Tools are invoked by the host LLM; resources and prompts are read by the client; UI resources are rendered inside the chat surface. The MCPServer class is the developer-friendly wrapper around the official MCP SDK that wires all of these primitives together (libraries/typescript/packages/mcp-use/src/server/README.md).

Server Architecture

A minimal server can be written in a few lines. The exported entry point mcp-use/server provides MCPServer and helper return constructors such as text:

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

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

server.tool({
  name: "get_weather",
  description: "Get weather for a city",
  schema: z.object({ city: z.string() }),
}, async ({ city }) => text(`Temperature: 72°F, City: ${city}`));

await server.listen(3000);

Source: libraries/typescript/packages/mcp-use/README.md.

The server module re-exports its sub-modules under clear paths: ./server, ./adapters, ./agent, ./auth, ./browser, ./react, and the browser-only agent bundle ./browser/agent (libraries/typescript/packages/mcp-use/package.json). The MCPServer API supports four core registrations, each demonstrated in the example suite:

The elicitation example highlights two patterns the server can use to gather information: form mode (Zod-validated structured data for non-sensitive preferences) and URL mode (redirecting the user out-of-band for credentials, API keys, or OAuth). Both forms are server-side validated and the result is fully typed through the Zod schema inference (libraries/typescript/packages/mcp-use/examples/server/features/elicitation/README.md). Elicitation runs on [email protected], which is the same version pinned across the ecosystem (libraries/typescript/packages/mcp-use/examples/server/features/elicitation/package.json).

Widget Development

Widgets are the visual half of an MCP App. They live as React components alongside the server, are bundled by the CLI, and are mounted into the host UI as UI resources. The model-context example shows the canonical dependency set: React 19, react-router 7, Tailwind 4, and Vite, all wired through the mcp-use dev / mcp-use build / mcp-use start scripts (libraries/typescript/packages/mcp-use/examples/server/ui/model-context/package.json). The starter template that create-mcp-use-app ships uses the same React/tailwind combination (libraries/typescript/packages/create-mcp-use-app/src/templates/starter/package.json).

The CLI expects a resources/ directory for widget sources. In development, the dev pipeline runs even when that directory does not exist, which historically produced confusing log output for non-widget projects. Community issue #1727 tracks a fix that gates the "[WIDGETS] Mounting widgets in development mode" log behind an actual presence check (issues/1727). A second active request, #1296, asks for streaming of tool *output* into widget props — currently only model-token streaming into tool input is plumbed all the way through to the UI (issues/1296). The streaming-props example in the feature suite is the existing reference implementation for the input-side path (libraries/typescript/packages/mcp-use/examples/README.md).

The example suite is split into agent/ (client/agent patterns) and server/ (server patterns). Server examples are further grouped into basic/, features/ (everything, conformance, elicitation, sampling, notifications, completion, streaming-props, middleware, express-middleware, session-management, proxy, client-info), and ui/ (widget patterns such as model-context) (libraries/typescript/packages/mcp-use/examples/README.md). The top-level examples README clarifies that *in-repo* examples are illustrative code samples; ready-to-deploy apps live in standalone template repositories (examples/README.md).

Development Tooling

The mcp-use CLI is the build orchestrator. It accepts Node 20.19+ or 22.12+, and requires React 18/19 plus react-router-dom 7.12+ as peer dependencies — these are the runtime expectations for any app that ships widgets (libraries/typescript/packages/cli/package.json). Standard scripts in every scaffolded project are:

"scripts": {
  "dev":   "mcp-use dev",
  "build": "mcp-use build",
  "start": "mcp-use start",
  "deploy":"mcp-use deploy"
}

Source: libraries/typescript/packages/create-mcp-use-app/src/templates/starter/package.json and libraries/typescript/packages/mcp-use/examples/server/ui/model-context/package.json.

mcp-use dev boots the server, the Vite dev client, and the inspector in one process. The inspector (@mcp-use/inspector, currently 10.x) is a web-based debugger that mounts at /inspector on the server port and is also published as the mcp-inspect binary for ad-hoc connections to external servers (libraries/typescript/packages/inspector/package.json, libraries/typescript/packages/inspector/README.md). The scaffolder create-mcp-use-app accepts either a built-in template name or a GitHub owner/repo reference, and clones the target repo to bootstrap the new project (libraries/typescript/packages/create-mcp-use-app/README.md).

flowchart LR
  A[Author src/index.ts] --> B[mcp-use dev]
  B --> C[MCPServer on :3000]
  B --> D[Vite dev client :port]
  B --> E[Inspector at /inspector]
  C -->|HTTP/Streamable| F[MCP host: Claude / ChatGPT]
  F -->|tool calls| C
  C -->|UI resources| G[React widget bundle]
  B --> H[Edit widget] --> B
  C --> I[mcp-use build] --> J[Production dist]

Common failure modes to be aware of:

• Stateful StreamableHTTP hangs in dev — tool results may never reach the client over SSE in some stateful transport configurations; setting enableJsonResponse is a known workaround (issues/1724).
• Inspector OAuth errors — the inspector previously rendered a raw error page on access_denied/server_error; the expected behavior is to redirect back with the error attached (issues/1362).
• Bundler/LangChain bloat — older versions of the inspector pulled @langchain/* transitively and broke Next.js bundlers; pin or upgrade the inspector separately if you hit this (issues/1371).

See Also

• libraries/typescript/packages/mcp-use/src/server/README.md — full MCPServer API reference
• libraries/typescript/packages/mcp-use/examples/README.md — index of every example, including all server features
• examples/README.md — distinction between in-repo samples and standalone deployable templates
• libraries/typescript/packages/create-mcp-use-app/README.md — scaffolder flags and GitHub template support
• libraries/typescript/packages/inspector/README.md — inspector usage, self-hosting, and OAuth error handling

Related Pages

Related topics: Framework Overview and Architecture, Building MCP Servers and Widgets (MCP Apps)

MCP Client, Agents, and LLM Adapters

Overview

The mcp-use monorepo provides a layered stack for working with the Model Context Protocol (MCP). Three components sit on the client side of that stack and are exported as the public surface that application code interacts with: the MCPClient (a transport-aware connection manager), the MCPAgent (an LLM-driven reasoning loop that uses MCP tools), and the LLM Adapters (provider-specific glue that normalizes tool and prompt schemas for OpenAI, Anthropic, Google, and LangChain-compatible runtimes). Both the TypeScript and Python distributions expose parallel abstractions under the same names, with the TypeScript package re-exporting them through dedicated subpaths (./adapters, ./agent, ./auth, ./browser/agent). Source: libraries/typescript/packages/mcp-use/package.json.

flowchart LR
    LLM[LLM Provider<br/>OpenAI / Anthropic / Google] -->|Adapter normalizes<br/>tools + prompts| Adapter[LLM Adapter<br/>./adapters]
    Adapter --> Agent[MCPAgent<br/>./agent]
    Agent -->|tool call| Client[MCPClient]
    Client -->|stdio / http / ws| S1[MCP Server A]
    Client -->|stdio / http / ws| S2[MCP Server B]
    Client -->|stdio / http / ws| S3[MCP Server C]
    Agent -->|final answer| User[Application / User]

MCPClient: Connection Manager

The MCPClient is the transport-layer facade used to discover and connect to one or more MCP servers. The README documents a fromDict() factory that takes a dictionary of server configurations and a command/args/env shape, matching the canonical MCP server descriptor format. The same documentation explicitly lists "Multi-Server" support, "HTTP Support", and "Tool Control" (restricting the set of tools visible to the agent) as first-class features. Source: libraries/typescript/README.md.

In Python, the same surface is described in the Python README: a MCPClient accepts a configuration dictionary, the MCPAgent is created with an LLM plus a client, and a maxSteps cap bounds the reasoning loop. Source: libraries/python/README.md.

A persistent community request is to give each connector its own typed callbacks, auth, and middleware configuration — currently, transport-specific concerns are spread across HttpConnector and StdioConnector. The accepted proposal in issue #947 makes name a required unique identifier and introduces typed authentication, which the docs should reflect once merged. Source: issue #947.

MCPAgent: Reasoning Loop

The MCPAgent wraps an LLM and an MCPClient, exposes a run() method that accepts a natural-language goal, and iterates up to maxSteps times — selecting tools, executing them through the client, and feeding the result back to the LLM until the model produces a final answer. Source: libraries/python/README.md.

The in-repo examples catalogue the agent patterns users are expected to adopt:

• Basic — chat_example.ts (built-in memory), mcp_everything.ts (full primitive coverage), simplified_agent_example.ts. Source: libraries/typescript/packages/mcp-use/examples/README.md.
• Advanced — observability.ts (Langfuse instrumentation), stream_example.ts (streaming intermediate steps), structured_output.ts (schema-aware retries).
• Code Mode — code_mode_example.ts and code_mode_e2b_example.ts (executing MCP tools inside an E2B remote sandbox).
• Server features consumed by the agent — sampling (ctx.sample()) and elicitation (ctx.elicit() in form and URL modes). Source: libraries/typescript/packages/mcp-use/examples/server/features/elicitation/README.md.

Streaming intermediate steps is the documented way to surface tool progress to a UI; the community has asked for an extension of that pattern so tool *output* (not just model token streaming) can flow into widget props (issue #1296). Until that lands, agents that drive MCP Apps can only stream model tokens into the widget input.

LLM Adapters

LLM Adapters translate MCP tool and prompt definitions into the native function-calling schema that each provider expects. The TypeScript package exports them through the dedicated ./adapters subpath, while the ./agent subpath hosts the agent runtime. Source: libraries/typescript/packages/mcp-use/package.json.

Because each provider has its own quirks (tool name character sets, prompt schema shape, JSON-mode behavior), the adapters historically contained copy-pasted logic. Issue #1726 specifically flags _sanitize_for_tool_name and the prompt-schema building loop in _convert_prompt as identical across AnthropicMCPAdapter, OpenAIMCPAdapter, and GoogleMCPAdapter, and proposes a shared base class. Source: issue #1726.

LLM flexibility is the headline capability: the TypeScript README advertises that the agent works with "OpenAI, Anthropic, Google, or any LangChain-supported LLM", while the Python README warns that "only models with tool calling capabilities can be used with mcp_use" and instructs users to install the matching LangChain provider package. Source: libraries/typescript/README.md, libraries/python/README.md.

Known Failure Modes and Community Friction

Several open issues shape how these components behave in practice:

• Stateful StreamableHTTP hangs in mcp-use dev: tool handlers complete on the server but the SSE response is dropped, leaving the inspector waiting forever. Setting enableJsonResponse: true works around it. Source: issue #1724.
• Transitive LangChain dependency: @mcp-use/[email protected] drags @langchain/core, @langchain/openai, @langchain/anthropic, and @langchain/google-genai into every consumer of [email protected], breaking Next.js and other bundlers. Source: issue #1371.
• OAuth metadata discovery: mcp-use 1.32.1-canary.2 ships an RFC 8414 fix for authorization servers with path-suffix issuers, closing #1576. Source: release notes.
• CLI subscription lifecycle: Ctrl+C in resources subscribe did not send an unsubscribe frame, fixed by #1723. Source: issue #1723.

See Also

• MCP Server framework: libraries/typescript/packages/mcp-use/src/server/README.md
• Inspector package: libraries/typescript/packages/inspector/README.md
• Top-level TypeScript monorepo overview: libraries/typescript/README.md
• Python client and agent: libraries/python/README.md
• In-repo examples index: examples/README.md

Related Pages

Related topics: Framework Overview and Architecture, Building MCP Servers and Widgets (MCP Apps)

Inspector, CLI, Authentication, and Deployment

The mcp-use ecosystem ships a coherent set of developer tools around the core MCP framework: the Inspector for debugging servers and widgets, the mcp-use CLI for the dev/build/deploy workflow, OAuth-based authentication primitives baked into the server runtime, and deployment commands for hosting MCP Apps. This page documents how those four concerns fit together, how to use them, and where the community has run into sharp edges.

The MCP Inspector

The Inspector is a self-hosted web UI for browsing tools, resources, prompts, and widgets exposed by an MCP server. Source: libraries/typescript/packages/inspector/README.md

It exposes a Tool Explorer (browse and execute tools with schema validation), Resource Browser (URI browsing with syntax highlighting), Prompt Manager, BYOK Chat (bring-your-own-key conversational testing), Saved Tool Calls, and a Widget Support view for MCP-UI / OpenAI Apps SDK widgets. Source: libraries/typescript/packages/inspector/README.md

There are three ways to launch the Inspector:

1. Online version at inspector.mcp-use.com for quick testing.
2. Local standalone via npx @mcp-use/inspector, which opens http://localhost:8080.
3. Auto-mounted by any mcp-use server: await server.listen(3000) exposes the inspector at http://localhost:3000/inspector. Source: libraries/typescript/packages/inspector/README.md, libraries/typescript/packages/mcp-use/README.md

The Inspector package exports both a server entry (./dist/server/index.js) and a client bundle (./dist/client/index.js) through its exports field, and ships a mcp-inspect CLI binary. Source: libraries/typescript/packages/inspector/package.json

Telemetry

The Inspector collects anonymized product analytics through PostHog and package download metrics through Scarf. Opt-out is supported via the MCP_USE_ANONYMIZED_TELEMETRY=false environment variable, a localStorage flag (mcp_inspector_telemetry_disabled), or the scarfSettings.enabled package option. Source: libraries/typescript/packages/inspector/README.md

Known Issues

• Bundler breakage from langchain transitive deps — @mcp-use/[email protected] historically pulled @langchain/* packages as hard dependencies, breaking Next.js/bundler consumers (issue #1371). Newer inspector majors (currently 10.x) ship independently.
• OAuth error rendering — When an authorization server returns an error such as access_denied, the Inspector previously rendered a raw stack trace in the DOM rather than redirecting back to the inspector (issue #1362).
• Stateful StreamableHTTP hangs in dev — Tool results from the inspector can hang indefinitely under stateful StreamableHTTP transports because the SSE response is dropped after the handler completes (issue #1724). Switching to enableJsonResponse: true is the documented workaround.

CLI Workflow

The @mcp-use/cli package wraps the full local lifecycle and provides production commands. Source: libraries/typescript/packages/cli/README.md

mcp-use dev     # TypeScript watch + widget HMR + auto-restart + auto-open inspector
mcp-use build   # Compile TS to JS, bundle .tsx in resources/ for production
mcp-use start   # Run the compiled production server
mcp-use deploy  # Ship to the Manufact platform
mcp-use servers update <id-or-slug>  # In-place server config mutation

`mcp-use dev`

In development mode, TypeScript files are compiled in watch mode, resources/ widgets are built with hot module replacement, the server auto-restarts on change (via tsx), and the Inspector automatically opens at http://localhost:3000/inspector. The MCP endpoint itself is mounted at http://localhost:3000/mcp. Source: libraries/typescript/packages/cli/README.md

Options include -p/--path <project-dir> (default .), --port <port> (default 3000), and --no-open to suppress the browser launch. Source: libraries/typescript/packages/cli/README.md

`servers update` and environment management

The 3.5.0 release of @mcp-use/cli introduced mcp-use servers update <id-or-slug>, which mutates server config in place — production branch, name, description, build/start commands — without deleting and recreating the server. The --branch flag maps CLI invocations onto branch-scoped environments, preserving the URL slug and environment variables. Source: Release: @mcp-use/cli 3.5.0

Known Issues

• Empty resources/ directory noise — When a project doesn't use widgets, the widget mounting pipeline still runs in mcp-use dev and emits a confusing sequence of [WIDGETS] messages about creating the directory (issue #1727).
• Ctrl+C doesn't unsubscribe resources — The CLI's resources subscribe mode previously did not send notifications/cancelled on Ctrl+C, leaving dangling subscriptions on the server side (issue #1723, see also #1686).

Authentication

The mcp-use framework ships first-class OAuth support, with both server-side and browser-side providers. Source: libraries/typescript/packages/mcp-use/package.json

The package exposes dedicated entry points:

• mcp-use/auth — base auth primitives
• mcp-use/auth/node — Node.js provider
• mcp-use/browser — browser OAuth provider with session store

Source: libraries/typescript/packages/mcp-use/package.json

Recent OAuth additions

• token_endpoint exposure (1.32.0) — The browser OAuth provider now exposes the resolved token_endpoint via getTokenEndpoint() and surfaces it on useMcp().authTokens. This lets consumers persist the token endpoint alongside access/refresh tokens so a backend can proactively refresh before expiry. Source: Release: mcp-use 1.32.0
• RFC 8414 path-suffix issuers (1.32.1-canary.2) — Upstream OAuth/OpenID metadata URLs are now constructed correctly for authorization servers whose issuer carries a path suffix, and the canonical /.well-known/oauth-authorization-server{issuer-path} route is mounted on the proxy. Source: Release: mcp-use 1.32.1-canary.2
• Outgoing notification logging (1.32.1-canary.1) — Server-side logs now print details (session ID, error) for sent and failed notifications, which is especially useful when debugging OAuth handshake timing. Source: Release: mcp-use 1.32.1-canary.1

The public-landing-page example demonstrates the canonical integration: an OAuth-protected MCP server that also exposes a public browser landing page. Source: libraries/typescript/packages/mcp-use/examples/server/features/public-landing-page/package.json

For non-OAuth interactive flows, the framework also supports elicitation — servers can request structured input via ctx.elicit(message, zodSchema) or direct users to external URLs for sensitive interactions like API keys. Source: libraries/typescript/packages/mcp-use/examples/server/features/elicitation/README.md

Deployment

mcp-use deploy publishes an MCP App to the Manufact platform, while mcp-use build prepares an optimized production bundle with hashed assets for caching. TypeScript compilation is part of the production build, and the resulting artifacts are served via mcp-use start. Source: libraries/typescript/packages/cli/README.md

New projects are scaffolded with npx create-mcp-use-app@latest, which installs mcp-use, @mcp-use/cli, and @mcp-use/inspector and provisions a dev, build, start, and deploy script set. Source: libraries/typescript/packages/create-mcp-use-app/README.md, README.md

Server management on the platform is handled through mcp-use servers ... sub-commands, including the branch-scoped environment model introduced in CLI 3.5.0. Source: Release: @mcp-use/cli 3.5.0

flowchart LR
  A["create-mcp-use-app"] --> B["mcp-use dev"]
  B -. hot reload .-> B
  B --> C["mcp-use build"]
  C --> D["mcp-use start"]
  C --> E["mcp-use deploy"]
  E --> F["Manufact platform"]
  F -- "servers update --branch" --> F
  B -. inspector .-> G["/inspector"]

See Also

• TypeScript Server Documentation
• Inspector Documentation
• Inspector Self-Hosting Guide
• CLI Documentation
• Templates gallery
• Issue #262 — community wishlist (mcp-use feature requests)

Doramagic Pitfall Log

Found 29 structured pitfall item(s), including 4 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/mcp-use/mcp-use/issues/1727

2. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/mcp-use/mcp-use/issues/1726

3. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/mcp-use/mcp-use/issues/1724

4. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/mcp-use/mcp-use/issues/947

5. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Example: Chart Library MCP for financial pattern analysis
• User impact: Developers may fail before the first successful local run: Example: Chart Library MCP for financial pattern analysis
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Example: Chart Library MCP for financial pattern analysis. Context: Observed when using python
• Evidence: failure_mode_cluster:github_issue | https://github.com/mcp-use/mcp-use/issues/1286

6. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/mcp-use/mcp-use/issues/1286

7. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | github_repo:956472076 | https://github.com/mcp-use/mcp-use

8. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: @mcp-use/cli 3.5.0
• User impact: Upgrade or migration may change expected behavior: @mcp-use/cli 3.5.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: @mcp-use/cli 3.5.0. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/mcp-use/mcp-use/releases/tag/%40mcp-use/cli%403.5.0

9. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: Refactor HttpConnector and StdioConnector with per-connector configuration
• User impact: Developers may misconfigure credentials, environment, or host setup: Refactor HttpConnector and StdioConnector with per-connector configuration
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Refactor HttpConnector and StdioConnector with per-connector configuration. Context: Observed when using python, playwright
• Evidence: failure_mode_cluster:github_issue | https://github.com/mcp-use/mcp-use/issues/947

10. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: mcp-use 1.32.0
• User impact: Upgrade or migration may change expected behavior: mcp-use 1.32.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: mcp-use 1.32.0. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/mcp-use/mcp-use/releases/tag/mcp-use%401.32.0

11. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: mcp-use 1.32.1-canary.2
• User impact: Upgrade or migration may change expected behavior: mcp-use 1.32.1-canary.2
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: mcp-use 1.32.1-canary.2. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/mcp-use/mcp-use/releases/tag/mcp-use%401.32.1-canary.2

12. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | github_repo:956472076 | https://github.com/mcp-use/mcp-use

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using mcp-use with real data or production workflows.

• Refactor: adaptor deduplicate across MCP adapters - github / github_issue
• Confusing Logs for empty resources/ folder - github / github_issue
• Stateful StreamableHTTP transport hangs in mcp-use dev — tool result nev - github / github_issue
• fix(cli): send unsubscribe on Ctrl+C in resources subscribe - github / github_issue
• Example: Chart Library MCP for financial pattern analysis - github / github_issue
• Refactor HttpConnector and StdioConnector with per-connector configurati - github / github_issue
• mcp-use 1.32.1-canary.2 - github / github_release
• @mcp-use/inspector 10.0.1-canary.2 - github / github_release
• @mcp-use/cli 3.5.2-canary.2 - github / github_release
• mcp-use 1.32.1-canary.1 - github / github_release
• mcp-use 1.32.0 - github / github_release
• Configuration risk requires verification - GitHub / issue