Skip to main content

​
MCP Server

mcp-use has a complete MCP server framework implementation for TypeScript. It improves the official Model Context Protocol SDK with support for Edge Runtime, ChatGPT Apps SDK and MCP-UI. In addition, it supports all official MCP features and achieves a conformance score of 100/100 based on the official MCP Conformance Tests.

​
Key Features

  • Full MCP compatibility: MCP servers built with mcp-use are 100% compatible with the MCP specs.
  • Apps SDK & MCP-UI support: UI widgets are compatible with Apps SDK for ChatGPT and MCP-UI resources. UI Widgets.
  • Edge runtime support: Built-in Edge runtime support
  • Built-in Inspector: An handy MCP inspector is launched for you to test you MCP server.
  • Hot Module Reloading: Add, remove, or update tools, prompts, and resources without restarting the server or dropping connections.
  • One command to get started: Use npx create-mcp-use-app command to scaffold a complete MCP server.

​
Installation

The easiest way to get started is to use the create-mcp-use-app command, which scaffolds a complete MCP server project with all necessary configuration: 
npx create-mcp-use-app my-mcp-server
cd my-mcp-server
npm install
npm run dev
This command will create a new MCP server with:
  • A complete TypeScript MCP server project structure.
  • Example MCP Tools and Resources to get you started.
  • Example UI Widgets React components in resources/ folder exposed as tools and resources in Apps SDK for ChatGPT and MCP-UI format.
  • Pre-configured build tools and dev server.
  • All necessary dependencies installed.
  • MCP Inspector to test your server.

​
Project Structure

After creation, your project will have this structure: 
my-mcp-server/
├── resources/
│   └── component.tsx  # React widgets for Apps SDK and MCP-UI
├── index.ts           # MCP server entry point, you can add tools and rest endpoints here
├── package.json
├── tsconfig.json
└── README.md

​
Running Your MCP Server

Commands: 
yarn dev   # start the development server
yarn build # build the server
yarn start # start the production server
yarn deploy # deploy the server to mcp-use cloud
When you run your MCP server, it will be available at:
  • MCP Endpoint: http://localhost:3000/mcp - For MCP client connections
  • MCP Inspector: http://localhost:3000/inspector

​
Hot Module Reloading (HMR)

The development server supports Hot Module Reloading for tools, prompts, and resources. When you modify your server file, changes are applied instantly without restarting the server or dropping client connections. 
# HMR is enabled by default
npm run dev

# Disable HMR if needed (uses tsx watch instead)
npx mcp-use dev --no-hmr
What HMR does:
  • Add tools/prompts/resources: New registrations appear immediately
  • Update existing ones: Changes to descriptions, schemas, or handlers are applied in-place
  • Remove registrations: Deleted tools/prompts/resources are removed from the server
  • Notify clients: Connected clients (like the Inspector) receive list_changed notifications and auto-refresh
This means you can keep the Inspector open, modify your server code, and see your changes reflected immediately without losing your session.

​
Deploy Your MCP Server

You can deploy your MCP server on any platform. Build your MCP server with npm run build and start the production server with npm run start. Or you can deploy it on mcp-use Cloud. For detailed instructions, see the Deploy Your Server guide.

​
Next Steps

  • Core features: Learn how to create MCP tools, prompts and resources.
  • UI Widgets: Expose UI components to chat clients compatible with ChatGPT Apps SDK and MCP-UI.
  • Configuration: Advanced configuration and deployment options.
  • Deploy Your Server - Deploy to production with one command

​
Manual Installation

If you prefer to set up manually or add mcp-use to an existing project, install the package via npm: 
npm install mcp-use

​
Example server file

The easiest way to start is with create-mcp-use-app, which provides a working example. After running the scaffold command above, your server is ready to go! For manual setup, here’s a minimal example: 
import { MCPServer, text, object } from 'mcp-use/server'
import { z } from 'zod'

// Create server instance
const server = new MCPServer({
  name: 'my-mcp-server',
  version: '1.0.0',
  description: 'My first MCP server',
})

// Define a simple tool
server.tool({
  name: 'greet',
  description: 'Greet someone by name',
  schema: z.object({
    name: z.string().describe('The name of the person to greet'),
  })
}, async ({ name }) => 
    text(`Hello, ${name}! Welcome to MCP.`)
)

// Define a resource
server.resource({
  name: 'config',
  uri: 'config://settings',
  description: 'Server configuration',
}, async () => 
    object({
      theme: 'dark',
      language: 'en'
    })
)

// Start the server
await server.listen(3000)
When you run this server, it will be available at:
  • MCP Endpoint: http://localhost:3000/mcp - For MCP client connections
  • Inspector UI: http://localhost:3000/inspector - Development and testing interface

​
Architecture Overview

The mcp-use server framework is designed around a modular architecture that seamlessly integrates MCP protocol features with Express.js flexibility. Understanding this architecture helps you build powerful, production-ready MCP servers. The framework is built on six fundamental components that work together:

​
Server Instance

The main MCPServer class created via new MCPServer(). It orchestrates all MCP functionality, manages the Express application, and handles client connections. Learn more: See Configuration for server setup options.

​
Tools

Executable functions that MCP clients can invoke with typed parameters. Tools perform actions, fetch data, or trigger operations and return structured results. Learn more: Tools Guide →

​
Resources

Static or dynamic content accessible via URIs. Resources can be configuration files, documentation, data feeds, or any content that clients need to read. Learn more: Resources Guide →

​
Prompts

Reusable, parameterized templates for AI model interactions. Prompts standardize how your server generates context for LLM conversations. Learn more: Prompts Guide →

​
UI Widgets

Rich, interactive React components that render in chat clients. Widgets are automatically registered from your resources/ folder and work with both ChatGPT Apps SDK and MCP-UI. Apps SDK UI Widget Example Key features:
  • Automatic Registration: Drop .tsx files in resources/ and they become MCP tools
  • Zero Boilerplate: No manual server.tool() or server.uiResource() calls needed
  • Hot Module Replacement: Changes reflect instantly during development
  • Type-Safe Props: Zod schemas provide full TypeScript type safety
  • Interactive: Widgets can call tools, manage state, and respond to user actions
Learn more: UI Widgets Guide →

​
Custom Endpoints Integration

Full Express.js and Hono functionality for custom routes, middleware, authentication, static file serving, and more. The server instance is also an Express app. 
// Add custom routes
server.get('/api/mango', (req, res) => {
  res.json({ fruit: 'mango' })
})
Learn more: API Reference →

​
McpServer API

The McpServer class provides a clean, chainable API: 
class McpServer {
  // MCP Protocol Methods
  tool(definition: ToolDefinition): this
  resource(definition: ResourceDefinition): this
  resourceTemplate(definition: ResourceTemplateDefinition): this
  prompt(definition: PromptDefinition): this
  uiResource(definition: UIResourceDefinition): this
  
  listen(port?: number): Promise<void>

  // Hono/Express proxy - all HTTP methods available
  // Examples: get(), post(), use(), static(), route()
}
Additional Features:
  • OAuth Authentication: Configure OAuth providers for secure authentication
  • Sampling: Request LLM completions from the client during tool execution
  • Notifications: Send real-time notifications to connected clients
  • Inspector UI: Interactive debugging interface automatically served at /inspector endpoint

​
Next Steps

Tools

Build executable functions with parameters and validation

Resources

Expose static and dynamic content via URI-based resources

Prompts

Create reusable prompt templates for AI interactions

UI Widgets

Build interactive React components with auto-registration

Configuration

Configure your server for production deployment

Deploy to Production

Deploy your server to mcp-use Cloud with one command