mcp-use-ts

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