mcp-use__mcp-use/libraries/typescript

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

📦 Part of the mcp-use Monorepo - This is the TypeScript implementation. Also available in Python.

---

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

🏗️ What's Included

mcp-use for TypeScript provides the complete MCP stack:

• 🤖 MCP Agent - Build AI agents that can use tools and reason across multiple steps
• 🔌 MCP Client - Connect directly to MCP servers for programmatic tool access
• 🛠️ MCP Server Framework - Create your own MCP servers with tools, resources, and prompts
• 🎨 MCP Apps - Build interactive widgets that work across Claude, ChatGPT, and other MCP clients
• 🔍 MCP Inspector - Web-based debugger for testing and monitoring

---

📖 Quick Links

• Main Repository - Overview of the entire mcp-use ecosystem
• Python Version - Python implementation for agents and clients
• Inspector Documentation - Debug your MCP servers
• Server and CLI Documentation - Build and run MCP apps

📦 Packages Overview

Package	Description	Version	Downloads
mcp-use	Core framework for MCP clients and servers
@mcp-use/inspector	Web-based debugger for MCP servers
@mcp-use/tunnel	WebSocket tunnel client and CLI
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!

---

🎨 MCP Apps

MCP Apps let you build interactive views that work across Claude, ChatGPT, and other MCP clients.

Why MCP Apps?

• 🖥️ Interactive Interfaces - Build rich UIs like dashboards, kanban boards, forms, and visualizations
• 🔗 Tool Integration - Views read their rendering result with useToolContext and call server tools with useCallTool
• 📦 Self-Contained - Views are bundled and served automatically by your MCP server
• 🎯 Framework Agnostic - Compatible with any MCP client (Claude Desktop, ChatGPT, custom apps, etc.)
• ⚡ Hot Reload - Development workflow with instant updates

Quick Example

// views/analytics-dashboard/view.tsx
import { useCallTool, useToolContext } from "mcp-use/react";

interface Analytics {
  period: string;
  visitors: number;
}

export default function AnalyticsDashboard() {
  const view = useToolContext();
  const refresh = useCallTool("show-analytics");

  if (view.status === "pending") return <p>Loading analytics…</p>;
  if (view.status === "error") return <p>{view.error.message}</p>;

  const analytics =
    refresh.data?.structuredContent ?? (view.toolOutput as Analytics);

  return (
    <main>
      <h1>Analytics Dashboard</h1>
      <p>{analytics.visitors} visitors</p>
      <button
        disabled={refresh.isPending}
        onClick={() => void refresh.callTool({ period: analytics.period })}
      >
        Refresh
      </button>
    </main>
  );
}

Bind the rendering tool to the view in your server:

export const showAnalytics = server.tool(
  {
    name: "show-analytics",
    description: "Show analytics for a reporting period",
    inputSchema: z.object({ period: z.string() }),
    outputSchema: z.object({ period: z.string(), visitors: z.number() }),
    view: { name: "analytics-dashboard" },
  },
  async ({ period }) => {
    const analytics = { period, visitors: 1_024 };
    return {
      content: [{ type: "text", text: JSON.stringify(analytics) }],
      structuredContent: analytics,
    };
  }
);

Learn More:

• MCP Apps Guide (detailed section below)
• Create mcp-use App - Scaffolding with UI examples
• AI SDK Integration - Build with Vercel AI SDK

---

📚 Package Documentation

Client, Agent, and Server Packages

Use @mcp-use/client for MCP connections, @mcp-use/agent for agents, and mcp-use for servers.

As an MCP Client

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

import { MCPClient } from "@mcp-use/client";
import { MCPAgent } from "@mcp-use/agent";
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 { MCPServer, text } from "mcp-use";
import { z } from "zod";

// Create your MCP server
const server = new MCPServer({
  name: "weather-server",
  version: "1.0.0",
  description: "Weather information MCP server",
});

// Define tools with Zod schemas
export const getWeather = server.tool(
  {
    name: "get_weather",
    description: "Get current weather for a city",
    schema: z.object({
      city: z.string().describe("City name"),
      units: z.enum(["celsius", "fahrenheit"]).optional(),
    }),
  },
  async ({ city, units = "celsius" }) => {
    const weather = await fetchWeather(city, units);
    return text(
      `Temperature: ${weather.temp}, Condition: ${weather.condition}, Humidity: ${weather.humidity}`
    );
  }
);

// Define resources
server.resource(
  {
    name: "weather_map",
    description: "Interactive weather map",
    uri: "weather://map",
    mimeType: "text/html",
  },
  async () => {
    return {
      contents: [
        {
          uri: "weather://map",
          mimeType: "text/html",
          text: generateWeatherMapHTML(),
        },
      ],
    };
  }
);

// Start the server
server.listen(3000);
// 🚀 MCP endpoint at http://localhost:3000/mcp

Key Server Features:

• 🔍 Dev Inspector: mcp-use dev mounts the project-local Inspector at /mcp/inspector
• 🎨 MCP Apps Views: 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/agent";
import { createTextStreamResponse } 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 createTextStreamResponse({ textStream: readableStream });
}

Custom MCP Apps views:

// views/analytics-dashboard/view.tsx
import { useToolContext } from "mcp-use/react";

export default function AnalyticsDashboard() {
  const view = useToolContext();

  if (view.status === "pending") return <p>Loading analytics…</p>;
  if (view.status === "error") return <p>{view.error.message}</p>;

  return (
    <div>
      <h1>Analytics Dashboard</h1>
      <pre>{JSON.stringify(view.toolOutput, null, 2)}</pre>
    </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 MCP Apps views
• 📦 Bundles React views for MCP resource delivery
• 🏗️ 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/mcp/inspector
# Watching for changes...

# Make changes to your code
# Server automatically restarts
# MCP Apps views hot reload
# Inspector updates in real-time

Full CLI Documentation →

---

@mcp-use/tunnel

Expose a local HTTP, WebSocket, or MCP server through the managed WebSocket relay. The same implementation is bundled into mcp-use dev --tunnel and mcp-use start --tunnel.

npx @mcp-use/tunnel 3000

Tunnel package 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 in development (with a generated mcp-use project):

npm run dev
# Inspector at http://localhost:3000/mcp/inspector

2. Standalone CLI:

npx @mcp-use/inspector --url https://mcp.example.com/sse

3. Custom mounting:

import { mountInspector } from "@mcp-use/inspector";
mountInspector(app, { basePath: "/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 views
• ✅ 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 = new MCPServer({
  name: "db-admin",
  version: "1.0.0",
});

export const executeQuery = server.tool(
  {
    name: "execute_query",
    description: "Execute SQL query safely",
    schema: z.object({
      query: z.string(),
      database: z.string(),
    }),
  },
  async ({ query, database }) => {
    // Validate and execute query
    const results = await db.query(query, { database });
    return text(`Query executed: ${results.length} rows returned`);
  }
);

// 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
├── views/                # MCP Apps views
│   ├── dashboard/
│   │   └── view.tsx      # Dashboard view entry
│   └── settings/
│       └── view.tsx      # Settings view entry
├── package.json         # Dependencies and scripts
├── tsconfig.json        # TypeScript configuration
├── .env                 # Environment variables
└── .mcp-use/           # Generated build output
    └── build/
        ├── index.js    # Compiled server
        └── views/      # Compiled view assets

---

🛠️ 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

---

📊 Version Management

This monorepo uses Changesets for automated version management and publishing.

For Contributors

When making changes to TypeScript packages, create a changeset to describe your changes:

# Create a changeset
cd libraries/typescript
pnpm changeset

# Follow the prompts to:
# 1. Select which packages changed
# 2. Choose the version bump type (major/minor/patch)
# 3. Write a summary of changes

# Commit the changeset with your code
git add .
git commit -m "feat: your feature description"

Release Channels

Stable Releases (main branch)

• Push changes with changesets to main branch
• CI creates/updates a "Version Packages" PR automatically
• Merge the Version PR to publish stable versions
• Packages published with latest tag on npm

Canary Prereleases (canary branch)

• Push changes with changesets to canary branch
• CI automatically publishes prerelease versions
• Versions: x.y.z-canary.0, x.y.z-canary.1, etc.
• Published with canary dist tag on npm

# Install canary versions
npm install mcp-use@canary

---

🧑‍💻 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.git
cd mcp-use/libraries/typescript

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Start development
pnpm dev

Finding Unused Code with Knip

This monorepo uses Knip to find unused files, exports, and dependencies.

# Full report (files, exports, dependencies, types, etc.)
pnpm knip

# Unused dependencies only (non-blocking)
pnpm knip:deps

# Production mode — excludes tests, stories, devDependencies
pnpm knip:production

Configuration lives in knip.json. When false positives appear, prefer refining entry / project patterns or adding tag-based overrides over broad ignore rules. See the Knip configuration docs for details.

---

📜 License

MIT © mcp-use

---

Built with ❤️ by the mcp-use team