MCP Server Testing Playbook: Manuell + Automatisiert mit Apidog

Ein "Ableton Live MCP" Show HN-Beitrag erreichte Anfang dieser Woche 118 Punkte und 78 Kommentare. Das Muster ist mittlerweile vertraut: Jemand schrieb einen Model Context Protocol-Server für ein unwahrscheinliches Tool, die Claude Desktop-Community liebte es, und eine Welle von "Soll ich einen für X schreiben?"-Beiträgen folgte. MCP entwickelte sich in weniger als einem Jahr von einem Anthropic-Experiment zu einer Standard-Agentenintegrationsschicht.

Was dieses Wachstum verbirgt, ist eine Lücke in den Tools: Niemand hat eine saubere Methode zum Testen von MCP-Servern veröffentlicht. JSON-RPC manuell über Stdio mit einem Debugger auszuführen, ist für Hello-World in Ordnung; es bricht jedoch zusammen, sobald Ihr Server 12 Tools, 3 Prompts und eine unzuverlässige Upstream-API hat. Dieser Leitfaden bietet Ihnen ein praktisches Handbuch zum manuellen Testen von MCP-Servern und zur Automatisierung dieser Tests mit Apidog, damit Sie MCP-Server so ausliefern können, wie Sie jede andere API ausliefern würden: mit einem Vertrag, einem Mock und einer Regressionstest-Suite.

Wenn Sie aus einem allgemeineren Agentenkontext kommen, passt unser agents.md-Leitfaden gut dazu; die dortigen Konventionen erleichtern die Kommunikation von MCP-Server-Verträgen an Ihr Team.

button

TL;DR

MCP ist das Model Context Protocol von Anthropic; es ist JSON-RPC 2.0 über Stdio oder HTTP und stellt drei Primitive bereit: Tools, Ressourcen und Prompts.
Das Testen eines MCP-Servers bedeutet, seine initialize-, tools/list-, tools/call-, resources/read- und prompts/get-Antworten gegen einen Vertrag zu überprüfen.
Beginnen Sie manuell: Steuern Sie den Server von der Befehlszeile mit Stdio, überprüfen Sie die Antworten visuell und beheben Sie Formfehler, bevor Sie Clients hinzufügen.
Wechseln Sie zur Automatisierung: Erfassen Sie den JSON-RPC-Traffic in Apidog, wandeln Sie jeden Aufruf in eine gespeicherte Anfrage um, erstellen Sie Zusicherungen zur Antwortform und zum Inhalt und führen Sie die Suite in der CI aus.
Verwenden Sie Apidogs Mock-Server, um Upstream-APIs zu simulieren, die Ihr MCP-Server aufruft, damit Tests deterministisch bleiben.
Laden Sie Apidog herunter, um die Anfragesammlung, den Mock-Server und den CI-Runner an einem Ort zu erhalten.

Was MCP tatsächlich ist, in zwei Minuten

Die Model Context Protocol Spezifikation definiert ein JSON-RPC 2.0 Wire-Format mit einer kleinen Oberfläche. Ein Client (Claude Desktop, Cursor, Ihr eigener Agent) startet einen MCP-Server, führt einen initialize-Handshake durch und tätigt dann Aufrufe.

Die fünf Aufrufe, für die Sie 90 Prozent Ihrer Testzeit aufwenden werden:

initialize: Versionsaushandlung und Offenlegung von Fähigkeiten.
tools/list: Der Server gibt die Tools zurück, die er bereitstellt, einschließlich JSON-Schema für Argumente.
tools/call: Der Client ruft ein Tool namentlich mit Argumenten auf.
resources/list und resources/read: Der Server stellt lesbare, URI-adressierte Inhalte bereit.
prompts/list und prompts/get: Der Server stellt Prompt-Templates bereit, die der Client rendern kann.

Der Transport erfolgt entweder über Stdio (JSON-RPC-Frames Zeilenumbruch-getrennt auf Stdin/Stdout) oder streamfähiges HTTP (typischerweise POST / mit SSE für Streaming). Die meisten lokalen Server verwenden Stdio; Remote-Server verwenden HTTP.

Warum Testen wichtig ist: Jeder Claude Desktop-Nutzer, jeder Cursor-Nutzer, jede IDE, die MCP-Unterstützung hinzufügt, wird Ihren Server aufrufen. Fehler in der Form von tools/list legen sofort jeden Client lahm. Die Kosten einer Regression sind hoch.

Was Sie testen sollten

Eine solide MCP-Server-Testsuite deckt sechs Dimensionen ab.

Protokollkonformität. Gibt initialize die richtige protocolVersion zurück? Bewirbt der Server die Funktionen, die er tatsächlich unterstützt?

Schema-Korrektheit. Hat jedes Tool in tools/list ein gültiges JSON-Schema für Argumente? Sind erforderliche Felder markiert? Ist die Beschreibung länger als drei Wörter? Leere Beschreibungen verhindern die Tool-Auswahl bei Claude.

Tool-Verhalten. Gibt tools/call für jedes Tool Inhaltsblöcke des richtigen Typs (text, image, resource) zurück? Geben Fehlerfälle ein isError: true-Ergebnis zurück, anstatt JSON-RPC-Fehler auszulösen?

Ressourcenzugriff. Werden resources/list-URIs aufgelöst, wenn sie über resources/read aufgerufen werden? Funktioniert die Paginierung über die erste Seite hinaus?

Prompt-Rendering. Geben Prompts wohlgeformte messages-Arrays zurück? Landen Argument-Substitutionen an den richtigen Stellen?

Fehlermodi. Was passiert, wenn eine Upstream-API ausgefallen ist? Wenn ein Tool-Argument fehlt? Wenn der Client eine Zeitüberschreitung hat? Dies sind die Fehler, die in der Produktion auftreten, nicht bei Hello-World.

Der Rest dieses Leitfadens führt Sie durch jeden dieser Punkte, zuerst manuell, dann automatisiert.

Manuelles Testen mit Stdio

Beginnen Sie mit dem einfachsten möglichen Setup: einem Terminal, Ihrer Server-Binärdatei und dem MCP-Inspektor oder rohem JSON-RPC von Hand.

Wenn Sie noch keinen Server gebaut haben, erstellen Sie einen mit dem offiziellen MCP SDK Quickstart in Python oder TypeScript. Das Zwei-Tool-Wetterbeispiel ist ausreichend zum Testen.

Führen Sie den Server im Inspektormodus aus:

npx @modelcontextprotocol/inspector node your-server.js

Der Inspektor startet eine lokale Web-Benutzeroberfläche, die mit Ihrem Server über MCP kommuniziert und Ihnen jede Anfrage und Antwort anzeigt. Dies ist der schnellste Weg, um zu bestätigen, dass der Server startet, Fähigkeiten bewirbt und auf tools/list antwortet.

Sobald die Inspektoransicht korrekt aussieht, führen Sie den gleichen Ablauf mit rohem Stdio aus, damit Sie Frames für Apidog erfassen können:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-04-01","capabilities":{}}}' | node your-server.js

Sie erhalten eine JSON-RPC-Antwort auf Stdout. Speichern Sie die Anfrage und Antwort. Wiederholen Sie dies für tools/list, tools/call, resources/list und den Rest. Am Ende dieser Übung verfügen Sie über 6 bis 12 kanonische Anfrage-Antwort-Paare, die den Wire-Level-Vertrag Ihres Servers definieren.

Zwei Dinge, auf die Sie achten sollten.

Erstens, Inhaltsblöcke. Ein Tool-Ergebnis gibt content: [{ type: "text", text: "..." }] oder content: [{ type: "image", data: "...", mimeType: "image/png" }] zurück. Das Mischen von Typen in einer Antwort ist erlaubt; Clients unterscheiden sich in der Art, wie sie rendern.

Zweitens, Fehler. Die MCP-Spezifikation ist eindeutig: Tool-Ausführungsfehler geben ein normales Ergebnis mit isError: true und einem Inhaltsblock zurück, der den Fehler beschreibt. Werfen Sie keine JSON-RPC-Fehlerantworten innerhalb eines Tools; das signalisiert einen Protokollfehler, keinen Tool-Fehler. Viele Clients trennen die Verbindung bei Protokollfehlern.

Von manuell zu automatisiert: Erstellen der Testsuite in Apidog

Manuelles Testen deckt offensichtliche Fehler auf. Zur Automatisierung wechseln Sie, wenn Sie sich fragen: „Hat meine letzte Änderung das Argumentschema von Tool 7 beschädigt?“ und nicht 12 Curl-Befehle eingeben möchten, um das herauszufinden.

Das Muster: Nehmen Sie jedes Anfrage-Antwort-Paar, das Sie während des manuellen Testens gespeichert haben, fügen Sie es als gespeicherte Anfrage in Apidog ein, fügen Sie Zusicherungen hinzu und führen Sie die Suite bei jedem Push aus.

1. Erstellen Sie ein Apidog-Projekt für den MCP-Server

Öffnen Sie Apidog, erstellen Sie ein neues Projekt, setzen Sie die Basis-URL auf den HTTP-Endpunkt Ihres MCP-Servers (oder die Stdio-Bridge-URL; siehe unten). Apidog-Projekte unterstützen sowohl REST als auch JSON-RPC; erstellen Sie eine JSON-RPC-Umgebung.

Für Stdio-Server, die keine HTTP-Schnittstelle haben, führen Sie sie hinter einem dünnen HTTP-Wrapper zum Testen aus. Der offizielle Inspektor liefert einen mit; alternativ funktioniert ein 30-zeiliges Node-Skript, das JSON-RPC über HTTP liest und an Stdio weiterleitet, einwandfrei. Wir verwenden dasselbe Muster im Beitrag API-Tests ohne Postman im Jahr 2026 für Nicht-HTTP-Backends.

2. Speichern Sie die kanonischen Anfragen

Speichern Sie für jeden der Aufrufe initialize, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get den JSON-RPC-Body als Anfrage. Apidog speichert sie mit Body, Headern und erwartetem Status.

Eine tools/call-Anfrage sieht in Apidogs Anfrage-Body-Ansicht so aus:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "Tokyo"
    }
  }
}

3. Zusicherungen hinzufügen

Der Sinn der Automatisierung ist, auf die Antwort zu prüfen, nicht die Anfrage zu senden. Apidog unterstützt JSONPath-Zusicherungen nativ. Für tools/list sollten Sie mindestens folgendes prüfen:

$.result.tools existiert
$.result.tools.length ist größer als null
Jedes Tool hat name, description und inputSchema
Jedes inputSchema ist ein gültiges JSON-Schema

Für tools/call bei einer bekanntermaßen guten Eingabe möchten Sie:

$.result.isError ist false (oder fehlt)
$.result.content ist ein Array
Der erste Inhaltsblock hat den erwarteten type und Inhalt

Für tools/call bei einer bekanntermaßen schlechten Eingabe (fehlendes erforderliches Argument) möchten Sie:

$.result.isError ist true
$.result.content[0].text stimmt mit Ihrer erwarteten Fehlermeldung überein

Apidog speichert diese Zusicherungen pro Anfrage. Fehler werden im Ausführungsbericht angezeigt.

4. Mocken Sie die Upstream-APIs

Die meisten MCP-Server wrappen eine externe API: Wetterdaten, GitHub, Linear, eine interne Datenbank. Sie möchten nicht, dass CI-Läufe bei jedem Commit Live-APIs treffen. Zwei Gründe: Kosten und Unzuverlässigkeit.

Apidogs eingebauter Mock-Server behebt dies. Definieren Sie jeden Upstream-Endpunkt als gemockte Route, die einen realistischen JSON-Body zurückgibt. Richten Sie die Konfiguration Ihres MCP-Servers während der Tests auf die Mock-URL und während der echten Läufe auf die Produktion. Wir behandeln den Mock-Workflow detailliert in der Vertrags-First-API-Entwicklung.

Das Ergebnis: eine Testsuite, die in Sekunden läuft, kein externes Netzwerk benötigt und Schema-Regressionen lange vor der Auslieferung abfängt.

5. Führen Sie die Suite in der CI aus

Apidog-Projekte exportieren in CLI-Runner. Der Befehl apidog run nimmt eine Projekt-ID entgegen, führt jede gespeicherte Anfrage aus, evaluiert Zusicherungen und beendet sich bei einem Fehler mit einem Wert ungleich Null. Binden Sie ihn in Ihre GitHub Actions oder einen anderen CI-Anbieter ein, den Sie bereits verwenden.

Ein minimaler Workflow:

name: MCP server tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - name: Start MCP HTTP wrapper
        run: node test/wrapper.js &
      - name: Run Apidog suite
        run: npx apidog run --project-id $APIDOG_PROJECT --env ci
        env:
          APIDOG_PROJECT: ${{ secrets.APIDOG_PROJECT }}
          APIDOG_TOKEN:   ${{ secrets.APIDOG_TOKEN }}

Jeder Push führt den gesamten MCP-Vertrag aus. Eine Schema-Regression von Tool 7 kann nicht ohne Aufdeckung veröffentlicht werden.

Wie eine gute Testabdeckung aussieht

Ein vollständiger MCP-Server-Testplan in Apidog umfasst typischerweise:

1 initialize-Anfrage mit Fähigkeitszusicherungen
1 tools/list-Anfrage mit Form- und JSON-Schema-Zusicherungen
2 bis 4 tools/call-Anfragen pro Tool: Happy Path, fehlendes Argument, ungültiger Typ, Upstream-Fehler
1 resources/list plus 1 resources/read pro Ressourcenfamilie
1 prompts/list plus 1 prompts/get pro Prompt-Template

Für einen Server mit 10 Tools, 3 Ressourcen und 4 Prompts umfasst die Suite 50 bis 70 Anfragen. Apidog führt dies lokal in weniger als 10 Sekunden aus, wenn der Mock-Server warm ist.

Häufige Fehler beim Testen von MCP-Servern

Dies sind die Muster, die wir am häufigsten sehen.

Überspringen des initialize-Roundtrips. Mehrere Server stürzen bei tools/list ab, wenn initialize nie aufgerufen wurde, da sie ihr Tool-Register lazy während des Handshakes aufbauen. Führen Sie initialize immer zuerst aus.

Prüfen auf rohe Fehlerzeichenketten. Tool-Fehlermeldungen werden sich ändern. Prüfen Sie auf isError: true und auf einen stabilen Fehlercode oder einen Regex, nicht auf exakte Zeichenkettenübereinstimmungen.

Zulassen, dass der Mock von der Produktion abweicht. Ein Mock, der Formen zurückgibt, die die reale API nie zurückgibt, führt zu grünen Tests bei einer fehlerhaften Integration. Nehmen Sie Mock-Fixtures bei jeder Veröffentlichung von echten Antworten neu auf.

Streaming vergessen. HTTP-MCP-Server streamen Tool-Ergebnisse über SSE. Ihr Test-Runner muss SSE handhaben; Apidog tut dies, aber Sie müssen Streaming bei der Anfrage aktivieren.

Nebenläufigkeit nicht testen. MCP-Clients senden nebenläufige tools/call-Anfragen in Agenten-Loops. Wenn Ihr Server einen gemeinsam genutzten Zustand ohne Sperren hält, bestehen Einzelanfragen-Tests, und die Produktion bricht zusammen. Fügen Sie der Suite einen Parallel-Test hinzu.

Verwechslung von Protokollfehlern mit Tool-Fehlern. Die MCP-Spezifikation trennt diese absichtlich; das Vermischen führt dazu, dass Claude Desktop die Verbindung schließt. Wir haben dieselbe Art von Vertragsfehler in der API-Plattform Contract-First-Entwicklung behandelt.

Praktische Anwendungsfälle

Ein Team, das einen internen MCP-Server für die Incident-Management-API ihres Unternehmens baute, entdeckte in einer Woche drei Regressionen mithilfe von Apidog-Zusicherungen auf die Form von tools/list. Ohne den Test wären die Fehler gleichzeitig an alle Ingenieure ausgeliefert worden, die Claude Desktop verwenden.

Ein Solo-Entwickler, der einen Open-Source-MCP-Server für Notion veröffentlicht, verwendet Apidog-Mocks, um die Testsuite auszuführen, ohne Notions Ratenbegrenzungen während der CI zu überschreiten. Seine Suite läuft bei jedem PR, dauert 8 Sekunden und speichert Apidogs Mock-Fixtures im Repository zwischen, sodass Mitwirkende keinen API-Zugriff zum Entwickeln benötigen.

Ein Plattformteam, das 14 interne MCP-Server betreibt, baute einen gemeinsamen Apidog-Workspace, in dem der Vertrag jedes Servers liegt. Neue Server erben eine Basis-Testsuite; Prüfer können Schema-Differenzen nebeneinander vergleichen, bevor sie mergen. Das Team meldet zwei im ersten Quartal verhinderte Ausfälle, beide wurden durch tools/list-Form-Zusicherungen bei einem PR entdeckt, der ein umbenanntes Argument an jeden Claude Desktop-Nutzer innerhalb des Unternehmens ausgeliefert hätte.

Ein zweites Team, das einen MCP-Server für eine interne Observability-Plattform erstellt, verwendet Apidogs Umgebungswechsler, um dieselbe Suite gegen Staging und Produktion auszuführen. Jede Umgebung verweist auf eine andere Mock-Fixture-Datei, sodass dieselben 60 Zusicherungen beide Bereitstellungen bestätigen, ohne eine einzige Anfrage neu schreiben zu müssen.

Fazit

MCP ist dieses Jahr Mainstream geworden, aber die Testgeschichte ist immer noch dort, wo REST-API-Tests vor einem Jahrzehnt waren: ad hoc, manuell, fragil. Sie müssen nicht darauf warten, dass das Ökosystem aufholt. Behandeln Sie Ihren MCP-Server als die API, die er ist, entwerfen Sie einen Vertrag, mocken Sie die Upstreams und führen Sie Zusicherungen in der CI aus.

Fünf Erkenntnisse:

Ein MCP-Server ist eine JSON-RPC-API; testen Sie ihn mit der gleichen Sorgfalt wie eine REST-API.
Beginnen Sie manuell mit dem offiziellen Inspektor, erfassen Sie dann kanonische Anfragen und gehen Sie zur Automatisierung über.
Apidog verwaltet JSON-RPC, Zusicherungen, Mocks und CI in einem Projekt.
Decken Sie die sechs Dimensionen ab: Protokollkonformität, Schemakorrektheit, Tool-Verhalten, Ressourcenzugriff, Prompt-Rendering und Fehlermodi.
Mocken Sie Upstream-APIs in Apidog, damit die Testsuite schnell und deterministisch bleibt.

Nächster Schritt: Öffnen Sie Apidog, erstellen Sie ein Projekt, fügen Sie die manuell erfassten Anfrage-Bodies ein, fügen Sie JSONPath-Zusicherungen für tools/list hinzu und führen Sie die Suite aus. Sie werden innerhalb einer Stunde wissen, ob der Vertrag Ihres Servers solide genug ist, um ausgeliefert zu werden.

FAQ

Was ist MCP?

MCP, das Model Context Protocol, ist Anthropic's offene Spezifikation dafür, wie AI-Clients (wie Claude Desktop) externe Tools, Ressourcen und Prompts aufrufen. Es ist JSON-RPC 2.0 über Stdio oder streamfähiges HTTP. Die vollständige MCP-Spezifikation ist auf modelcontextprotocol.io veröffentlicht.

Kann ich einen MCP-Server ohne HTTP-Wrapper testen?

Ja. Der offizielle MCP-Inspektor spricht direkt Stdio und bietet Ihnen eine Benutzeroberfläche für manuelles Testen. Für automatisierte Tests in Apidog umhüllen Sie Stdio während der CI mit einem dünnen HTTP-Server; der Produktionsverkehr läuft weiterhin über Stdio.

Wie mocke ich Upstream-APIs, die mein MCP-Server aufruft?

Definieren Sie jeden Upstream-Endpunkt als Mock in Ihrem Apidog-Projekt, richten Sie die Konfiguration des MCP-Servers während der Tests auf die Mock-URL und wechseln Sie zur Laufzeit zu Produktions-URLs. Wir gehen dasselbe Muster in API-Testtools für QA-Ingenieure durch.

Was ist mit dem Streaming von Tool-Ergebnissen?

HTTP-MCP-Server streamen Tool-Ergebnisse über Server-Sent Events. Apidog unterstützt SSE in gespeicherten Anfragen; aktivieren Sie es in den Anfrageeinstellungen und prüfen Sie den zusammengestellten Stream.

Sollte ich die Protokollversion testen?

Ja. Legen Sie die protocolVersion fest, die Sie in initialize unterstützen, und prüfen Sie diese. Nichtübereinstimmungen führen zu stillschweigender Client-Inkompatibilität.

Kann ich meinen MCP-Server gegen das echte Claude Desktop testen?

Sie können, und Sie sollten dies mindestens einmal vor jeder Veröffentlichung tun. Verlassen Sie sich jedoch nicht auf Claude Desktop als Ihre Testschleife; es ist langsam, manuell und nicht deterministisch. Verwenden Sie Apidog für die Regressionstest-Suite und Claude Desktop für den Rauchtest.

Wo kann ich reale MCP-Server-Beispiele sehen?

Das offizielle MCP-Server-Repository enthält Referenzimplementierungen für Dateisystem, GitHub, Slack, Postgres und Dutzende weitere. Lesen Sie die Tool-Definitionen; sie sind der einfachste Weg zu verstehen, wie eine gute MCP-Form aussieht.