Skip to main content

​
MCP Server Framework

mcp-use is the complete MCP server framework for TypeScript. It combines the official Model Context Protocol SDK with Express.js and React to enable both MCP protocol communication and HTTP endpoints for UI widgets and custom routes. You can expose UI components to chat clients like ChatGPT, Claude, and MCP-UI compatible ones.

​
Key Features

  • Full MCP compatibility: MCP servers built with mcp-use are 100% compatible with the MCP specs.
  • UI Widgets in React: mcp-use automatically registers all React components in your resources/ folder as MCP tools and resources.
  • Apps SDK & MCP-UI support: UI widgets are compatible with Apps SDK for ChatGPT and MCP-UI resources. UI Widgets.
  • Express Integration: Built-in Express server for HTTP endpoints, static file serving, and custom routes.
  • Built-in Inspector: An handy MCP inspector is launched for you to test you MCP server.
  • 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@latest my-mcp-server
cd my-mcp-server
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.ts # MCP-UI / OpenAI Apps SDK example
├── index.ts   # MCP server entry point
├── package.json
├── tsconfig.json
└── README.md

​
Running Your MCP Server

Commands: 
npm run dev   # start the development server
npm run build # build the server
npm run start # start the production server
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 - It will automatically launch an MCP Inspector for you to test you MCP server.

​
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.

​
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.

​
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
For development and testing, you can also install the optional inspector UI: 
npm install --save-dev @mcp-use/cli

​
Quick Start

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 { createMCPServer } from 'mcp-use/server'

// Create server instance
const server = createMCPServer('my-mcp-server', {
  version: '1.0.0',
  description: 'My first MCP server',
  baseUrl: process.env.MCP_URL || "http://localhost:3000"
})

// Define a simple tool
server.tool({
  name: 'greet',
  description: 'Greet someone by name',
  inputs: [
    { name: 'name', type: 'string', required: true }
  ],
  cb: async ({ name }) => {
    return {
      content: [
        {
          type: 'text',
          text: `Hello, ${name}! Welcome to MCP.`
        }
      ]
    }
  }
})

// Define a resource
server.resource({
  name: 'config',
  uri: 'config://settings',
  mimeType: 'application/json',
  description: 'Server configuration',
  readCallback: async () => ({
    contents: [{
      uri: 'config://settings',
      mimeType: 'application/json',
      text: JSON.stringify({
        theme: 'dark',
        language: 'en'
      })
    }]
  })
})

// Start the server
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 (if @mcp-use/inspector is installed)

​
Architecture Overview

The MCP server framework is built on several core concepts:

​
1. Server Instance

The main server object created via createMCPServer(). It manages all MCP functionality and HTTP endpoints.

​
2. Tools

Functions that MCP clients can invoke with parameters. Tools perform actions and return results.

​
3. Resources

Static or dynamic content that clients can read. Resources can be simple files or complex data structures.

​
4. Prompts

Template-based prompt generation for AI models, accepting parameters to create structured prompts.

​
5. UI Resources

Interactive widgets that can be embedded in web applications, supporting both MCP-UI and OpenAI Apps SDK formats.

​
6. Express Integration

Full access to Express.js functionality for adding custom routes, middleware, and static file serving.

​
Core Components

​
McpServer Class

The main server class that orchestrates all functionality: 
class McpServer {
  constructor(config: ServerConfig)

  // MCP Protocol Methods
  tool(definition: ToolDefinition): this
  resource(definition: ResourceDefinition): this
  resourceTemplate(definition: ResourceTemplateDefinition): this
  prompt(definition: PromptDefinition): this
  uiResource(definition: UIResourceDefinition): this

  // Server Control
  listen(port?: number): Promise<void>

  // Express proxy - all Express methods available
  // e.g., server.get(), server.post(), server.use()
}

​
Type System

The framework provides comprehensive TypeScript types for all components:
  • ServerConfig - Server configuration
  • ToolDefinition - Tool configuration and callbacks
  • ResourceDefinition - Resource configuration and read callbacks
  • PromptDefinition - Prompt template configuration
  • UIResourceDefinition - UI widget configuration
  • InputDefinition - Parameter definitions for tools and prompts

​
MCP Protocol Support

The server fully implements the MCP protocol specification:
  • Transport: HTTP with Server-Sent Events (SSE) for streaming
  • Tools: Function execution with typed parameters
  • Resources: Content serving with MIME types and annotations
  • Prompts: Template-based prompt generation
  • Resource Templates: Dynamic resource generation with URI parameters

​
UI Widget System

The framework supports multiple UI widget formats:

​
MCP-UI Widgets

  • External URL widgets (iframe-based)
  • Raw HTML widgets
  • Remote DOM scripting

​
OpenAI Apps SDK

  • Text/HTML+Skybridge format
  • Widget CSP configuration
  • Tool output templates

​
Next Steps