modelcontextprotocol/ext-apps
Watch
1
0
Fork
You've already forked ext-apps
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #286 from modelcontextprotocol/ochafik/readme-mcp-config

Browse source 
docs: add MCP client configuration to READMEs
This commit is contained in:
Anton Pidkuiko 2026-01-20 11:11:51 +00:00 • committed by GitHub
commit f6ee5d5bdc
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
22 changed files with 686 additions and 27 deletions
Download patch file Download diff file Expand all files Collapse all files

226
README.md
View file

@ -79,7 +79,231 @@ Or edit your `package.json` manually:
The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples) directory contains additional demo apps showcasing real-world use cases.
To run all examples:
<details>
<summary>MCP client configuration for all examples</summary>
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"basic-react": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-basic-react",
"--stdio"
]
},
"basic-vanillajs": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-basic-vanillajs",
"--stdio"
]
},
"basic-vue": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-basic-vue",
"--stdio"
]
},
"basic-svelte": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-basic-svelte",
"--stdio"
]
},
"basic-preact": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-basic-preact",
"--stdio"
]
},
"basic-solid": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-basic-solid",
"--stdio"
]
},
"budget-allocator": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-budget-allocator",
"--stdio"
]
},
"cohort-heatmap": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-cohort-heatmap",
"--stdio"
]
},
"customer-segmentation": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-customer-segmentation",
"--stdio"
]
},
"map": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-map",
"--stdio"
]
},
"pdf": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-pdf",
"--stdio"
]
},
"scenario-modeler": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-scenario-modeler",
"--stdio"
]
},
"shadertoy": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-shadertoy",
"--stdio"
]
},
"sheet-music": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-sheet-music",
"--stdio"
]
},
"system-monitor": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-system-monitor",
"--stdio"
]
},
"threejs": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-threejs",
"--stdio"
]
},
"transcript": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-transcript",
"--stdio"
]
},
"video-resource": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-video-resource",
"--stdio"
]
},
"wiki-explorer": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-wiki-explorer",
"--stdio"
]
},
"qr": {
"command": "uv",
"args": [
"run",
"/path/to/ext-apps/examples/qr-server/server.py",
"--stdio"
]
},
"say": {
"command": "uv",
"args": [
"run",
"--default-index",
"https://pypi.org/simple",
"https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/refs/heads/main/examples/say-server/server.py",
"--stdio"
]
}
}
}
```
> **Note:** The `qr` server requires cloning the repository first. See [qr-server README](examples/qr-server) for details.
</details>
To run all examples locally in dev mode:
```bash
npm install

21
examples/basic-server-preact/README.md
View file

@ -5,6 +5,27 @@ An MCP App example with a Preact UI.
> [!TIP]
> Looking for a vanilla JavaScript example? See [`basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs)!
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"basic-preact": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-basic-preact",
"--stdio"
]
}
}
}
```
## Overview
- Tool registration with a linked UI resource

21
examples/basic-server-react/README.md
View file

@ -7,6 +7,27 @@ An MCP App example with a React UI.
> [!TIP]
> Looking for a vanilla JavaScript example? See [`basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs)!
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"basic-react": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-basic-react",
"--stdio"
]
}
}
}
```
## Overview
- Tool registration with a linked UI resource

21
examples/basic-server-solid/README.md
View file

@ -5,6 +5,27 @@ An MCP App example with a Solid UI.
> [!TIP]
> Looking for a vanilla JavaScript example? See [`basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs)!
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"basic-solid": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-basic-solid",
"--stdio"
]
}
}
}
```
## Overview
- Tool registration with a linked UI resource

21
examples/basic-server-svelte/README.md
View file

@ -5,6 +5,27 @@ An MCP App example with a Svelte 5 UI using runes for reactivity.
> [!TIP]
> Looking for a vanilla JavaScript example? See [`basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs)!
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"basic-svelte": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-basic-svelte",
"--stdio"
]
}
}
}
```
## Overview
- Tool registration with a linked UI resource

21
examples/basic-server-vanillajs/README.md
View file

@ -5,6 +5,27 @@ An MCP App example with a vanilla JavaScript UI (no framework).
> [!TIP]
> Looking for a React-based example? See [`basic-server-react`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react)!
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"basic-vanillajs": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-basic-vanillajs",
"--stdio"
]
}
}
}
```
## Overview
- Tool registration with a linked UI resource

21
examples/basic-server-vue/README.md
View file

@ -5,6 +5,27 @@ An MCP App example with a Vue 3 UI using the Composition API.
> [!TIP]
> Looking for a vanilla JavaScript example? See [`basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs)!
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"basic-vue": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-basic-vue",
"--stdio"
]
}
}
}
```
## Overview
- Tool registration with a linked UI resource

21
examples/budget-allocator-server/README.md
View file

@ -10,6 +10,27 @@ An interactive budget allocation tool demonstrating real-time data visualization
</tr>
</table>
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"budget-allocator": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-budget-allocator",
"--stdio"
]
}
}
}
```
## Features
- **Interactive Sliders**: Adjust budget allocation across 5 categories (Marketing, Engineering, Operations, Sales, R&D)

21
examples/cohort-heatmap-server/README.md
View file

@ -10,6 +10,27 @@ A demo MCP App that displays cohort retention data as an interactive heatmap, sh
</tr>
</table>
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"cohort-heatmap": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-cohort-heatmap",
"--stdio"
]
}
}
}
```
## Features
- **Cohort Retention Heatmap**: Color-coded grid showing retention percentages across cohorts and time periods

21
examples/customer-segmentation-server/README.md
View file

@ -10,6 +10,27 @@ A demo MCP App that displays customer data as an interactive scatter/bubble char
</tr>
</table>
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"customer-segmentation": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-customer-segmentation",
"--stdio"
]
}
}
}
```
## Features
- **Interactive Scatter Plot**: Bubble chart visualization using Chart.js with configurable X/Y axes

21
examples/map-server/README.md
View file

@ -4,6 +4,27 @@
Interactive 3D globe viewer using CesiumJS with OpenStreetMap tiles. Demonstrates geocoding integration and full MCP App capabilities.
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"map": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-map",
"--stdio"
]
}
}
}
```
## Features
- **3D Globe Rendering**: Interactive CesiumJS globe with rotation, zoom, and 3D perspective

21
examples/pdf-server/README.md
View file

@ -4,6 +4,27 @@
A simple interactive PDF viewer that uses [PDF.js](https://mozilla.github.io/pdf.js/). Launch it w/ a few PDF files and/or URLs as CLI args (+ support loading any additional pdf from arxiv.org).
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"pdf": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-pdf",
"--stdio"
]
}
}
}
```
## What This Example Demonstrates
### 1. Chunked Data Through Size-Limited Tool Calls

42
examples/qr-server/README.md
View file

@ -4,12 +4,37 @@ A minimal Python MCP server that generates customizable QR codes with an interac
![Screenshot](https://modelcontextprotocol.github.io/ext-apps/screenshots/qr-server/screenshot.png)
## MCP Client Configuration
First, clone the repository:
```bash
git clone https://github.com/modelcontextprotocol/ext-apps.git
```
Then add to your MCP client configuration (stdio transport), replacing the path with your clone location:
```json
{
"mcpServers": {
"qr": {
"command": "uv",
"args": [
"run",
"/path/to/ext-apps/examples/qr-server/server.py",
"--stdio"
]
}
}
}
```
## Features
- Generate QR codes from any text or URL
- Customizable colors, size, and error correction
- Interactive widget that displays in MCP-UI enabled clients
- Supports both HTTP (for web clients) and stdio (for Claude Desktop)
- Supports both HTTP (for web clients) and stdio (for MCP clients)
## Prerequisites
@ -41,24 +66,13 @@ Connect from basic-host:
SERVERS='["http://localhost:3108/mcp"]' bun serve.ts
```
### Stdio Mode (for Claude Desktop)
### Stdio Mode (for MCP clients)
```bash
uv run server.py --stdio
```
Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"qr": {
"command": "uv",
"args": ["run", "/path/to/qr-server/server.py", "--stdio"]
}
}
}
```
See [MCP Client Configuration](#mcp-client-configuration) above for how to add this server to your MCP client.
### Docker (accessing host server from container)

46
examples/say-server/README.md
View file

@ -2,6 +2,29 @@
A real-time text-to-speech MCP App with karaoke-style text highlighting, powered by [Kyutai's Pocket TTS](https://github.com/kyutai-labs/pocket-tts).
![Screenshot](screenshot.png)
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"say": {
"command": "uv",
"args": [
"run",
"--default-index",
"https://pypi.org/simple",
"https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/refs/heads/main/examples/say-server/server.py",
"--stdio"
]
}
}
}
```
## MCP App Features Demonstrated
This example showcases several MCP App capabilities:
@ -26,35 +49,31 @@ This example showcases several MCP App capabilities:
## Prerequisites
- [uv](https://docs.astral.sh/uv/getting-started/installation/) - fast Python package manager
- A CUDA GPU (recommended) or CPU with sufficient RAM (~2GB for model)
- [uv](https://docs.astral.sh/uv/) - fast Python package manager
## Quick Start
The server is a single self-contained Python file that can be run directly with `uv`:
The server is a single self-contained Python file that can be run directly from GitHub:
```bash
# Run directly (uv auto-installs dependencies)
uv run examples/say-server/server.py
# Run directly from GitHub (uv auto-installs dependencies)
uv run https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/main/examples/say-server/server.py
```
The server will be available at `http://localhost:3109/mcp`.
## Running with Docker
Run directly from GitHub using the official `uv` Docker image. Mount your HuggingFace cache to avoid re-downloading the model:
Run directly from GitHub using the official `uv` Docker image:
```bash
docker run --rm -it \
-p 3109:3109 \
-v ~/.cache/huggingface:/root/.cache/huggingface \
-e HF_HOME=/root/.cache/huggingface \
-v ~/.cache/huggingface-docker-say-server:/root/.cache/huggingface \
ghcr.io/astral-sh/uv:debian \
uv run https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/main/examples/say-server/server.py
```
For GPU support, add `--gpus all` (requires [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)).
## Usage
### With Claude Desktop
@ -66,8 +85,11 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
"mcpServers": {
"say": {
"command": "uv",
"args": ["run", "server.py", "--stdio"],
"cwd": "/path/to/examples/say-server"
"args": [
"run",
"https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/main/examples/say-server/server.py",
"--stdio"
]
}
}
}

21
examples/scenario-modeler-server/README.md
View file

@ -10,6 +10,27 @@ A React-based demo MCP App that lets users adjust SaaS business parameters and s
</tr>
</table>
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"scenario-modeler": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-scenario-modeler",
"--stdio"
]
}
}
}
```
## Features
- **Interactive Parameters**: 5 sliders for Starting MRR, Growth Rate, Churn Rate, Gross Margin, and Fixed Costs

21
examples/shadertoy-server/README.md
View file

@ -10,6 +10,27 @@ A demo MCP App that renders [ShaderToy](https://www.shadertoy.com/)-compatible G
</tr>
</table>
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"shadertoy": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-shadertoy",
"--stdio"
]
}
}
}
```
## Features
- **Real-time Rendering**: Renders GLSL shaders using WebGL 2.0

21
examples/sheet-music-server/README.md
View file

@ -9,6 +9,27 @@ A demo MCP App that renders [ABC notation](https://en.wikipedia.org/wiki/ABC_not
</tr>
</table>
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"sheet-music": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-sheet-music",
"--stdio"
]
}
}
}
```
## Features
- **Audio Playback**: Built-in audio player with play/pause and loop controls

21
examples/system-monitor-server/README.md
View file

@ -10,6 +10,27 @@ A demo MCP App that displays real-time OS metrics with a stacked area chart for
</tr>
</table>
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"system-monitor": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-system-monitor",
"--stdio"
]
}
}
}
```
## Features
- **Per-Core CPU Monitoring**: Stacked area chart showing individual CPU core utilization over a 1-minute sliding window

21
examples/threejs-server/README.md
View file

@ -4,6 +4,27 @@
Interactive 3D scene renderer using Three.js. Demonstrates streaming code preview and full MCP App integration.
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"threejs": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-threejs",
"--stdio"
]
}
}
}
```
## Features
- **Interactive 3D Rendering**: Execute JavaScript code to create and animate Three.js scenes

21
examples/transcript-server/README.md
View file

@ -4,6 +4,27 @@
An MCP App Server for live speech transcription using the Web Speech API.
## MCP Client Configuration
Add to your MCP client configuration (stdio transport):
```json
{
"mcpServers": {
"transcript": {
"command": "npx",
"args": [
"-y",
"--silent",
"--registry=https://registry.npmjs.org/",
"@modelcontextprotocol/server-transcript",
"--stdio"
]
}
}
}
```
## Features
- **Live Transcription**: Real-time speech-to-text using browser's Web Speech API

Some files were not shown because too many files have changed in this diff Show more