MCP-Entwicklerhandbuch

Das Model Context Protocol (MCP) ist ein offener Standard, der es KI-Modellen ermöglicht, über eine einheitliche Schnittstelle mit externen Tools und Diensten zu interagieren. Visual Studio Code implementiert die vollständige MCP-Spezifikation und ermöglicht es Ihnen, MCP-Server zu erstellen, die Tools, Prompts und Ressourcen für die Erweiterung der Fähigkeiten von KI-Agenten in VS Code bereitstellen.

MCP-Server stellen neben integrierten Tools und von Erweiterungen beigesteuerten Tools einen von drei verfügbaren Werkzeugtypen in VS Code bereit. Erfahren Sie mehr über Tool-Typen.

Dieses Handbuch behandelt alles, was Sie wissen müssen, um MCP-Server zu erstellen, die nahtlos mit VS Code und anderen MCP-Clients zusammenarbeiten.

Warum MCP-Server verwenden?

Die Implementierung eines MCP-Servers zur Erweiterung des Chats in VS Code mit Sprachmodell-Tools bietet die folgenden Vorteile

• Erweitern Sie den Agentenmodus mit spezialisierten, domänenspezifischen Tools, die automatisch als Teil der Antwort auf eine Benutzeraufforderung aufgerufen werden. Ermöglichen Sie beispielsweise das Erstellen und Abfragen von Datenbanken, um dem LLM dynamisch relevante Kontexte bereitzustellen.
• Flexible Bereitstellungsoptionen für lokale und Remote-Szenarien.
• Wiederverwendung Ihres MCP-Servers über verschiedene Tools und Plattformen hinweg.

Sie können die Implementierung eines Sprachmodell-Tools mit der Language Model API in den folgenden Szenarien in Betracht ziehen

• Sie möchten eine tiefe Integration mit VS Code durch die Verwendung von Erweiterungs-APIs.
• Sie möchten Ihr Tool und Updates über den Visual Studio Marketplace vertreiben.

Von VS Code unterstützte MCP-Funktionen

VS Code unterstützt die folgenden MCP-Funktionen

• Transporte:

  • Lokale Standardein-/ausgabe (stdio)
  • Streamfähiges HTTP (http)
  • Server-Sent Events (sse) – Legacy-Unterstützung.

• Funktionen:

  • Tools: Erweitern Sie den Agentenmodus um zusätzliche Tools
  • Prompts: Fügen Sie wiederverwendbare Prompts als Slash-Befehle im Chat hinzu
  • Ressourcen: Stellen Sie Daten und Inhalte bereit, die Benutzer als Chat-Kontext hinzufügen oder direkt in VS Code bearbeiten können
  • Elicitation: Fordern Sie Eingaben vom Benutzer an
  • Sampling: Führen Sie Sprachmodell-Anfragen mit den konfigurierten Modellen und Abonnements des Benutzers durch
  • Authentifizierung: Autorisieren Sie den Zugriff auf einen MCP-Server mit OAuth
  • Serveranweisungen
  • Roots: Stellen Sie Informationen über die Stammordner des Benutzerarbeitsbereichs bereit

Werkzeuge

Tool-Definition

VS Code unterstützt MCP-Tools im Agentenmodus, wo sie bei Bedarf basierend auf der Aufgabe aufgerufen werden. Benutzer können sie mit dem Tool-Selektor aktivieren und konfigurieren. Die Tool-Beschreibung wird im Tool-Selektor neben dem Tool-Namen und im Dialogfeld bei der Aufforderung zur Bestätigung vor der Ausführung eines Tools angezeigt.

Benutzer können modellgenerierte Eingabeparameter im Bestätigungsdialog für Tools bearbeiten. Der Bestätigungsdialog wird für alle Tools angezeigt, die nicht mit der Annotation readOnlyHint gekennzeichnet sind.

Dynamische Tool-Erkennung

VS Code unterstützt auch die dynamische Tool-Erkennung, die es Servern ermöglicht, Tools zur Laufzeit zu registrieren. Ein Server kann beispielsweise unterschiedliche Tools basierend auf dem im Arbeitsbereich erkannten Framework oder der Sprache oder als Reaktion auf die Chat-Anfrage des Benutzers bereitstellen.

Tool-Annotationen

Um zusätzliche Metadaten über das Verhalten eines Tools bereitzustellen, können Sie Tool-Annotationen verwenden.

• title: Menschenlesbarer Titel für das Tool, der in der Chat-Ansicht angezeigt wird, wenn ein Tool aufgerufen wird
• readOnlyHint: Optionaler Hinweis, der angibt, dass das Tool schreibgeschützt ist. VS Code fragt nicht zur Bestätigung für schreibgeschützte Tools.

Ressourcen

Ressourcen ermöglichen es Ihnen, Daten und Inhalte strukturiert für Benutzer bereitzustellen. Benutzer können direkt in VS Code auf Ressourcen zugreifen oder sie als Kontext in Chat-Anfragen verwenden. Beispielsweise könnte ein MCP-Server Screenshots generieren und sie als Ressourcen verfügbar machen oder Zugriff auf Protokolldateien gewähren, die dann in Echtzeit aktualisiert werden.

Wenn Sie eine MCP-Ressource definieren, wird der Ressourcenname in den MCP-Ressourcen-Schnellauswahlen angezeigt. Ressourcen können über den Befehl MCP: Ressourcen durchsuchen geöffnet oder mit Kontext hinzufügen und anschließender Auswahl von MCP-Ressource an eine Chat-Anfrage angehängt werden. Ressourcen können Text oder Binärdaten enthalten.

VS Code unterstützt Ressourcenaktualisierungen, sodass Benutzer Änderungen am Inhalt einer Ressource in Echtzeit im Editor sehen können.

Ressourcenvorlagen

VS Code unterstützt auch Ressourcenvorlagen, die es Benutzern ermöglichen, Eingabeparameter bei der Referenzierung einer Ressource bereitzustellen. Beispielsweise könnte ein Datenbankabfragetool nach dem Namen der Datenbanktabelle fragen.

Beim Zugriff auf eine Ressource mit einer Vorlage wird dem Benutzer in einer Schnellauswahl nach den erforderlichen Parametern gefragt. Sie können Vervollständigungen bereitstellen, um Werte für den Parameter vorzuschlagen.

Prompts

Prompts sind wiederverwendbare Chat-Prompt-Vorlagen, die Benutzer im Chat über einen Slash-Befehl (mcp.servername.promptname) aufrufen können. Prompts können nützlich sein, um Benutzer bei der Einführung in Ihre Server zu unterstützen, indem sie verschiedene Tools hervorheben oder integrierte komplexe Workflows bereitstellen, die sich an den lokalen Kontext und Dienst des Benutzers anpassen.

Wenn Sie Vervollständigungen definieren, um Werte für Prompt-Eingabeargumente vorzuschlagen, zeigt VS Code einen Dialog an, um Eingaben vom Benutzer zu sammeln.

server.prompt(
  'teamGreeting',
  'Generate a greeting for team members',
  {
    name: completable(z.string(), value => {
      return ['Alice', 'Bob', 'Charlie'].filter(n => n.startsWith(value));
    })
  },
  async ({ name }) => ({
    messages: [
      {
        role: 'assistant',
        content: { type: 'text', text: `Hello ${name}, welcome to the team!` }
      }
    ]
  })
);

Wenn Sie einen Ressourcentyp in die Prompt-Antwort aufnehmen, hängt VS Code diese Ressource als Kontext an den Chat-Prompt an.

Autorisierung

VS Code unterstützt MCP-Server, die eine Authentifizierung erfordern, sodass Benutzer mit einem MCP-Server interagieren können, der im Namen ihres Benutzerkontos für diesen Dienst arbeitet.

Die Autorisierungsspezifikation trennt MCP-Server sauber als Ressourcenserver von Autorisierungsservern, was es Entwicklern ermöglicht, die Authentifizierung an bestehende Identitätsanbieter (IdPs) zu delegieren, anstatt eigene OAuth-Implementierungen von Grund auf neu zu erstellen.

VS Code verfügt über integrierte Authentifizierungsunterstützung für GitHub und Microsoft Entra. Wenn Ihr MCP-Server die neueste Spezifikation implementiert und GitHub oder Microsoft Entra als Autorisierungsserver verwendet, können Benutzer über die Aktion Konto-Menü > Vertrauenswürdige MCP-Server verwalten für dieses Konto verwalten, welche MCP-Server Zugriff auf ihr Konto haben.

VS Code unterstützt die Autorisierung nach OAuth 2.1- und 2.0-Standards für andere IdPs als GitHub und Microsoft Entra. VS Code beginnt zuerst mit einem Dynamic Client Registration (DCR)-Handshake und greift dann auf einen Client-Credentials-Workflow zurück, wenn der IdP DCR nicht unterstützt. Dies gibt den verschiedenen IdPs mehr Flexibilität, statische Client-IDs oder spezifische Client-ID-Geheimnispaare für jeden MCP-Server entsprechend zu erstellen.

Benutzer können ihren Authentifizierungsstatus dann auch über das Konto-Menü einsehen. Um dynamische Client-Registrierungen zu entfernen, können Benutzer den Befehl Authentifizierung: Dynamische Authentifizierungsanbieter entfernen in der Befehlspalette verwenden.

Nachfolgend finden Sie eine Checkliste, um sicherzustellen, dass Ihr MCP-Server und die OAuth-Workflows von VS Code funktionieren

1. Der MCP-Server definiert die MCP-Autorisierungsspezifikation.
2. Der IdP muss entweder DCR oder Client-Credentials unterstützen.
3. Die Liste der Weiterleitungs-URLs muss die folgenden URLs enthalten: http://127.0.0.1:33418 und https://vscode.dev/redirect.

Wenn DCR vom MCP-Server nicht unterstützt wird, durchlaufen die Benutzer den Fallback-Client-Credential-Flow.

Sampling

VS Code bietet MCP-Servern Zugriff auf Sampling. Dies ermöglicht Ihrem MCP-Server, Sprachmodell-Anfragen mit den konfigurierten Modellen und Abonnements des Benutzers durchzuführen. Verwenden Sie Sampling beispielsweise, um große Datensätze zusammenzufassen, Informationen zu extrahieren, bevor sie an den Client gesendet werden, oder um Agentenentscheidungslogik in einem Tool zu implementieren.

Beim ersten Sampling-Anfrage eines MCP-Servers wird der Benutzer aufgefordert, dem Server den Zugriff auf seine Modelle zu gestatten.

Bei Sampling-Anfragen mit bestimmten Modellen sollten Sie berücksichtigen, dass Benutzer einschränken können, welche Modelle ein MCP-Server verwenden darf, über den Befehl MCP: Server auflisten > Modellzugriff konfigurieren in der Befehlspalette. Wenn Sie modelPreferences in Ihrem MCP-Server angeben, um Hinweise zu geben, welche Modelle für das Sampling verwendet werden sollen, wählt VS Code aus den zugelassenen Modellen aus.

Benutzer können die von einem MCP-Server gemachten Sampling-Anfragen über den Befehl MCP: Server auflisten > Sampling-Anfragen anzeigen in der Befehlspalette einsehen.

Arbeitsbereichswurzeln

VS Code stellt dem MCP-Server die Informationen zu den Stammordnern des Benutzerarbeitsbereichs zur Verfügung.

Icons

VS Code unterstützt icons, die auf MCP-Servern, Ressourcen und Tools bereitgestellt werden. MCP-Icons haben eine src-Eigenschaft, die eine URI zum Bild ist.

• MCP-Server, die die HTTP- oder SSE-Transporte verwenden, können Bilder von derselben Autorität bereitstellen, auf der der MCP-Server gehostet wird. Ein Server, der unter https://example.com/mcp konfiguriert ist, kann beispielsweise Bilder von example.com bereitstellen.
• MCP-Server, die den stdio-Transport verwenden, können Bilder vom Dateisystem über file:/// URIs bereitstellen.
• Jeder MCP-Server kann Bilder als Data-URIs einbetten, die mit data: beginnen.

MCP-Server zu VS Code hinzufügen

Benutzer können MCP-Server auf verschiedene Weise innerhalb von VS Code hinzufügen

• Direkte Installation aus dem Web: Verwenden Sie eine spezielle MCP-Installations-URL (vscode:mcp/install) auf Ihrer Website.
• Arbeitsbereichskonfiguration: Geben Sie die Serverkonfiguration in einer .vscode/mcp.json-Datei im Arbeitsbereich an.
• Globale Konfiguration: Definieren Sie Server global im Profil des Benutzers.
• Automatische Erkennung: VS Code kann Server aus anderen Tools wie Claude Desktop erkennen.
• Erweiterung: VS Code-Erweiterungen können MCP-Server programmatisch registrieren.
• Befehlszeile: Installieren Sie MCP-Server über die Befehlszeile mit der VS Code-Befehlszeilenoption --add-mcp.

Erfahren Sie mehr über die verschiedenen Möglichkeiten, MCP-Server zu VS Code hinzuzufügen.

MCP-Server verwalten

Sie können die Liste der installierten MCP-Server über die Erweiterungsansicht (⇧⌘X (Windows, Linux Ctrl+Shift+X)) in VS Code verwalten.

Klicken Sie mit der rechten Maustaste auf einen MCP-Server oder wählen Sie das Zahnradsymbol aus, um verschiedene Verwaltungsaktionen für den Server auszuführen. Alternativ können Sie den Befehl MCP: Server auflisten aus der Befehlspalette ausführen, um die Liste der konfigurierten MCP-Server anzuzeigen. Sie können dann einen Server auswählen und Aktionen darauf ausführen.

Erstellen einer MCP-Installations-URL

VS Code stellt einen URL-Handler für die Installation eines MCP-Servers über einen Link bereit: vscode:mcp/install?{json-configuration} (Insiders: vscode-insiders:mcp/install?{json-configuration}).

Stellen Sie die JSON-Serverkonfiguration in der Form {\"name\":\"server-name\",\"command\":...} bereit und führen Sie dann eine JSON-Stringifizierung und URL-Codierung durch. Verwenden Sie beispielsweise die folgende Logik, um die Installations-URL zu erstellen

// For Insiders, use `vscode-insiders` instead of `code`
const link = `vscode:mcp/install?${encodeURIComponent(JSON.stringify(obj))}`;

Dieser Link kann in einem Browser verwendet oder auf der Befehlszeile geöffnet werden, z. B. über xdg-open $LINK unter Linux.

Registrieren eines MCP-Servers in Ihrer Erweiterung

Um einen MCP-Server in Ihrer Erweiterung zu registrieren, müssen Sie die folgenden Schritte ausführen

1. Definieren Sie den MCP-Server-Definitionsanbieter in der Datei package.json Ihrer Erweiterung.
2. Implementieren Sie den MCP-Server-Definitionsanbieter in Ihrem Erweiterungscode mithilfe der vscode.lm.registerMcpServerDefinitionProvider API.

Sie können mit einem einfachen Beispiel für die Registrierung eines MCP-Servers in einer VS Code-Erweiterung beginnen.

1. Statische Konfiguration in package.json

Erweiterungen, die MCP-Server registrieren möchten, müssen den Erweiterungspunkt contributes.mcpServerDefinitionProviders in package.json mit der id des Anbieters beitragen. Diese id sollte mit der in der Implementierung verwendeten übereinstimmen.

{
    ...
    "contributes": {
        "mcpServerDefinitionProviders": [
            {
                "id": "exampleProvider",
                "label": "Example MCP Server Provider"
            }
        ]
    }
    ...
}

2. Implementieren Sie den Anbieter

Um einen MCP-Server in Ihrer Erweiterung zu registrieren, verwenden Sie die API vscode.lm.registerMcpServerDefinitionProvider, um die MCP-Konfiguration für den Server bereitzustellen. Die API nimmt eine providerId-Zeichenfolge und ein McpServerDefinitionProvider-Objekt entgegen.

Das McpServerDefinitionProvider-Objekt hat drei Eigenschaften

• onDidChangeMcpServerDefinitions: Ereignis, das ausgelöst wird, wenn sich die MCP-Serverkonfigurationen ändern.
• provideMcpServerDefinitions: Funktion, die ein Array von MCP-Serverkonfigurationen (vscode.McpServerDefinition[]) zurückgibt.
• resolveMcpServerDefinition: Funktion, die der Editor aufruft, wenn der MCP-Server gestartet werden muss. Verwenden Sie diese Funktion, um zusätzliche Aktionen durchzuführen, die eine Benutzerinteraktion erfordern können, z. B. Authentifizierung.

Ein McpServerDefinition-Objekt kann einer der folgenden Typen sein

• vscode.McpStdioServerDefinition: Stellt einen MCP-Server dar, der durch Ausführen eines lokalen Prozesses und Betrieb seiner Standardein- und -ausgabeströme verfügbar ist.
• vscode.McpHttpServerDefinition: Stellt einen MCP-Server dar, der mit dem Streamable HTTP-Transport verfügbar ist.

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    const didChangeEmitter = new vscode.EventEmitter<void>();

    context.subscriptions.push(vscode.lm.registerMcpServerDefinitionProvider('exampleProvider', {
        onDidChangeMcpServerDefinitions: didChangeEmitter.event,
        provideMcpServerDefinitions: async () => {
            let servers: vscode.McpServerDefinition[] = [];

            // Example of a simple stdio server definition
            servers.push(new vscode.McpStdioServerDefinition(
            {
                label: 'myServer',
                command: 'node',
                args: ['server.js'],
                cwd: vscode.Uri.file('/path/to/server'),
                env: {
                    API_KEY: ''
                },
                version: '1.0.0'
            });

            // Example of an HTTP server definition
            servers.push(new vscode.McpHttpServerDefinition(
            {
                label: 'myRemoteServer',
                uri: 'https://:3000',
                headers: {
                    'API_VERSION': '1.0.0'
                },
                version: '1.0.0'
            }));

            return servers;
        },
        resolveMcpServerDefinition: async (server: vscode.McpServerDefinition) => {

            if (server.label === 'myServer') {
                // Get the API key from the user, e.g. using vscode.window.showInputBox
                // Update the server definition with the API key
            }

            // Return undefined to indicate that the server should not be started or throw an error
            // If there is a pending tool call, the editor will cancel it and return an error message
            // to the language model.
            return server;
        }
    }));
}

MCP-Server beheben und debuggen

MCP-Entwicklungsmodus in VS Code

Wenn Sie MCP-Server entwickeln, können Sie den Entwicklungsmodus für MCP-Server aktivieren, indem Sie einen dev-Schlüssel zur MCP-Serverkonfiguration hinzufügen. Dies ist ein Objekt mit zwei Eigenschaften

• watch: Ein Dateimuster (Glob), das auf Dateiänderungen überwacht wird, die den MCP-Server neu starten.

• debug: Ermöglicht Ihnen die Einrichtung eines Debuggers mit dem MCP-Server. Derzeit unterstützt VS Code das Debugging von Node.js- und Python-MCP-Servern.

  Node.js MCP-Server

  Um einen Node.js MCP-Server zu debuggen, setzen Sie die Eigenschaft debug.type auf node.

  {
    "servers": {
      "my-mcp-server": {
        "type": "stdio",
        "command": "node",
        "cwd": "${workspaceFolder}",
        "args": ["./build/index.js"],
        "dev": {
          "watch": "src/**/*.ts",
          "debug": { "type": "node" }
        }
      }
    }
  }
  

  Python MCP-Server

  Um einen Python MCP-Server zu debuggen, setzen Sie die Eigenschaft debug.type auf debugpy und setzen Sie optional die Eigenschaft debug.debugpyPath auf den Pfad des debugpy-Moduls, falls es nicht in der Standard-Python-Umgebung installiert ist.

  {
    "servers": {
      "my-python-mcp-server": {
        "type": "stdio",
        "command": "python",
        "cwd": "${workspaceFolder}",
        "args": ["./server.py"],
        "dev": {
          "watch": "**/*.py",
          "debug": {
            "type": "debugpy",
            "debugpyPath": "/path/to/debugpy"
          }
        }
      }
    }
  }
  

MCP-Ausgabeprotokoll

Wenn VS Code ein Problem mit einem MCP-Server feststellt, wird in der Chat-Ansicht ein Fehlerindikator angezeigt.

Wählen Sie die Fehlermeldung in der Chat-Ansicht aus und wählen Sie dann die Option Ausgabe anzeigen, um die Serverprotokolle anzuzeigen. Alternativ können Sie MCP: Server auflisten aus der Befehlspalette ausführen, den Server auswählen und dann Ausgabe anzeigen auswählen.

Best Practices

• Namenskonventionen, um eindeutige und aussagekräftige Namen sicherzustellen
• Implementieren Sie ordnungsgemäße Fehlerbehandlung und Validierung mit aussagekräftigen Fehlermeldungen
• Verwenden Sie Fortschrittsanzeigen, um Benutzer über langwierige Vorgänge zu informieren
• Halten Sie Tool-Operationen fokussiert und atomar, um komplexe Interaktionen zu vermeiden
• Dokumentieren Sie Ihre Tools klar mit Beschreibungen, die Benutzern helfen zu verstehen, wann sie sie verwenden sollen
• Behandeln Sie fehlende Eingabeparameter professionell, indem Sie Standardwerte oder klare Fehlermeldungen bereitstellen
• Legen Sie MIME-Typen für Ressourcen fest, um die ordnungsgemäße Handhabung verschiedener Inhaltstypen in VS Code sicherzustellen
• Verwenden Sie Ressourcenvorlagen, um Benutzern die Angabe von Eingabeparametern beim Zugriff auf Ressourcen zu ermöglichen
• Cache-Ressourceninhalte, um die Leistung zu verbessern und unnötige Netzwerkanfragen zu reduzieren
• Legen Sie angemessene Token-Limits für Sampling-Anfragen fest, um übermäßige Ressourcennutzung zu vermeiden
• Validieren Sie Sampling-Antworten, bevor Sie sie verwenden

Namenskonventionen

Die folgenden Namenskonventionen werden für MCP-Server und ihre Komponenten empfohlen

Erste Schritte zur Erstellung eines MCP-Servers

VS Code bietet alle Werkzeuge, die Sie zur Entwicklung Ihres eigenen MCP-Servers benötigen. MCP-Server können zwar in jeder Sprache geschrieben werden, die stdout verarbeiten kann, aber die offiziellen SDKs von MCP sind ein guter Ausgangspunkt.

• TypeScript SDK
• Python SDK
• Java SDK
• Kotlin SDK
• C# SDK

Das Lehrcurriculum "MCP for Beginners" könnte Ihnen ebenfalls helfen, mit dem Erstellen Ihres ersten MCP-Servers zu beginnen.

Verwandte Inhalte

• Beitragen eines Sprachmodell-Tools
• MCP-Tools im Agentenmodus verwenden
• Von VS Code kuratierte Liste von MCP-Servern
• Model Context Protocol Dokumentation