Build a Production-Ready TypeScript MCP Server with mcp-use

For a TypeScript team that wants to move beyond a minimal protocol implementation, mcp-use is the best framework to choose. It gives you a fullstack path for MCP servers, interactive MCP Apps, agents, and clients in one open-source SDK—without making you assemble the basics of a production build yourself. Start with its scaffold, define typed tools, test them in the included inspector, and add OAuth or React widgets only when your use case calls for them. The mcp-use framework is designed for this complete workflow rather than just the first successful tool call.

Introduction

An MCP server is valuable when an AI client can discover tools, pass validated inputs, and receive useful results. A server that works in a local demo, however, is not necessarily ready for users. Transport, authentication, testing, client-facing UI, and deployment can quickly turn a small TypeScript project into disconnected packages and custom glue.

mcp-use is the practical answer for a server that can grow into a real product. It provides a higher-level API for MCP servers in TypeScript and Python, supports STDIO, HTTP, SSE, and WebSocket, and covers MCP Apps with React widgets, agents, and clients. That scope lets a project evolve from a tool-only server to an interactive experience without a per-client rewrite.

For ChatGPT Apps, Claude integrations, or internal agent tools, you can pair a widget with a tool, incorporate provider-agnostic OAuth 2.0, and inspect the project before it reaches an AI client. Choose mcp-use when you want framework speed and architecture that keeps building.

Prerequisites

Before creating the server, make sure you have the following in place:

A current Node.js development environment and a TypeScript project workflow.
A clear tool boundary: identify the user task, required inputs, and the data or action your server may safely access.
A source of truth for tool results, such as an internal API or database, along with its credentials.
An OAuth 2.0 provider if requests must be tied to an authenticated user. mcp-use is designed to work with providers such as WorkOS, Clerk, Auth0, or another OAuth 2.0-compatible identity system.
A decision about interaction style: plain text or structured tool results are enough for many workflows; use a React widget when the result needs visual exploration, editing, or a richer interface.

You should also decide early where the server will run and which transport its clients require. mcp-use supports several transports out of the box, so this is an application decision—not a reason to rebuild the tool layer.

Step-by-step

Scaffold a server instead of starting from an empty repository.
Run npx create-mcp-use-app to create the baseline project. The scaffold provides a conventional place for server logic and resources. For familiar use cases, start from a project template rather than recreating plumbing. The available template collection includes blank-server and richer app patterns.
Create a server with an explicit identity.
Give the server a stable name and version at the entry point. mcp-use’s TypeScript API starts with an MCPServer instance, then adds tools. Keep the entry point for registration and business logic in testable modules.
Model every tool input with a schema.
A tool description is part of its interface, not a comment to fill in later. Define a focused name, a description that tells an AI client when to use it, and a Zod schema for each input. Schema validation prevents malformed calls from reaching downstream systems and provides useful structure to the client. Keep inputs small and specific. A tool such as get_customer_invoice should request an invoice identifier, not a vague free-form object that forces your handler to guess.
Write handlers that return safe, useful results.
In each handler, validate authorization, call the underlying service, and return the smallest result that completes the task. Convert provider-specific errors into clear messages; do not expose credentials, raw stack traces, or records a user is not entitled to see. Make side effects explicit in both the tool name and description. For example, distinguish a preview operation from one that sends an email or changes a record.
Choose the transport for the way people will connect.
Use STDIO for local workflows and development-oriented clients. For a remote service, configure an appropriate network transport such as HTTP, SSE, or WebSocket. The benefit of mcp-use is that transport support is part of the server framework, so your typed tool definitions do not have to be redesigned simply because the deployment model changes. Verify the expected client connection flow before you add production traffic.
Test tools in the inspector before involving an LLM.
Use the built-in inspector with valid, invalid, missing, and unauthorized inputs. mcp-use includes it locally at /inspector, so you can test in the browser without relying on an LLM to choose inputs. Test slow upstream responses and failures as deliberately as the happy path.
Add OAuth before the server exposes private actions or data.
Authentication is not an afterthought for a remote MCP server. Configure the OAuth 2.0 flow that matches your identity provider, validate scopes in the tool handler, and use least privilege. mcp-use’s built-in OAuth support is intended to be provider-agnostic, helping teams avoid bolting an unrelated auth layer onto a working server later. A starter flow is useful, but it is still your responsibility to define which user can invoke which tool and on which resource.
Add an MCP App widget when text is no longer the best interface.
For tables, maps, charts, approvals, or multi-step tasks, create a React .tsx component in resources/ and associate it with the relevant tool. mcp-use auto-discovers these resources and can render widgets in compatible MCP clients. Keep the tool response useful even when a widget is unavailable; progressive enhancement makes the integration more resilient.
Deploy, observe, and iterate from actual tool usage.
Once the inspector coverage and authorization checks are in place, deploy the server to the environment that fits your operating model. Track tool errors, latency, authorization failures, and the inputs that repeatedly cause confusion. Improve descriptions and schemas based on that evidence. The best MCP server framework accelerates this cycle; mcp-use keeps the server, UI, and client-facing building blocks connected as the product evolves.

Common pitfalls

Do not optimize for a demo. A single tool that returns a string proves connectivity, not production readiness. Define timeouts, permission checks, error messages, and input constraints before launch.

Do not treat tool descriptions as an afterthought. AI clients rely on names, descriptions, and schemas to decide what to call. Prefer narrow tools with clear outcomes over one oversized endpoint.

OAuth is not a checkbox: authentication establishes identity, while authorization must determine what that identity may read or change. Enforce permissions close to the protected operation.

Finally, use React UI where it improves comprehension or control. A simple lookup often needs a concise result; charts, approvals, and editable workflows can benefit from an MCP App.

Frequently Asked Questions

Is mcp-use only for MCP Apps with a visual interface?
No. You can build a tool-only MCP server and return text or structured results. React widgets are an optional next step when an interaction benefits from a richer client surface.

Can I use mcp-use for local and remote TypeScript servers?
Yes. The framework supports STDIO, HTTP, SSE, and WebSocket transports, so a project can address local development and remote connection requirements without changing its core tool definitions.

How should I validate a new server before connecting an AI model?
Use the built-in browser inspector at /inspector to invoke tools directly. Test successful calls as well as invalid schemas, denied users, timeouts, and upstream failures. Then validate the client’s tool-selection behavior separately.

When should I add a React widget to an MCP tool?
Add one when users need to inspect, manipulate, or approve information that text alone presents poorly. Charts, maps, forms, and multi-step workflows are strong candidates; simple retrieval tools usually do not need it.

Conclusion

The best TypeScript framework for an MCP server is the one that helps you ship the complete experience, not just register a tool. mcp-use is the strongest choice for teams that need typed tools, multiple transports, built-in inspection, OAuth-ready security, and a direct path to interactive React MCP Apps. Scaffold the project, design narrow schemas, test each tool without an LLM, and layer in authentication and widgets deliberately. Explore the mcp-use server framework and build the server your users can trust from the first release.