Model Context Protocol: Anwendungsbeispiel in TypeScript

Das KI-Unternehmen Anthropic, das 2021 von ehemaligen OpenAI-Mitarbeitern gegründet wurde, hat das Model Context Protocol (MCP) mit dem Ziel einer Standardisierung der Kommunikation zwischen Large Language Models und externen Datenquellen entwickelt. Beim sogenannten Tool Calling hat das LLM die Möglichkeit, auf vordefinierte Schnittstellen zuzugreifen. Diese lassen sich parametrisieren und erlauben so große Flexibilität. Die meisten LLM-Anbieter unterstützen dieses Feature. Jede Datenquelle braucht dabei eine Verknüpfung über eine eigene Funktion, was in der Regel eine Anpassung am Programmcode erforderlich macht.

Das Model Context Protocol soll die Verknüpfung externer Datenquellen deutlich vereinfachen und es erlauben, externe Schnittstellen, Datenbanken, Unternehmenssysteme oder Dateisysteme ohne zusätzliche Anpassung direkt anzubinden. Dieser Artikel widmet sich den technischen Details der Funktionsweise des MCP und zeigt anhand eines konkreten Beispiels mit dem MCP-TypeScript-SDK, wie eine Integration in eine Applikation gelingen kann.

Die zentrale Anlaufstelle für Ressourcen zum Thema MCP sind zum einen die offizielle Website des Projekts und zum anderen das GitHub-Repo. Dort stehen die Dokumentation, die Spezifikation und eine ganze Reihe von Software Development Kits (SDKs) für verschiedene Programmiersprachen wie Python, TypeScript, C# oder Kotlin zur Verfügung.

Die Architektur einer MCP-Applikation

Eine Applikation, die das MCP nutzt, besteht aus verschiedenen Komponenten:

• MCP-Server: Der Server ist die Stelle bei MCP, die ihre Funktionalität über das MCP zur Verfügung stellt. Das können Daten aus einer Datenbank, aber auch Suchergebnisse aus dem Internet sein. Die Schnittstellen des Servers sind exakt definiert und lassen sich von der Clientseite verwenden.
• MCP-Client: Die Gegenseite zum Server ist der Client. Er kommuniziert mit dem Server und führt die verfügbaren Operationen über die Schnittstellen aus. Dabei gibt es sowohl lesende als auch schreibende Operationen.
• MCP-Host: Die Applikation, mit der die Benutzer interagieren. Das kann eine Web-Applikation, eine klassische Desktop-Applikation (wie Claude Desktop), eine Entwicklungsumgebung (wie Cursor) oder ein eigener, auf Frameworks wie Langchain basierender Agent sein. In diese Applikation ist der Client eingebettet, sodass der Host nicht direkt über MCP mit dem Server, sondern über den Umweg des Clients kommuniziert.

MCP-Server

Ein MCP-Server kann direkt in eine Applikation integriert, aber auch, und das wird der häufigere Fall sein, ein eigenständiger Dienst sein. Die MCP-Initiative stellt eine Reihe von SDKs in unterschiedlichen Programmiersprachen bereit, die die Grundlage für die Serverimplementierung bilden. Der Server selbst ist modular aufgebaut und erlaubt verschiedene Transportmechanismen, über die er mit den Clients kommuniziert. Das TypeScript-SDK sieht aktuell die Transportmechanismen Streamable HTTP, SSE und stdio vor. Streamable HTTP und SSE basieren auf HTTP, wobei die MCP-Spezifikation vom 26.03.2025 den SSE-Transport als veraltet (deprecated) markierte und die Version vom 18.06.2025 (latest) SSE bereits nicht mehr erwähnt.

Ein MCP-Client kann die HTTP-basierten Transportmechanismen verwenden, um sich mit einem entfernten Server zu verbinden. Der stdio-Transport ist für lokale Anwendungen gedacht. Hierbei verbindet sich der Client über die Standard-Ein- und -Ausgabe mit dem Server. Dieser Weg arbeitet deutlich schneller, ist jedoch nur für die Verwendung auf einem System geeignet. Das Python-SDK definiert zusätzlich zu diesen Transporttypen noch weitere wie den ASGI-Transport (Asynchronous Server Gateway Interface), eine Schnittstelle aus der Python-Welt, die neben der Kommunikation über HTTP noch weitere Protokolle wie WebSockets oder benutzerdefinierte Protokolle unterstützt.

Die MCP-Spezifikation unterteilt die Features, die ein Server seinen Clients bietet, in drei Kategorien: Resources, Tools und Prompts.

Resources

Mit der Feature-Kategorie Resources stellt ein MCP-Server Daten zur Verfügung. Ein typisches Beispiel ist die Anbindung an eine Datenbank. Resources sollten Daten nur lesend zur Verfügung stellen, keine komplexen Berechnungen durchführen und keine Seiteneffekte wie Datenmanipulationen aufweisen. Sie sind parametrisierbar, um die Abfrage zu beeinflussen und eine höhere Flexibilität zu erreichen.

Die MCP-Spezifikation sieht vor, dass das Format [protocol]://[host]/[path] Resources spezifiziert. Ein Beispiel könnte folgendermaßen aussehen: postgres://database/users. Die Antwort auf eine Resources-Anfrage kann entweder im Textformat wie beispielsweise JSON oder als Binärdaten wie PDFs oder Bilder erfolgen.

Der MCP-Server stellt über den Endpunkt resources/list eine Liste der verfügbaren Resources zur Verfügung. Jeder Datensatz weist mindestens die URL der jeweiligen Resource und einen menschenlesbaren Namen auf. Hinzu kommen noch eine optionale Beschreibung und ein ebenfalls optionaler MIME-Type, der das Format der Rückmeldung spezifiziert.

Die Spezifikation sieht nicht nur den lesenden Zugriff auf Ressourcen vor, sondern auch einen Benachrichtigungsmechanismus, über den der Server registrierte Clients über Änderungen der verfügbaren sowie Datenänderungen einer einzelnen Resource benachrichtigen kann.

Tools

Die Features der Kategorie Tools dürfen Berechnungen durchführen und Seiteneffekte aufweisen. Clients müssen berücksichtigen, dass eine Toolausführung im Vergleich zu einer Ressourcenabfrage länger dauern kann. Diese Werkzeuge können Funktionen sein, die aufgrund einer Eingabe eine bestimmte Ausgabe produzieren, aber auch Schnittstellen zu Datenbanken und anderen Systemen, um dort gespeicherte Informationen zu manipulieren. Ähnlich wie Resources können Clients auch die verfügbaren Tools eines Servers über einen Endpunkt auslesen. Dieser lautet tools/list.

Die Beschreibung eines MCP-Tools ist etwas umfangreicher als die einer Resource. Sie enthält einen Namen und ein Input-Schema, um die Parameter des Tools zu beschreiben. Hinzu kommen noch dessen optionale Beschreibung und optionale Metadaten über die Tool-Annotations. Die Annotations liefern Clients beziehungsweise Hinweise für Entwicklerinnen und Entwicklern über das Verhalten eines Tools. Die meisten vordefinierten Annotations der MCP-Spezifikation sind Boolean-Werte. So sagt beispielsweise die readOnlyHint-Annotation aus, dass das Tool sein Umfeld nicht modifiziert. Wie auch bei den Resources kann ein Client sich beim Server registrieren, um über Änderungen benachrichtigt zu werden.

Prompts

Prompts sind Vorlagen, die dem MCP-Host die Arbeit mit dem Large Language Model (LLM) erleichtern. Damit kann eine MCP-Applikation nicht nur die Kommunikation zwischen Client und Server, sondern auch zum LLM hin standardisieren. Bei einer Applikation, die ein Code-Review-Feature anbietet, dient der Prompt beispielsweise dazu, den zu überprüfenden Code korrekt einzubetten. Laut der MCP-Spezifikation besitzen die Prompt-Templates einen eindeutigen Namen. Zusätzlich sieht die Spezifikation noch die optionalen Felder description für eine menschenlesbare Beschreibung und arguments mit einer Liste der unterstützten Argumente des Schemas vor.

Die Prompt-Endpunkte eines MCP-Servers kommen ähnlich wie Tools zum Einsatz. Der Client fragt nach dem eindeutigen Identifier und übermittelt die benötigten Werte. Der Server antwortet mit dem Prompt, in den die Werte integriert sind, sodass der Client beziehungsweise die Host-Applikation den Prompt direkt verwenden kann.Für eine Liste aller verfügbaren Prompts bietet der MCP-Server den Endpunkt prompts/list an.

Die SDKs, die die MCP-Initiative zur Verfügung stellt, implementieren die Spezifikation und dienen als Grundlage für die Implementierung von MCP-Servern und MCP-Clients. Das folgende Beispiel implementiert einen einfachen MCP-Server mit je einer Resource, einem Tool und einem Prompt mit dem TypeScript-SDK.

import {
  McpServer,
  ResourceTemplate,
} from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({
  name: 'mcp-server',
  version: '1.0.0',
});

server.tool(
  'currency-converter',
  'Convert currency between EUR and USD',
  {
    amount: z.number(),
    from: z.enum(['EUR', 'USD']),
    to: z.enum(['EUR', 'USD']),
  },
  async ({ amount, from, to }) => {
    const exchangeRate =
      from === 'EUR' && to === 'USD'
        ? 1.1
        : from === 'USD' && to === 'EUR'
        ? 0.91
        : 1;
    const convertedAmount = amount * exchangeRate;
    return {
      content: [
        {
          type: 'text',
          text: `${amount} ${from} is ${convertedAmount.toFixed(2)} ${to}`,
        },
      ],
    };
  }
);

server.resource(
  'price-list',
  new ResourceTemplate('price-list://products/{category}', {
    list: undefined,
  }),
  async (uri, { category }) => {
    const priceList = [
      { name: 'Apple', category: 'Fruit', price: 1.2 },
      { name: 'Banana', category: 'Fruit', price: 0.8 },
      { name: 'Carrot', category: 'Vegetable', price: 0.5 },
      { name: 'Bread', category: 'Bakery', price: 2.5 },
      { name: 'Milk', category: 'Dairy', price: 1.5 },
    ];

    const filteredList =
      category !== 'all'
        ? priceList.filter(
            (item) => item.category.toLowerCase() === category.toLowerCase()
          )
        : priceList;

    return {
      contents: [
        {
          uri: uri.href,
          text: JSON.stringify(filteredList),
          json: filteredList,
        },
      ],
    };
  }
);

server.prompt(
  'get-product-description-prompt',
  {
    productName: z.string().describe('The name of the product.'),
    length: z
      .enum(['short', 'medium', 'long'])
      .optional()
      .describe('The desired length of the description.'),
  },
  async (input) => {
    const { productName, length } = input;

    let promptInstructions = `Please generate a compelling product description.`;

    let promptCore = `The product is named "${productName}". `;
    promptCore += `Focus on its general benefits and appeal. `;

    let refinements = '';

    if (length) {
      let lengthGuidance = '';
      if (length === 'short')
        lengthGuidance = 'Keep it concise, around 1-2 sentences. ';
      if (length === 'medium')
        lengthGuidance = 'Aim for a paragraph of about 3-5 sentences. ';
      if (length === 'long')
        lengthGuidance =
          'Provide a detailed description, potentially multiple paragraphs. ';
      refinements += lengthGuidance;
    }

    const fullPrompt = `${promptInstructions}\n\nProduct Details:\n${promptCore}\n\nStyle and Constraints:\n${refinements.trim()}`;

    return {
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: fullPrompt,
          },
        },
      ],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Listing 1: MCP-Serverimplementierung

Die Grundlage für das Beispiel bildet das TypeScript-SDK, das mit dem Kommando npm install @modelcontextprotocol/sdk installiert wird. Das Paket stellt mit der McpServer-Klasse die Grundlage für die Serverimplementierung zur Verfügung. Auf der Server-Instanz sind die Methoden tool, resource und prompt implementiert, die die Schnittstelle zur Registrierung der verschiedenen MCP-Features darstellen. Nachdem die Applikation alle Features registriert hat, ruft sie die connect-Methode der Serverinstanz auf und übergibt ein Transport-Objekt. Das kann wie im Beispiel eine Instanz der StdioServerTransport-Klasse für den Stdio-Transport sein oder auch eine Instanz der StreamableHTTPServerTransport-Klasse für eine Remote-Schnittstelle über Streamable-HTTP. Alternativ dazu unterstützt das TypeScript-SDK auch noch die SSEServerTransport-Klasse für Server Sent Events als Transportmethode.

Für die Implementierung der einzelnen Features des MCP-Servers gelten einige Regeln, die das SDK mit einer sehr strikten Schemavalidierung absichert. Folgt die Implementierung nicht diesen Regeln, lässt sich der Serverprozess nicht starten. Die Validierung stellt auch die Konsistenz der Argumente beim Aufruf sicher und spielt damit eine wichtige Rolle bei der Sicherheit in der Applikation.

Resource im Beispiel

Zur Definition von Resources sieht das SDK die resource-Methode des Serverobjekts vor. Diese Methode akzeptiert die Bezeichnung der Resource, die zugehörige URL und eine Callback-Funktion, die das Ergebnis produziert. Die Callback-Funktion darf asynchron sein, sodass auch der Anbindung einer Datenbank nichts im Wege steht. Eine Besonderheit gibt es bei der Registrierung von Resources allerdings: Ist die URL als Zeichenkette angegeben, darf sie keine dynamischen Parameter enthalten. Für diesen Fall akzeptiert die resource-Methode eine ResourceTemplate-Instanz. Hier werden die Parameter im Pfad mit geschweiften Klammern gekennzeichnet. Die Callback-Funktion kann über ihr zweites Argument auf die Parameter der URL zugreifen und das Ergebnis entsprechend modifizieren.

Im Beispiel ist die Resource eine statische Preisliste für eine Reihe von Produkten. Sie trägt die Bezeichnung price-list und ist über die URL price-list://products/{category} erreichbar, wobei category für eine Kategorie steht, nach der die Callback-Funktion die Datensätze filtert. Das TypeScript-SDK arbeitet mit Zod als Validierungsbibliothek und nutzt diese beispielsweise für die Überprüfung des Rückgabewerts der Resource-Callback-Funktion, sodass diese verpflichtend eine gewisse Struktur zurückgeben muss. Das contents-Array im Rückgabewert kann eine Reihe von Objekten aufweisen, die mindestens über die Eigenschaften uri und text verfügen müssen. Zusätzlich akzeptiert das SDK noch weitere Eigenschaften wie json, in der die Daten als JSON-Objekt vorliegen dürfen.