Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Schnellstart für MCP-Server und Benutzeroberflächen

Erstelle einen MCP-Server für ChatGPT und Codex und ergänze bei Bedarf eine Benutzeroberfläche für ChatGPT.

Einführung

Plugins nutzen das Model Context Protocol (MCP), um ChatGPT und Codex serverseitige Funktionen zur Verfügung zu stellen. In diesem Tutorial verwendest du folgende Komponenten:

  1. Einen MCP-Server, der Tools definiert und sie ChatGPT und Codex zur Verfügung stellt.
  2. Eine optionale Webkomponente, die ChatGPT in einem Iframe anzeigt.

ChatGPT implementiert den offenen UI-Standard MCP Apps. Du kannst deine Benutzeroberfläche also einmal entwickeln und auf allen Hosts ausführen, die MCP Apps unterstützen.

In diesem Schnellstart entwickelst du eine einfache Aufgabenliste, in der du Aufgaben hinzufügen und als erledigt markieren kannst. Die Benutzeroberfläche besteht aus einer einzigen HTML-Datei, die Markup, CSS und JavaScript enthält.

Komplexere Beispiele mit React findest du im Repository mit Beispielen auf GitHub.

Eine Webkomponente erstellen

Dieser Schritt ist optional. Wenn du nur Tools brauchst und keine Benutzeroberfläche für ChatGPT, fahre mit dem Abschnitt Einen MCP-Server erstellen fort und registriere keine UI-Ressource.

Lege in einem neuen Verzeichnis die Datei public/todo-widget.html an. Sie enthält die Webkomponente für die Benutzeroberfläche in ChatGPT. ChatGPT zeigt sie an, sobald das zugehörige MCP-Tool sie zurückgibt.

Füge folgenden Inhalt ein:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Todo list</title>
    <style>
      :root {
        color: #0b0b0f;
        font-family:
          "Inter",
          system-ui,
          -apple-system,
          sans-serif;
      }

      html,
      body {
        width: 100%;
        min-height: 100%;
        box-sizing: border-box;
      }

      body {
        margin: 0;
        padding: 16px;
        background: #f6f8fb;
      }

      main {
        width: 100%;
        max-width: 360px;
        min-height: 260px;
        margin: 0 auto;
        background: #fff;
        border-radius: 16px;
        padding: 20px;
        box-shadow: 0 12px 24px rgba(15, 23, 42, 0.08);
      }

      h2 {
        margin: 0 0 16px;
        font-size: 1.25rem;
      }

      form {
        display: flex;
        gap: 8px;
        margin-bottom: 16px;
      }

      form input {
        flex: 1;
        padding: 10px 12px;
        border-radius: 10px;
        border: 1px solid #cad3e0;
        font-size: 0.95rem;
      }

      form button {
        border: none;
        border-radius: 10px;
        background: #111bf5;
        color: white;
        font-weight: 600;
        padding: 0 16px;
        cursor: pointer;
      }

      form button:disabled {
        opacity: 0.7;
        cursor: not-allowed;
      }

      input[type="checkbox"] {
        accent-color: #111bf5;
      }

      ul {
        list-style: none;
        padding: 0;
        margin: 0;
        display: flex;
        flex-direction: column;
        gap: 8px;
      }

      li {
        background: #f2f4fb;
        border-radius: 12px;
        padding: 10px 14px;
        display: flex;
        align-items: center;
        gap: 10px;
      }

      li span {
        flex: 1;
      }

      li[data-completed="true"] span {
        text-decoration: line-through;
        color: #6c768a;
      }

      li[data-busy="true"] {
        opacity: 0.7;
      }
    </style>
  </head>
  <body>
    <main>
      <h2>Todo list</h2>
      <form id="add-form" autocomplete="off">
        <input id="todo-input" name="title" placeholder="Add a task" />
        <button type="submit">Add</button>
      </form>
      <ul id="todo-list"></ul>
    </main>

    <script type="module">
      const listEl = document.querySelector("#todo-list");
      const formEl = document.querySelector("#add-form");
      const inputEl = document.querySelector("#todo-input");
      const addButtonEl = formEl.querySelector('button[type="submit"]');
      const addButtonText = addButtonEl.textContent;

      let tasks = [];
      let isAdding = false;
      const busyTodoIds = new Set();

      const render = () => {
        listEl.innerHTML = "";
        tasks.forEach((task) => {
          const li = document.createElement("li");
          li.dataset.id = task.id;
          li.dataset.completed = String(Boolean(task.completed));
          li.dataset.busy = String(busyTodoIds.has(task.id));

          const label = document.createElement("label");
          label.style.display = "flex";
          label.style.alignItems = "center";
          label.style.gap = "10px";

          const checkbox = document.createElement("input");
          checkbox.type = "checkbox";
          checkbox.checked = Boolean(task.completed);
          checkbox.disabled = busyTodoIds.has(task.id);

          const span = document.createElement("span");
          span.textContent = task.title;

          label.appendChild(checkbox);
          label.appendChild(span);
          li.appendChild(label);
          listEl.appendChild(li);
        });
      };

      const updateFromResponse = (response) => {
        if (response?.structuredContent?.tasks) {
          tasks = response.structuredContent.tasks;
          render();
        }
      };

      // MCP Apps standard bridge: JSON-RPC messages over postMessage.
      //
      // - Initialize the bridge with `ui/initialize`.
      // - Confirm readiness with `ui/notifications/initialized`.
      // - Call tools with `tools/call`.
      // - Listen for `ui/notifications/tool-result` to react to model-initiated tool calls.
      let rpcId = 0;
      const pendingRequests = new Map();

      const rpcNotify = (method, params) => {
        window.parent.postMessage({ jsonrpc: "2.0", method, params }, "*");
      };

      const rpcRequest = (method, params) =>
        new Promise((resolve, reject) => {
          const id = ++rpcId;
          pendingRequests.set(id, { resolve, reject });
          window.parent.postMessage(
            { jsonrpc: "2.0", id, method, params },
            "*"
          );
        });

      window.addEventListener(
        "message",
        (event) => {
          if (event.source !== window.parent) return;
          const message = event.data;
          if (!message || message.jsonrpc !== "2.0") return;

          // Responses
          if (typeof message.id === "number") {
            const pending = pendingRequests.get(message.id);
            if (!pending) return;
            pendingRequests.delete(message.id);

            if (message.error) {
              pending.reject(message.error);
              return;
            }

            pending.resolve(message.result);
            return;
          }

          // Notifications
          if (typeof message.method !== "string") return;
          if (message.method === "ui/notifications/tool-result") {
            updateFromResponse(message.params);
          }
        },
        { passive: true }
      );

      const initializeBridge = async () => {
        const appInfo = { name: "todo-widget", version: "0.1.0" };
        const appCapabilities = {};
        const protocolVersion = "2026-01-26";

        try {
          await rpcRequest("ui/initialize", {
            appInfo,
            appCapabilities,
            protocolVersion,
          });
          rpcNotify("ui/notifications/initialized", {});
        } catch (error) {
          console.error("Failed to initialize the MCP Apps bridge:", error);
          throw error;
        }
      };

      const bridgeReady = initializeBridge();

      const callTodoTool = async (name, payload) => {
        await bridgeReady;
        const response = await rpcRequest("tools/call", {
          name,
          arguments: payload,
        });
        updateFromResponse(response);
      };

      formEl.addEventListener("submit", async (event) => {
        event.preventDefault();
        const title = inputEl.value.trim();
        if (!title || isAdding) return;

        isAdding = true;
        addButtonEl.disabled = true;
        addButtonEl.textContent = "Adding…";

        try {
          await callTodoTool("add_todo", { title });
          inputEl.value = "";
        } catch (error) {
          console.error("Failed to add todo:", error);
        } finally {
          isAdding = false;
          addButtonEl.disabled = false;
          addButtonEl.textContent = addButtonText;
        }
      });

      listEl.addEventListener("change", async (event) => {
        const checkbox = event.target;
        if (!checkbox.matches('input[type="checkbox"]')) return;
        const id = checkbox.closest("li")?.dataset.id;
        if (!id) return;

        if (!checkbox.checked) {
          checkbox.checked = true;
          return;
        }

        if (busyTodoIds.has(id)) return;
        busyTodoIds.add(id);
        checkbox.disabled = true;
        const rowEl = checkbox.closest("li");
        if (rowEl) rowEl.dataset.busy = "true";

        try {
          await callTodoTool("complete_todo", { id });
        } catch (error) {
          console.error("Failed to complete todo:", error);
        } finally {
          busyTodoIds.delete(id);
          render();
        }
      });

      render();
    </script>
  </body>
</html>

MCP Apps in deiner Webkomponente verwenden

Verwende für neue Benutzeroberflächen die Host-Bridge von MCP Apps. Sie überträgt JSON-RPC-Nachrichten über postMessage und unterstützt ui/*-Benachrichtigungen sowie Methoden wie tools/call.

Sobald die hostübergreifende Kommunikation über MCP Apps funktioniert, kannst du über window.openai optionale ChatGPT-Erweiterungen hinzufügen. Nutze sie nur, wenn du Funktionen brauchst, die der Standard nicht abdeckt. Einzelheiten findest du im Abschnitt Deinen MCP-Server um eine Benutzeroberfläche erweitern.

Einen MCP-Server erstellen

Installiere das offizielle MCP-SDK für Python oder TypeScript, um einen Server zu erstellen und unter /mcp einen Endpunkt bereitzustellen.

In diesem Schnellstart verwenden wir das TypeScript-SDK.

Wenn du Python verwendest, findest du in unserem Repository mit Beispielen auf GitHub einen MCP-Server, der das Python-SDK nutzt.

Verwende Node.js 22.6 oder neuer. Installiere das TypeScript-SDK, die Hilfsfunktionen für MCP Apps und das Paket zod mit folgendem Befehl:

npm install @modelcontextprotocol/sdk @modelcontextprotocol/ext-apps zod

MCP-Server mit UI-Ressourcen

Registriere eine Ressource für dein Komponenten-Bundle und die Tools, die das Modell aufrufen kann (zum Beispiel add_todo und complete_todo). So kann ChatGPT die Benutzeroberfläche steuern.

Erstelle die Datei server.ts und füge den folgenden Beispielcode ein, der das TypeScript-SDK verwendet:

import { createServer } from "node:http";
import { readFileSync } from "node:fs";
import {
  registerAppResource,
  registerAppTool,
  RESOURCE_MIME_TYPE,
} from "@modelcontextprotocol/ext-apps/server";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { z } from "zod";

const todoHtml = readFileSync("public/todo-widget.html", "utf8");

const addTodoInputSchema = {
  title: z.string().min(1),
};

const completeTodoInputSchema = {
  id: z.string().min(1),
};

const todoOutputSchema = {
  tasks: z.array(
    z.object({
      id: z.string(),
      title: z.string(),
      completed: z.boolean(),
    })
  ),
};

let todos: { id: string; title: string; completed: boolean }[] = [];
let nextId = 1;

const replyWithTodos = (message: string) => ({
  content: message ? [{ type: "text" as const, text: message }] : [],
  structuredContent: { tasks: todos },
});

function createTodoServer() {
  const server = new McpServer({
    name: "todo-plugin-server",
    version: "0.1.0",
  });

  registerAppResource(
    server,
    "todo-widget",
    "ui://widget/todo.html",
    {},
    async () => ({
      contents: [
        {
          uri: "ui://widget/todo.html",
          mimeType: RESOURCE_MIME_TYPE,
          text: todoHtml,
        },
      ],
    })
  );

  registerAppTool(
    server,
    "add_todo",
    {
      title: "Add todo",
      description: "Creates a todo item with the given title.",
      inputSchema: addTodoInputSchema,
      outputSchema: todoOutputSchema,
      _meta: {
        ui: { resourceUri: "ui://widget/todo.html" },
      },
    },
    async (args) => {
      const title = args?.title?.trim?.() ?? "";
      if (!title) return replyWithTodos("Missing title.");
      const todo = { id: `todo-${nextId++}`, title, completed: false };
      todos = [...todos, todo];
      return replyWithTodos(`Added "${todo.title}".`);
    }
  );

  registerAppTool(
    server,
    "complete_todo",
    {
      title: "Complete todo",
      description: "Marks a todo as done by id.",
      inputSchema: completeTodoInputSchema,
      outputSchema: todoOutputSchema,
      _meta: {
        ui: { resourceUri: "ui://widget/todo.html" },
      },
    },
    async (args) => {
      const id = args?.id;
      if (!id) return replyWithTodos("Missing todo id.");
      const todo = todos.find((task) => task.id === id);
      if (!todo) {
        return replyWithTodos(`Todo ${id} was not found.`);
      }

      todos = todos.map((task) =>
        task.id === id ? { ...task, completed: true } : task
      );

      return replyWithTodos(`Completed "${todo.title}".`);
    }
  );

  return server;
}

const port = Number(process.env.PORT ?? 8787);
const MCP_PATH = "/mcp";

const httpServer = createServer(async (req, res) => {
  if (!req.url) {
    res.writeHead(400).end("Missing URL");
    return;
  }

  const url = new URL(req.url, `http://${req.headers.host ?? "localhost"}`);

  if (req.method === "OPTIONS" && url.pathname === MCP_PATH) {
    res.writeHead(204, {
      "Access-Control-Allow-Origin": "*",
      "Access-Control-Allow-Methods": "POST, GET, OPTIONS",
      "Access-Control-Allow-Headers": "content-type, mcp-session-id",
      "Access-Control-Expose-Headers": "Mcp-Session-Id",
    });
    res.end();
    return;
  }

  if (req.method === "GET" && url.pathname === "/") {
    res.writeHead(200, { "content-type": "text/plain" }).end("Todo MCP server");
    return;
  }

  const MCP_METHODS = new Set(["POST", "GET", "DELETE"]);
  if (url.pathname === MCP_PATH && req.method && MCP_METHODS.has(req.method)) {
    res.setHeader("Access-Control-Allow-Origin", "*");
    res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");

    const server = createTodoServer();
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined, // stateless mode
      enableJsonResponse: true,
    });

    res.on("close", () => {
      transport.close();
      server.close();
    });

    try {
      await server.connect(transport);
      await transport.handleRequest(req, res);
    } catch (error) {
      console.error("Error handling MCP request:", error);
      if (!res.headersSent) {
        res.writeHead(500).end("Internal server error");
      }
    }
    return;
  }

  res.writeHead(404).end("Not Found");
});

httpServer.listen(port, () => {
  console.log(
    `Todo MCP server listening on http://localhost:${port}${MCP_PATH}`
  );
});

Mit diesem Code beantwortet der Server auch GET / für Zustandsprüfungen und verarbeitet CORS-Preflight-Anfragen für /mcp. Für OAuth-Discovery-Routen, die du noch nicht nutzt, gibt er 404 Not Found zurück. So zeigt ChatGPT keine 502-Fehler an, während du den Server ohne Authentifizierung weiterentwickelst.

Lokal ausführen

Wenn du ein Webframework wie React verwendest, kompiliere deine Komponente zu statischen Dateien, damit die HTML-Vorlage deren Inhalt direkt einbetten kann. In der Regel erzeugt ein Build-Befehl wie npm run build ein Verzeichnis namens dist mit den kompilierten Dateien.

In diesem Schnellstart verwenden wir reines HTML. Ein Build-Schritt entfällt daher.

Starte den MCP-Server unter http://localhost:<port>/mcp. Führe dazu die folgenden Schritte in dem Verzeichnis aus, das server.ts enthält.

Stelle sicher, dass "type": "module" in deiner Datei package.json steht:

{
  "type": "module",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.20.2",
    "@modelcontextprotocol/ext-apps": "^1.0.1",
    "zod": "^3.25.76"
  }
}

Starte den Server anschließend mit folgendem Befehl:

node --experimental-strip-types server.ts

Sobald der Server bereit ist, sollte er Todo MCP server listening on http://localhost:8787/mcp ausgeben.

Mit dem MCP Inspector testen

Mit dem MCP Inspector kannst du deinen Server lokal testen.

npx @modelcontextprotocol/inspector@latest

Der Befehl öffnet die Benutzeroberfläche des MCP Inspector. Wähle „Streamable HTTP“, gib http://localhost:8787/mcp ein und stelle die Verbindung her. Jetzt kannst du deinen Server testen und die Antworten seiner Tools prüfen.

Benutzeroberfläche des MCP Inspector

Deinen Server über das Internet erreichbar machen

Damit ChatGPT während der Entwicklung auf deinen Server zugreifen kann, muss er über das öffentliche Internet erreichbar sein. Mit einem Tool wie ngrok kannst du einen Tunnel zu deinem lokalen Server öffnen.

ngrok http <port>

Du erhältst eine öffentliche URL wie https://<subdomain>.ngrok.app, über die du von ChatGPT aus auf deinen Server zugreifen kannst.

Wenn du deinen MCP-Server in ChatGPT verbindest, gib die öffentliche URL mit dem Pfad /mcp an (zum Beispiel https://<subdomain>.ngrok.app/mcp).

Deinen MCP-Server in ChatGPT verbinden

Sobald dein MCP-Server und deine Webkomponente lokal funktionieren, verbinde den Server in ChatGPT:

  1. Öffne die Plugins in ChatGPT, wähle die Schaltfläche mit dem Pluszeichen und dann „Benutzerdefinierten MCP-Server hinzufügen“.
  2. Füge die HTTPS-URL deines Tunnels oder deiner Bereitstellung einschließlich des Pfads /mcp ein (zum Beispiel https://<subdomain>.ngrok.app/mcp). Gib der Verbindung einen Namen und konfiguriere die Authentifizierung.
  3. Lies den Risikohinweis. Wähle „Ich verstehe die Risiken und möchte fortfahren“ und anschließend „Als Plugin erstellen“.
  4. Installiere das neu erstellte Plugin und öffne einen neuen Chat. Gib @ in das Eingabefeld ein und wähle das Plugin aus. Sende dem Modell einen Prompt, zum Beispiel „Füge ‚Mein Buch lesen‘ als neue Aufgabe hinzu“. ChatGPT überträgt die Daten der Tool-Aufrufe als Stream, sodass du die Ein- und Ausgaben überprüfen kannst.

Nächste Schritte

Jetzt kannst du die Benutzeroberfläche und ihre Bedienung verbessern, Prompts und Tool-Metadaten anpassen und das Nutzungserlebnis insgesamt weiterentwickeln.

Aktualisiere die Plugin-Verbindung nach jeder Änderung am MCP-Server, etwa an Tools, Metadaten oder der zugehörigen Konfiguration. Das geht auf der Detailseite des Plugins unter chatgpt.com/plugins.

Wenn du dein Plugin veröffentlichen möchtest, lies die Anleitung zum Einreichen von Plugins, die Richtlinien für Plugins und die Tipps zum Sammeln von Ideen für Plugin-Anwendungsfälle. Wenn du eine Benutzeroberfläche entwickelst, kannst du auch die UI-Richtlinien heranziehen.

Sobald du mit den Grundlagen vertraut bist, kannst du umfangreichere Benutzeroberflächen entwickeln, bei Bedarf die Nutzerauthentifizierung einrichten und den Zustand deiner App verwalten.