github · mcp-use1e19af9a5a68

File invokes the MCP `sampling/createMessage` capability without passing a `maxTokens` / `max_tokens` cap. The MCP spec has the *client* perform the LLM call on the server's behalf, so an uncapped request bills the end user (or hits provider limits silently). Always pass an explicit cap. TS: await server.createMessage({ messages, maxTokens: 1024, ... }) Python: await session.create_message(messages=[...], max_tokens=1024) Distinct from MCP-084 (denial-of-wallet), which targets the server's

# Sampling Example Server

This example demonstrates how to create an MCP server that uses sampling to request LLM completions from connected clients.

## Features

This server includes three example tools that use sampling:

1. **analyze-sentiment** - Analyzes text sentiment using the client's LLM

2. **summarize-text** - Summarizes text using the client's LLM

3. **translate-text** - Translates text to another language using the client's LLM

## Running the Server

```bash

# Development mode (wi

File invokes the MCP `sampling/createMessage` capability without passing a `maxTokens` / `max_tokens` cap. The MCP spec has the *client* perform the LLM call on the server's behalf, so an uncapped request bills the end user (or hits provider limits silently). Always pass an explicit cap. TS: await server.createMessage({ messages, maxTokens: 1024, ... }) Python: await session.create_message(messages=[...], max_tokens=1024) Distinct from MCP-084 (denial-of-wallet), which targets the server's

import type {

  CreateMessageRequest,

  CreateMessageResult,

  ElicitRequestFormParams,

  ElicitRequestURLParams,

  ElicitResult,

  Notification,

} from "@modelcontextprotocol/sdk/types.js";

import React, {

  createContext,

  useCallback,

  useContext,

  useEffect,

  useMemo,

  useRef,

  useState,

  type ReactNode,

} from "react";

import { Logger } from "../logging.js";

import type { StorageProvider } from "./storage/StorageProvider.js";

import type { UseMcpOptions, UseMcpResult } from "./types.

File mounts an HTTP route that handles MCP `tools/list` (Express / Fastify / FastAPI / Flask) but the route — and the router it sits behind — has no auth middleware applied. An anonymous client can enumerate every tool the server exposes, scope the attack surface, and (if `tools/call` shares the route) invoke them. Apply auth at the route or router level: Express `passport.authenticate(...)` / a `requireAuth`-style middleware, FastAPI `Depends(get_current_user)` or `Depends(verify_jwt)`, Flask

from __future__ import annotations

import inspect

import logging

import os

import time

import weakref

from datetime import UTC, datetime

from typing import TYPE_CHECKING, Any, cast

import mcp.server.lowlevel.server as lowlevel

import mcp.server.session as mcp_session

from mcp.server.fastmcp import FastMCP

from mcp.types import (

    AnyFunction,

    CallToolRequest,

    CompleteRequest,

    Completion,

    GetPromptRequest,

    Icon,

    ListPromptsRequest,

    ListResourcesRequest,

    ListTo

File mounts an HTTP route that handles MCP `tools/list` (Express / Fastify / FastAPI / Flask) but the route — and the router it sits behind — has no auth middleware applied. An anonymous client can enumerate every tool the server exposes, scope the attack surface, and (if `tools/call` shares the route) invoke them. Apply auth at the route or router level: Express `passport.authenticate(...)` / a `requireAuth`-style middleware, FastAPI `Depends(get_current_user)` or `Depends(verify_jwt)`, Flask

# Architecture

Understanding how mcp-use servers are structured under the hood.

---

## Server Structure

mcp-use is **built on top of the Hono web framework**. When you create an `MCPServer`, you get:

```typescript

const server = new MCPServer({

  name: "my-server",

  version: "1.0.0"

});

```

The server instance has three key components:

### 1. `server.app` - Hono Instance

The underlying Hono web application that handles HTTP routing and middleware.

```typescript

// Add custom HTTP route

File mounts an HTTP route that handles MCP `tools/list` (Express / Fastify / FastAPI / Flask) but the route — and the router it sits behind — has no auth middleware applied. An anonymous client can enumerate every tool the server exposes, scope the attack surface, and (if `tools/call` shares the route) invoke them. Apply auth at the route or router level: Express `passport.authenticate(...)` / a `requireAuth`-style middleware, FastAPI `Depends(get_current_user)` or `Depends(verify_jwt)`, Flask

# Architecture

Understanding how mcp-use servers are structured under the hood.

---

## Server Structure

mcp-use is **built on top of the Hono web framework**. When you create an `MCPServer`, you get:

```typescript

const server = new MCPServer({

  name: "my-server",

  version: "1.0.0"

});

```

The server instance has three key components:

### 1. `server.app` - Hono Instance

The underlying Hono web application that handles HTTP routing and middleware.

```typescript

// Add custom HTTP route

File mounts an HTTP route that handles MCP `tools/list` (Express / Fastify / FastAPI / Flask) but the route — and the router it sits behind — has no auth middleware applied. An anonymous client can enumerate every tool the server exposes, scope the attack surface, and (if `tools/call` shares the route) invoke them. Apply auth at the route or router level: Express `passport.authenticate(...)` / a `requireAuth`-style middleware, FastAPI `Depends(get_current_user)` or `Depends(verify_jwt)`, Flask

# Architecture

Understanding how mcp-use servers are structured under the hood.

---

## Server Structure

mcp-use is **built on top of the Hono web framework**. When you create an `MCPServer`, you get:

```typescript

const server = new MCPServer({

  name: "my-server",

  version: "1.0.0"

});

```

The server instance has three key components:

### 1. `server.app` - Hono Instance

The underlying Hono web application that handles HTTP routing and middleware.

```typescript

// Add custom HTTP route

MCP tool returns a hyperlink whose URL interpolates a runtime variable. Two render surfaces: markdown `[text](URL)` and HTML `<a href="URL">`. When the host renders the link, the user may click — exfiltration, phishing, or click-tracking. Unlike MCP-220 (markdown image, auto-fetched at render time), hyperlinks fire on user click — but the same threat model applies: never put untrusted data in the destination URL. Hard-code the URL or validate against a per-tool allow-list before interpolation.

import {

  Dialog,

  DialogContent,

  DialogHeader,

  DialogTitle,

} from "@/client/components/ui/dialog";

import type { McpServer } from "mcp-use/react";

import { Copy } from "lucide-react";

import { copyToClipboard } from "@/client/utils/clipboard";

import { toast } from "sonner";

import { Button } from "./ui/button";

import { Tooltip, TooltipContent, TooltipTrigger } from "./ui/tooltip";

import { JSONDisplay } from "./shared/JSONDisplay";

import {

  getConfiguredServerAlias,

  getServerDispla

MCP tool returns a hyperlink whose URL interpolates a runtime variable. Two render surfaces: markdown `[text](URL)` and HTML `<a href="URL">`. When the host renders the link, the user may click — exfiltration, phishing, or click-tracking. Unlike MCP-220 (markdown image, auto-fetched at render time), hyperlinks fire on user click — but the same threat model applies: never put untrusted data in the destination URL. Hard-code the URL or validate against a per-tool allow-list before interpolation.

import { Badge } from "@/client/components/ui/badge";

import { Button } from "@/client/components/ui/button";

import {

  DropdownMenu,

  DropdownMenuContent,

  DropdownMenuItem,

  DropdownMenuTrigger,

} from "@/client/components/ui/dropdown-menu";

import { NotFound } from "@/client/components/ui/not-found";

import { MESH_PANEL_FINE_OVERLAY_NOISE_DATA_URL } from "@/client/components/ui/random-gradient-background";

import { MeshGradient } from "@paper-design/shaders-react";

import {

  Tooltip,

  T

MCP tool returns content marked as HTML (`{type: "html"}`, `Content-Type: text/html`, or `mimeType: "text/html"`) with no sanitiser on the same code path. The host renders HTML directly — anything tainted in the body becomes a script execution / markup-injection vector. Pipe the body through `DOMPurify.sanitize()` (TS), `bleach.clean()` (Python), `lxml.html.clean.Cleaner`, or `sanitize_html` before returning. Better: return `{type: "text"}` / `text/plain` and let the host escape. Distinct from

/**

 * MCP Endpoint Mounting

 *

 * Main orchestration function for mounting MCP endpoints at /mcp and /sse.

 * Uses a single native SDK transport instance to handle all sessions.

 */

import type { Context, Hono as HonoType } from "hono";

import { join } from "node:path";

import { Telemetry } from "../../telemetry/telemetry-node.js";

import { generateLandingPage } from "../landing.js";

import type { SessionData, StreamManager } from "../sessions/index.js";

import {

  FileSystemSessionStore,

  In

MCP tool returns content marked as HTML (`{type: "html"}`, `Content-Type: text/html`, or `mimeType: "text/html"`) with no sanitiser on the same code path. The host renders HTML directly — anything tainted in the body becomes a script execution / markup-injection vector. Pipe the body through `DOMPurify.sanitize()` (TS), `bleach.clean()` (Python), `lxml.html.clean.Cleaner`, or `sanitize_html` before returning. Better: return `{type: "text"}` / `text/plain` and let the host escape. Distinct from

---

title: "Building ChatGPT Apps"

description: "Understanding ChatGPT widget flows and how mcp-use simplifies widget development"

icon: "openai"

---

<Info>

ChatGPT now supports **MCP Apps**. For new projects, use [Creating MCP Apps Server](/typescript/server/creating-mcp-apps-server) to build widgets that work with both ChatGPT and MCP Apps clients.

</Info>

# Building ChatGPT Apps with Widgets

<Info>

**Widget Protocol Options**: This guide focuses on **ChatGPT Apps SDK** specifically. For th

MCP tool returns content marked as HTML (`{type: "html"}`, `Content-Type: text/html`, or `mimeType: "text/html"`) with no sanitiser on the same code path. The host renders HTML directly — anything tainted in the body becomes a script execution / markup-injection vector. Pipe the body through `DOMPurify.sanitize()` (TS), `bleach.clean()` (Python), `lxml.html.clean.Cleaner`, or `sanitize_html` before returning. Better: return `{type: "text"}` / `text/plain` and let the host escape. Distinct from

<div align="center" style="margin: 0 auto; max-width: 80%;">

  <picture>

    <source media="(prefers-color-scheme: dark)" srcset="./packages/mcp-use/static/logo_white.svg">

    <source media="(prefers-color-scheme: light)" srcset="./packages/mcp-use/static/logo_black.svg">

    <img alt="mcp use logo" src="./packages/mcp-use/static/logo_white.svg" width="80%" style="margin: 20px auto;">

  </picture>

</div>

<h1 align="center">mcp-use: The Complete TypeScript Framework for Model Context Protocol</

MCP tool returns content marked as HTML (`{type: "html"}`, `Content-Type: text/html`, or `mimeType: "text/html"`) with no sanitiser on the same code path. The host renders HTML directly — anything tainted in the body becomes a script execution / markup-injection vector. Pipe the body through `DOMPurify.sanitize()` (TS), `bleach.clean()` (Python), `lxml.html.clean.Cleaner`, or `sanitize_html` before returning. Better: return `{type: "text"}` / `text/plain` and let the host escape. Distinct from

import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";

import { fsHelpers, isDeno } from "./runtime.js";

/**

 * Typed CallToolResult that constrains the structuredContent property

 * to match a specific type T. Used for output schema validation.

 * T must be a record type (object) to match the SDK's CallToolResult interface.

 *

 * Note:

 * Properties are listed explicitly instead of using `extends Omit<CallToolResult, "structuredContent">`

 * to avoid breaking type inference.

Auth material (token / session / JWT / API key) is stored in `localStorage` or `sessionStorage`. Both are JS-readable from any script in the same origin — a single XSS leaks the credential, and no `HttpOnly` cookie option exists for these stores. Move auth material to an `HttpOnly; Secure; SameSite=Lax` cookie set by the server. If you must keep it client-side, use the in-memory store of an SPA framework and accept the cost of re-auth on tab refresh.

"mcp-inspector-llm-config",

      JSON.stringify(newLlmConfig)

    );

    localStorage.setItem(

      "mcp-inspector-auth-config",

      JSON.stringify(newAuthConfig)

    );

motion is 1 edit from popular 'emotion' — possible typosquat

Dockerfile never sets a non-root `USER` directive, so the CMD runs as root by default. Any RCE or library-level vulnerability exploited inside this container gets full privileges (MCP Top-10 R3). Add `USER <non-root>` before CMD / ENTRYPOINT in the final stage — e.g. `USER 1000`, `USER nobody`, or `USER nonroot` on distroless.

FROM node:20-alpine

# Specify the version variable (defaults to latest)

ARG VERSION=latest

WORKDIR /app

# Cache bust by checking the latest version from npm

# This layer will be invalidated when a new version is published

RUN npm view @mcp-use/inspector version

# Install the inspector package from npm

RUN npm install -g @mcp-use/inspector@${VERSION}

# Set production environment

ENV NODE_ENV=production

# Expose 8080 (standard alternative HTTP port for production)

# Note: The actual port is 

User-controlled value printed to terminal without ANSI escape sanitization. Malicious input can inject cursor-control sequences, rewrite earlier output, or hide shell commands from the operator.

agent.setTags(["test-tag-1", "test-tag-2"]);

  console.log("💬 Running agent query...");

  const result = await agent.run({

    prompt: `Hello, you are a tester can you please answer the follwing questions:

- Which resources do you have access to?

User-controlled value printed to terminal without ANSI escape sanitization. Malicious input can inject cursor-control sequences, rewrite earlier output, or hide shell commands from the operator.

const terminalElicitation: OnElicitationCallback = async (params) => {

  if (params.mode === "url") {

    console.log(`Visit: ${params.url}`);

    return { action: "accept" };

  }

  const input = await promptTerminal(params.message, params.requestedSchema);

User-controlled value printed to terminal without ANSI escape sanitization. Malicious input can inject cursor-control sequences, rewrite earlier output, or hide shell commands from the operator.

// Custom middleware

server.use('/api/*', async (c, next) => {

  console.log(`${c.req.method} ${c.req.path}`)

  await next()

})

User-controlled value printed to terminal without ANSI escape sanitization. Malicious input can inject cursor-control sequences, rewrite earlier output, or hide shell commands from the operator.

currentToolCall = event.name;

          console.log(`\n🔧 Tool started: ${event.name}`);

          if (event.data?.input) {

            console.log(`   Input: ${JSON.stringify(event.data.input)}`);

          }

          break;

User-controlled value printed to terminal without ANSI escape sanitization. Malicious input can inject cursor-control sequences, rewrite earlier output, or hide shell commands from the operator.

{

    clientInfo: { name: "my-app", version: "1.0.0" },

    onElicitation: async (params) => acceptWithDefaults(params),

    onNotification: (n) => console.log(n.method, n.params),

    // onSampling: optional; see Sampling docs

  }

);

User-controlled value printed to terminal without ANSI escape sanitization. Malicious input can inject cursor-control sequences, rewrite earlier output, or hide shell commands from the operator.

// Set up elicitation handler

  client.setRequestHandler(ElicitRequestSchema, async (request: any) => {

    console.log("\n📥 Received elicitation request:");

    console.log("  Mode:", request.params.mode || "form");

    console.log("  Message:", request.params.message);

    if (request.params.mode === "url") {

User-controlled value printed to terminal without ANSI escape sanitization. Malicious input can inject cursor-control sequences, rewrite earlier output, or hide shell commands from the operator.

// Find and select the request immediately

      const request = pendingRequests.find((r) => r.id === requestId);

      if (request) {

        console.log(

          "[ElicitationTab] Selecting request from event:",

          requestId

        );

        setSelectedRequest(request);

        setTimeout(() => {

          const requestElement = document.getElementById(

User-controlled value printed to terminal without ANSI escape sanitization. Malicious input can inject cursor-control sequences, rewrite earlier output, or hide shell commands from the operator.

const query = `What's the current time and date? Also create a simple text file with today's date.`;

  console.log(`📝 Query: ${query}\n`);

  console.log("🔄 Streaming fine-grained events...\n");

  try {

User-controlled value printed to terminal without ANSI escape sanitization. Malicious input can inject cursor-control sequences, rewrite earlier output, or hide shell commands from the operator.

// Register notification handler

session.on("notification", async (notification) => {

  console.log(`Received: ${notification.method}`, notification.params);

});

```

User-controlled value printed to terminal without ANSI escape sanitization. Malicious input can inject cursor-control sequences, rewrite earlier output, or hide shell commands from the operator.

* ```typescript

 * // Log all tool calls

 * server.use('mcp:tools/call', async (ctx, next) => {

 *   console.log(`Calling tool: ${ctx.params.name}`);

 *   const result = await next();

 *   return result;

 * });

User-controlled value printed to terminal without ANSI escape sanitization. Malicious input can inject cursor-control sequences, rewrite earlier output, or hide shell commands from the operator.

});

  try {

    console.log("📝 Running query with custom config...\n");

    const result = await agent.run("What files are in this directory?");

    console.log("\n✅ Result:");

User-controlled value printed to terminal without ANSI escape sanitization. Malicious input can inject cursor-control sequences, rewrite earlier output, or hide shell commands from the operator.

}>;

      const requestId = customEvent.detail.requestId;

      console.log("[SamplingTab] Custom navigate event received:", requestId);

      // Find and select the request immediately

      const request = pendingRequests.find((r) => r.id === requestId);

User-controlled value printed to terminal without ANSI escape sanitization. Malicious input can inject cursor-control sequences, rewrite earlier output, or hide shell commands from the operator.

try {

        listener(...args);

      } catch (e) {

        console.error("Error in event listener:", e);

      }

    });

  }

Silent error swallowing detected. An except clause that does pass or ... discards the exception with no log, no metric, and no trace. This blinds incident response and hides real failures.

if (stored && window.openai) {

              window.openai.widgetState = JSON.parse(stored);

            }

          } catch (err) {}

        }, 0);

      })();

    </script>

Silent error swallowing detected. An except clause that does pass or ... discards the exception with no log, no metric, and no trace. This blinds incident response and hides real failures.

# This catches non-McpError exceptions, like a direct httpx timeout

                # but in the most cases this won't happen. It's for safety.

                try:

                    await raw_test_client.__aexit__(None, None, None)

                except Exception:

                    pass

                raise init_error

        # Exception from the inner try is propagated here and in

Silent error swallowing detected. An except clause that does pass or ... discards the exception with no log, no metric, and no trace. This blinds incident response and hides real failures.

json_str = json_str.replace("\\'", "'")

        json_str = json_str.replace("\\\\", "\\")

        try:

            return json.loads(json_str)

        except json.JSONDecodeError:

            pass

    return None

Silent error swallowing detected. An except clause that does pass or ... discards the exception with no log, no metric, and no trace. This blinds incident response and hides real failures.

if isinstance(content, dict | list):

        try:

            formatted = json.dumps(content, indent=2)

            return Markdown(f"```json\n{formatted}\n```", code_theme=CODE_THEME)

        except (TypeError, ValueError):

            pass

    # If it already has markdown code blocks, render as is

    if "```" in content_str:

Silent error swallowing detected. An except clause that does pass or ... discards the exception with no log, no metric, and no trace. This blinds incident response and hides real failures.

# Put response in queue

            try:

                self.response_queue.put_nowait(response)

            except asyncio.QueueFull:

                pass  # Ignore if queue is already full

            # Return success page

            if response.code: