MCP Servers vs MCP Apps

Overview

mcp-use enables you to build two types of MCP implementations:

MCP Servers

Backend services that expose tools, resources, and prompts to AI agents

MCP Apps

Interactive widgets with UI components that work across ChatGPT, Claude, and other clients

MCP Servers

What are MCP Servers?

MCP Servers are backend services that implement the Model Context Protocol to provide tools, resources, and prompts that AI agents can use. They are headless services focused on functionality rather than presentation.

Key Characteristics

Tool-Focused

MCP Servers primarily expose tools (functions) that AI agents can call to perform actions:

server.tool({
  name: "search_database",
  description: "Search the product database",
  schema: z.object({
    query: z.string(),
    limit: z.number().optional(),
  }),
}, async ({ query, limit = 10 }) => {
  const results = await db.search(query, limit);
  return text(JSON.stringify(results));
});

No User Interface

MCP Servers return structured data (text, JSON, binary) without any UI components. The AI client decides how to present the data to users.

// Server returns data
return text("Temperature: 72°F");

// Client/AI decides how to display it

Stateless Operations

Each tool call is typically independent and stateless:

server.tool({
  name: "calculate",
  schema: z.object({ expression: z.string() }),
}, async ({ expression }) => {
  const result = eval(expression);
  return text(`Result: ${result}`);
});

Resource Access

Servers can expose resources for AI agents to read:

server.resource({
  name: "config",
  uri: "app://config",
  title: "Application Configuration",
}, async () => {
  const config = await loadConfig();
  return text(JSON.stringify(config));
});

When to Use MCP Servers

Use MCP Servers when you need:

🛠️ Programmatic access to APIs and services
🤖 Tool-based interactions for AI agents
📋 Data retrieval from databases or files
⚙️ Background processing without UI requirements
🔌 Integration with existing backend services

Example: Simple MCP Server

import { MCPServer, text } from "mcp-use/server";
import { z } from "zod";

const server = new MCPServer({
  name: "weather-server",
  version: "1.0.0",
});

server.tool({
  name: "get_weather",
  description: "Get weather for a city",
  schema: z.object({ city: z.string() }),
}, async ({ city }) => {
  const weather = await fetchWeather(city);
  return text(`${city}: ${weather.temp}°F, ${weather.condition}`);
});

await server.listen(3000);

MCP Apps

What are MCP Apps?

MCP Apps extend MCP Servers with interactive UI widgets that render in AI clients like ChatGPT and Claude. They combine backend functionality with frontend presentation in a unified package.

Key Characteristics

Interactive Widgets

MCP Apps include React components that render in the client:

// resources/weather-display/widget.tsx
import { useWidget } from "mcp-use/react";

export default function WeatherDisplay() {
  const { props } = useWidget<{
    city: string;
    temperature: number;
    condition: string;
  }>();
  
  return (
    <div className="weather-card">
      <h2>{props.city}</h2>
      <div className="temp">{props.temperature}°</div>
      <p>{props.condition}</p>
    </div>
  );
}

Cross-Platform Compatibility

Widgets work seamlessly across different AI clients:

ChatGPT: Using Apps SDK protocol
Claude Desktop: Using MCP Apps Extension
Other MCP clients: Auto-adapts to capabilities

server.tool({
  name: "show_weather",
  description: "Display weather widget",
  schema: z.object({ city: z.string() }),
  widget: "weather-display",  // Links to widget
}, async ({ city }) => {
  return widget({
    props: { city, temperature: 72, condition: "Sunny" },
    message: `Weather for ${city}`,
  });
});

Rich Interactions

Widgets can handle user interactions and call tools:

export default function TaskManager() {
  const { callTool } = useWidget();
  
  const addTask = async (title: string) => {
    await callTool("create_task", { title });
  };
  
  return (
    <button onClick={() => addTask("New task")}>
      Add Task
    </button>
  );
}

Automatic Discovery

Widgets in resources/ directory are auto-discovered:

project/
├── src/
│   └── server.ts
└── resources/
    ├── weather-display/
    │   └── widget.tsx
    └── task-list/
        └── widget.tsx

No manual registration needed!

When to Use MCP Apps

Use MCP Apps when you need:

📊 Data visualization (charts, graphs, dashboards)
🎮 Interactive forms and user input
📋 Rich content display (cards, lists, galleries)
👩‍💻 User-facing interfaces embedded in chat
🎨 Custom styling and branding

import { MCPServer, widget } from "mcp-use/server";
import { z } from "zod";

const server = new MCPServer({
  name: "weather-app",
  version: "1.0.0",
});

server.tool({
  name: "show_weather",
  description: "Display interactive weather widget",
  schema: z.object({ city: z.string() }),
  widget: "weather-display",  // Links to resources/weather-display/widget.tsx
}, async ({ city }) => {
  const weather = await fetchWeather(city);
  
  return widget({
    props: {
      city,
      temperature: weather.temp,
      condition: weather.condition,
      icon: weather.icon,
    },
    message: `Weather in ${city}: ${weather.condition}, ${weather.temp}°F`,
  });
});

await server.listen(3000);

import { useWidget, type WidgetMetadata } from "mcp-use/react";
import { z } from "zod";

const propSchema = z.object({
  city: z.string(),
  temperature: z.number(),
  condition: z.string(),
  icon: z.string().optional(),
});

export const widgetMetadata: WidgetMetadata = {
  description: "Display weather information",
  props: propSchema,
};

export default function WeatherDisplay() {
  const { props, theme, isPending } = useWidget<z.infer<typeof propSchema>>();
  
  if (isPending) return <div>Loading...</div>;
  
  return (
    <div style={{
      background: theme === "dark" ? "#1a1a2e" : "#f0f4ff",
      borderRadius: 16,
      padding: 24,
    }}>
      <h2>{props.city}</h2>
      {props.icon && <img src={props.icon} alt="weather icon" />}
      <div className="temp">{props.temperature}°F</div>
      <p>{props.condition}</p>
    </div>
  );
}

Comparison Table

Feature	MCP Server	MCP App
UI Components	❌ No	✅ Yes (React widgets)
Tool Exposure	✅ Yes	✅ Yes
Resource Access	✅ Yes	✅ Yes
Prompts	✅ Yes	✅ Yes
Client Compatibility	All MCP clients	ChatGPT, Claude, MCP Apps clients
Use Case	Backend services, data access	Interactive UIs, visualizations
Development	Simple, lightweight	Requires widget development
Auto Inspector	✅ Yes	✅ Yes

Choosing the Right Approach

Start with MCP Server

Begin with a basic MCP Server if you:

Need simple tool exposure
Don’t require UI components
Want the simplest implementation

Add Widgets Incrementally

Upgrade to MCP App when you:

Identify tools that benefit from visualization
Want to improve user experience
Need interactive components

Mix Both Approaches

In the same server, you can have:

Some tools return plain text (server-style)
Some tools return widgets (app-style)

// Plain tool (no widget)
server.tool({
  name: "calculate",
  schema: z.object({ expr: z.string() }),
}, async ({ expr }) => {
  return text(`Result: ${eval(expr)}`);
});

// Widget-enabled tool
server.tool({
  name: "show_chart",
  schema: z.object({ data: z.array(z.number()) }),
  widget: "chart-display",
}, async ({ data }) => {
  return widget({ props: { data } });
});

Development Workflow

MCP Server
MCP App

# Create server
npx create-mcp-use-app my-server

# Start development
cd my-server
npm run dev

# Test in inspector
open http://localhost:3000/inspector

# Create app with widgets
npx create-mcp-use-app my-app
# Select: "MCP App with widgets"

# Start development with hot reload
cd my-app
npm run dev

# Inspector auto-opens and reloads on changes

Learn More

Build Your First Server

Step-by-step guide to creating an MCP Server

Build MCP Apps

Learn to create interactive widgets for MCP Apps

Tools, Resources, Prompts

Deep dive into MCP primitives

Architecture

Understand the mcp-use framework architecture

Getting Started

Core Concepts

Guides

MCP Servers vs MCP Apps

Overview

MCP Servers

MCP Apps

MCP Servers

What are MCP Servers?

Key Characteristics

When to Use MCP Servers

Example: Simple MCP Server

MCP Apps

What are MCP Apps?

Key Characteristics

When to Use MCP Apps

Example: MCP App with Widget

Comparison Table

Choosing the Right Approach

Development Workflow

Learn More

Build Your First Server

Build MCP Apps

Tools, Resources, Prompts

Architecture

​Overview

MCP Servers

MCP Apps

​MCP Servers

​What are MCP Servers?

​Key Characteristics

​When to Use MCP Servers

​Example: Simple MCP Server

​MCP Apps

​What are MCP Apps?

​Key Characteristics

​When to Use MCP Apps

​Example: MCP App with Widget

​Comparison Table

​Choosing the Right Approach

​Development Workflow

​Learn More

Build Your First Server

Build MCP Apps

Tools, Resources, Prompts

Architecture

Overview

MCP Servers

What are MCP Servers?

Key Characteristics

When to Use MCP Servers

Example: Simple MCP Server

MCP Apps

What are MCP Apps?

Key Characteristics

When to Use MCP Apps

Example: MCP App with Widget

Comparison Table

Choosing the Right Approach

Development Workflow

Learn More