MCP-Use: The Complete TypeScript Framework for Model Context Protocol

Build powerful AI agents, create MCP servers with UI widgets, and debug with built-in inspector - all in TypeScript

---

🎯 What is MCP-Use?

MCP-Use is a comprehensive TypeScript framework for building and using Model Context Protocol (MCP) applications. It provides everything you need to create AI agents that can use tools, build MCP servers with rich UI interfaces, and debug your applications with powerful developer tools.

📦 Packages Overview

Package	Description	Version	Downloads
mcp-use	Core framework for MCP clients and servers
@mcp-use/cli	Build tool with hot reload and auto-inspector
@mcp-use/inspector	Web-based debugger for MCP servers
create-mcp-use-app	Project scaffolding tool

---

🚀 Quick Start

Get started with MCP-Use in under a minute:

# Create a new MCP application
npx create-mcp-use-app my-mcp-app

# Navigate to your project
cd my-mcp-app

# Start development with hot reload and auto-inspector
npm run dev

Your MCP server is now running at http://localhost:3000 with the inspector automatically opened in your browser!

---

📚 Package Documentation

mcp-use: Core Framework

The heart of the MCP-Use ecosystem - a powerful framework for building both MCP clients and servers.

As an MCP Client

Connect any LLM to any MCP server and build intelligent agents:

import { MCPClient, MCPAgent } from 'mcp-use'
import { ChatOpenAI } from '@langchain/openai'

// Configure MCP servers
const client = MCPClient.fromDict({
  mcpServers: {
    filesystem: {
      command: 'npx',
      args: ['@modelcontextprotocol/server-filesystem']
    },
    github: {
      command: 'npx',
      args: ['@modelcontextprotocol/server-github'],
      env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN }
    }
  }
})

// Create an AI agent
const agent = new MCPAgent({
  llm: new ChatOpenAI({ model: 'gpt-4' }),
  client,
  maxSteps: 10
})

// Use the agent with natural language
const result = await agent.run(
  'Search for TypeScript files in the project and create a summary'
)

Key Client Features:

• 🤖 LLM Agnostic: Works with OpenAI, Anthropic, Google, or any LangChain-supported LLM
• 🔄 Streaming Support: Real-time streaming with stream() and streamEvents() methods
• 🌐 Multi-Server: Connect to multiple MCP servers simultaneously
• 🔒 Tool Control: Restrict access to specific tools for safety
• 📊 Observability: Built-in Langfuse integration for monitoring
• 🎯 Server Manager: Automatic server selection based on available tools

As an MCP Server Framework

Build your own MCP servers with automatic inspector and UI capabilities:

import { createMCPServer } from 'mcp-use/server'
import { z } from 'zod'

// Create your MCP server
const server = createMCPServer('weather-server', {
  version: '1.0.0',
  description: 'Weather information MCP server'
})

// Define tools with Zod schemas
server.tool('get_weather', {
  description: 'Get current weather for a city',
  parameters: z.object({
    city: z.string().describe('City name'),
    units: z.enum(['celsius', 'fahrenheit']).optional()
  }),
  execute: async ({ city, units = 'celsius' }) => {
    const weather = await fetchWeather(city, units)
    return {
      temperature: weather.temp,
      condition: weather.condition,
      humidity: weather.humidity
    }
  }
})

// Define resources
server.resource('weather_map', {
  description: 'Interactive weather map',
  uri: 'weather://map',
  mimeType: 'text/html',
  fetch: async () => {
    return generateWeatherMapHTML()
  }
})

// Start the server
server.listen(3000)
// 🎉 Inspector automatically available at http://localhost:3000/inspector
// 🚀 MCP endpoint at http://localhost:3000/mcp

Key Server Features:

• 🔍 Auto Inspector: Debugging UI automatically mounts at /inspector
• 🎨 UI Widgets: Build React components served alongside MCP tools
• 🔐 OAuth Support: Built-in authentication flow handling
• 📡 Multiple Transports: HTTP/SSE and WebSocket support
• 🛠️ TypeScript First: Full type safety and inference
• ♻️ Hot Reload: Development mode with auto-restart

Advanced Features

Streaming with AI SDK Integration:

import { streamEventsToAISDKWithTools } from 'mcp-use'
import { LangChainAdapter } from 'ai'

// In your Next.js API route
export async function POST(req: Request) {
  const { prompt } = await req.json()

  const streamEvents = agent.streamEvents(prompt)
  const enhancedStream = streamEventsToAISDKWithTools(streamEvents)
  const readableStream = createReadableStreamFromGenerator(enhancedStream)

  return LangChainAdapter.toDataStreamResponse(readableStream)
}

Custom UI Widgets:

// resources/analytics-dashboard.tsx
import { useMcp } from 'mcp-use/react'

export default function AnalyticsDashboard() {
  const { callTool, status } = useMcp()
  const [data, setData] = useState(null)

  useEffect(() => {
    callTool('get_analytics', { period: '7d' })
      .then(setData)
  }, [])

  return (
    <div>
      <h1>Analytics Dashboard</h1>
      {/* Your dashboard UI */}
    </div>
  )
}

Full mcp-use Documentation →

---

@mcp-use/cli

Powerful build and development tool for MCP applications with integrated inspector.

# Development with hot reload
mcp-use dev

# Production build
mcp-use build

# Start production server
mcp-use start

What it does:

• 🚀 Auto-opens inspector in development mode
• ♻️ Hot reload for both server and UI widgets
• 📦 Bundles React widgets into standalone HTML pages
• 🏗️ Optimized production builds with asset hashing
• 🛠️ TypeScript compilation with watch mode

Example workflow:

# Start development
mcp-use dev
# Server running at http://localhost:3000
# Inspector opened at http://localhost:3000/inspector
# Watching for changes...

# Make changes to your code
# Server automatically restarts
# UI widgets hot reload
# Inspector updates in real-time

Full CLI Documentation →

---

@mcp-use/inspector

Web-based debugging tool for MCP servers - like Swagger UI but for MCP.

Features:

• 🔍 Test tools interactively with live execution
• 📊 Monitor connection status and server health
• 🔐 Handle OAuth flows automatically
• 💾 Persistent sessions with localStorage
• 🎨 Beautiful, responsive UI

Three ways to use:

1. Automatic (with mcp-use server):

server.listen(3000)
// Inspector at http://localhost:3000/inspector

2. Standalone CLI:

npx mcp-inspect --url https://mcp.example.com/sse

3. Custom mounting:

import { mountInspector } from '@mcp-use/inspector'
mountInspector(app, '/debug')

Full Inspector Documentation →

---

create-mcp-use-app

Zero-configuration project scaffolding for MCP applications.

# Interactive mode
npx create-mcp-use-app

# Direct mode
npx create-mcp-use-app my-app --template advanced

What you get:

• ✅ Complete TypeScript setup
• ✅ Pre-configured build scripts
• ✅ Example tools and widgets
• ✅ Development environment ready
• ✅ Docker and CI/CD configs (advanced template)

Full create-mcp-use-app Documentation →

---

💡 Real-World Examples

Example 1: AI-Powered File Manager

// Create an agent that can manage files
const agent = new MCPAgent({
  llm: new ChatOpenAI(),
  client: MCPClient.fromDict({
    mcpServers: {
      filesystem: {
        command: 'npx',
        args: ['@modelcontextprotocol/server-filesystem', '/Users/me/documents']
      }
    }
  })
})

// Natural language file operations
await agent.run('Organize all PDF files into a "PDFs" folder sorted by date')
await agent.run('Find all TypeScript files and create a project summary')
await agent.run('Delete all temporary files older than 30 days')

Example 2: Multi-Tool Research Assistant

// Connect multiple MCP servers
const client = MCPClient.fromDict({
  mcpServers: {
    browser: { command: 'npx', args: ['@playwright/mcp'] },
    search: { command: 'npx', args: ['@mcp/server-search'] },
    memory: { command: 'npx', args: ['@mcp/server-memory'] }
  }
})

const researcher = new MCPAgent({
  llm: new ChatAnthropic(),
  client,
  useServerManager: true // Auto-select appropriate server
})

// Complex research task
const report = await researcher.run(`
  Research the latest developments in quantum computing.
  Search for recent papers, visit official websites,
  and create a comprehensive summary with sources.
`)

Example 3: Database Admin Assistant

const server = createMCPServer('db-admin', {
  version: '1.0.0'
})

server.tool('execute_query', {
  description: 'Execute SQL query safely',
  parameters: z.object({
    query: z.string(),
    database: z.string()
  }),
  execute: async ({ query, database }) => {
    // Validate and execute query
    const results = await db.query(query, { database })
    return { rows: results, count: results.length }
  }
})

// Create an AI-powered DBA
const dba = new MCPAgent({
  llm: new ChatOpenAI({ model: 'gpt-4' }),
  client: new MCPClient({ url: 'http://localhost:3000/mcp' })
})

await dba.run('Show me all users who signed up this week')
await dba.run('Optimize the slow queries in the performance log')

---

🏗️ Project Structure

A typical MCP-Use project structure:

my-mcp-app/
├── src/
│   └── index.ts          # MCP server definition
├── resources/            # UI widgets (React components)
│   ├── dashboard.tsx     # Main dashboard widget
│   └── settings.tsx      # Settings panel widget
├── package.json         # Dependencies and scripts
├── tsconfig.json        # TypeScript configuration
├── .env                 # Environment variables
└── dist/               # Build output
    ├── index.js        # Compiled server
    └── resources/      # Compiled widgets

---

🛠️ Development Workflow

Local Development

# 1. Create your project
npx create-mcp-use-app my-project

# 2. Start development
cd my-project
npm run dev

# 3. Make changes - hot reload handles the rest
# 4. Test with the auto-opened inspector

Production Deployment

# Build for production
npm run build

# Deploy with Docker
docker build -t my-mcp-server .
docker run -p 3000:3000 my-mcp-server

# Or deploy to any Node.js host
npm run start

---

🤝 Community & Support

• Discord: Join our community
• GitHub Issues: Report bugs or request features
• Documentation: Full docs

---

📊 Publishing & Version Management

This monorepo uses modern tooling for package management:

Using Changesets (Recommended)

# Create a changeset for your changes
pnpm changeset

# Version packages based on changesets
pnpm changeset version

# Publish all changed packages
pnpm changeset publish

Manual Publishing

# Publish individual packages
pnpm --filter mcp-use publish --access public
pnpm --filter @mcp-use/cli publish --access public
pnpm --filter @mcp-use/inspector publish --access public
pnpm --filter create-mcp-use-app publish --access public

# Or publish all at once
pnpm -r publish --access public

---

🧑‍💻 Contributing

We welcome contributions! Check out our Contributing Guide to get started.

Development Setup

# Clone the repository
git clone https://github.com/mcp-use/mcp-use-ts.git
cd mcp-use-ts

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Start development
pnpm dev

---

📜 License

MIT © MCP-Use

---

Built with ❤️ by the MCP-Use team