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 inzwischen bekannt: Jemand baut einen Model-Context-Protocol-Server für ein unerwartetes Tool, die Claude-Desktop-Community nutzt ihn, und kurz darauf folgen viele „Soll ich einen für X bauen?“-Beiträge. MCP hat sich in weniger als einem Jahr von einem Anthropic-Experiment zu einer gängigen Integrationsschicht für Agenten entwickelt.

Teste Apidog noch heute

Was dabei oft fehlt: ein sauberer Testprozess für MCP-Server. JSON-RPC manuell über Stdio mit einem Debugger zu senden, reicht für Hello World. Sobald Ihr Server aber 12 Tools, 3 Prompts und eine unzuverlässige Upstream-API hat, wird das fragil. Dieser Leitfaden zeigt, wie Sie MCP-Server manuell testen und diese Tests anschließend mit Apidog automatisieren: mit Vertrag, Mock und Regressionstest-Suite.

Wenn Sie aus einem allgemeineren Agenten-Kontext kommen, passt unser agents.md-Leitfaden gut dazu. Die dortigen Konventionen helfen, MCP-Server-Verträge im Team klar zu dokumentieren.

TL;DR

• MCP ist Anthropic’s Model Context Protocol: JSON-RPC 2.0 über Stdio oder HTTP.
• MCP stellt drei zentrale Primitive bereit: Tools, Ressourcen und Prompts.
• Testen Sie mindestens initialize, tools/list, tools/call, resources/read und prompts/get.
• Starten Sie manuell mit Stdio oder dem MCP-Inspector.
• Erfassen Sie danach kanonische JSON-RPC-Requests und automatisieren Sie sie in Apidog.
• Verwenden Sie Mock-Server für externe APIs, damit CI-Tests deterministisch bleiben.
• Laden Sie Apidog herunter, wenn Sie Request-Sammlung, Mock-Server und CI-Runner in einem Workflow bündeln möchten.

Was MCP tatsächlich ist

Die Model Context Protocol Spezifikation definiert ein JSON-RPC-2.0-Wire-Format mit kleiner Oberfläche.

Ein Client, zum Beispiel Claude Desktop, Cursor oder ein eigener Agent:

1. startet einen MCP-Server,
2. führt einen initialize-Handshake aus,
3. ruft anschließend Tools, Ressourcen oder Prompts ab.

Die wichtigsten Calls für Tests sind:

• initialize: Versionsaushandlung und Capabilities.
• tools/list: listet verfügbare Tools inklusive JSON-Schema für Argumente.
• tools/call: ruft ein Tool mit Argumenten auf.
• resources/list und resources/read: stellen URI-adressierte Inhalte bereit.
• prompts/list und prompts/get: liefern Prompt-Templates für Clients.

Der Transport läuft typischerweise über:

• Stdio: JSON-RPC-Frames über stdin/stdout, meist bei lokalen Servern.
• Streamfähiges HTTP: häufig POST / plus SSE für Streaming, meist bei Remote-Servern.

Warum Tests wichtig sind: Wenn tools/list eine falsche Form zurückgibt, kann ein Client Ihren Server nicht zuverlässig verwenden. Eine kleine Schema-Regression kann damit alle Nutzer treffen.

Was Sie testen sollten

Eine robuste MCP-Test-Suite deckt sechs Bereiche ab.

1. Protokollkonformität

Prüfen Sie den initialize-Handshake:

• Gibt der Server die erwartete protocolVersion zurück?
• Bewirbt er nur Capabilities, die er tatsächlich unterstützt?
• Funktionieren nach initialize die weiteren Calls?

Beispiel-Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2026-04-01",
    "capabilities": {}
  }
}

2. Schema-Korrektheit

Für jedes Tool aus tools/list sollten Sie prüfen:

• name existiert.
• description ist aussagekräftig.
• inputSchema ist gültiges JSON Schema.
• Pflichtfelder sind korrekt als required markiert.
• Datentypen stimmen mit der Implementierung überein.

Leere oder generische Beschreibungen erschweren die Tool-Auswahl durch Clients.

3. Tool-Verhalten

Für jedes Tool sollten Sie mindestens testen:

• Happy Path mit gültigen Argumenten.
• fehlendes Pflichtargument.
• falscher Datentyp.
• Upstream-API-Fehler.
• Timeout oder leere Antwort.

Ein erfolgreiches Tool-Ergebnis sollte Content-Blöcke zurückgeben, zum Beispiel:

{
  "content": [
    {
      "type": "text",
      "text": "Weather in Tokyo: 21°C"
    }
  ]
}

4. Ressourcenzugriff

Prüfen Sie:

• Gibt resources/list gültige URIs zurück?
• Lassen sich diese URIs mit resources/read abrufen?
• Funktioniert Paginierung über die erste Seite hinaus?
• Sind Fehlerfälle stabil definiert?

5. Prompt-Rendering

Für Prompts sollten Sie testen:

• Gibt prompts/list alle erwarteten Templates zurück?
• Liefert prompts/get ein wohlgeformtes messages-Array?
• Werden Argumente an den richtigen Stellen ersetzt?
• Verhalten sich fehlende Argumente erwartbar?

6. Fehlermodi

Produktionsfehler entstehen meistens nicht im Happy Path.

Testen Sie deshalb:

• Upstream-API nicht erreichbar.
• ungültige Authentifizierung.
• fehlendes Tool-Argument.
• Client-Timeout.
• parallele tools/call-Anfragen.
• unerwartete Upstream-Antwortform.

Manuelles Testen mit Stdio

Starten Sie mit dem einfachsten Setup:

• Terminal
• Server-Binary oder Node/Python-Entry-Point
• MCP Inspector oder rohe JSON-RPC-Requests

Wenn Sie noch keinen Server haben, verwenden Sie den offiziellen MCP SDK Quickstart in Python oder TypeScript. Das Wetterbeispiel mit zwei Tools reicht für erste Tests.

Starten Sie den Inspector:

npx @modelcontextprotocol/inspector node your-server.js

Der Inspector öffnet eine lokale Web-UI, kommuniziert über MCP mit Ihrem Server und zeigt Requests und Responses an.

Prüfen Sie dort zuerst:

1. Startet der Server?
2. Funktioniert initialize?
3. Werden Capabilities korrekt beworben?
4. Gibt tools/list die erwarteten Tools zurück?
5. Funktionieren einzelne tools/call-Aufrufe?

Danach führen Sie denselben Ablauf roh über Stdio aus, damit Sie Requests für Apidog erfassen können:

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

Speichern Sie Request und Response.

Wiederholen Sie das für:

• initialize
• tools/list
• tools/call
• resources/list
• resources/read
• prompts/list
• prompts/get

Am Ende haben Sie 6 bis 12 kanonische Request-Response-Paare. Diese bilden den Wire-Level-Vertrag Ihres Servers.

Worauf Sie bei manuellen Tests achten sollten

Content-Blöcke

Ein Tool-Ergebnis enthält Content-Blöcke wie:

{
  "content": [
    {
      "type": "text",
      "text": "Result text"
    }
  ]
}

Oder bei Bildern:

{
  "content": [
    {
      "type": "image",
      "data": "base64-data",
      "mimeType": "image/png"
    }
  ]
}

Gemischte Content-Typen sind erlaubt. Clients rendern sie jedoch unterschiedlich. Testen Sie deshalb die konkrete Form.

Tool-Fehler vs. Protokollfehler

Die MCP-Spezifikation trennt Tool-Fehler und JSON-RPC-Protokollfehler.

Ein Tool-Ausführungsfehler sollte als normales Ergebnis mit isError: true zurückkommen:

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Missing required argument: city"
      }
    ]
  }
}

Werfen Sie für Tool-Fehler keine JSON-RPC-Error-Response. Viele Clients interpretieren das als Protokollfehler und trennen die Verbindung.

Von manuell zu automatisiert: Testsuite in Apidog erstellen

Manuelle Tests finden offensichtliche Fehler. Automatisierung beantwortet die wichtigere Frage:

Hat meine letzte Änderung den Vertrag beschädigt?

Das Vorgehen:

1. Manuell geprüfte JSON-RPC-Requests sammeln.
2. Jeden Request in Apidog speichern.
3. Assertions für Response-Form und Inhalt definieren.
4. Upstream-APIs mocken.
5. Suite in CI ausführen.

1. Apidog-Projekt für den MCP-Server anlegen

Erstellen Sie in Apidog ein neues Projekt.

Für HTTP-basierte MCP-Server:

• Base URL auf den MCP-Endpunkt setzen.
• JSON-RPC-Requests als gespeicherte Requests anlegen.
• Umgebung für lokal, CI, Staging und Produktion definieren.

Für Stdio-Server ohne HTTP-Schnittstelle brauchen Sie für automatisierte Tests einen dünnen HTTP-Wrapper.

Optionen:

• MCP Inspector als Bridge verwenden.
• eigenes Node-Skript schreiben, das HTTP-Requests annimmt und an Stdio weiterleitet.
• denselben Wrapper nur in Tests/CI starten.

Ein minimales Muster:

import express from "express";
import { spawn } from "node:child_process";

const app = express();
app.use(express.json());

app.post("/", (req, res) => {
  const child = spawn("node", ["your-server.js"]);

  let output = "";

  child.stdout.on("data", chunk => {
    output += chunk.toString();
  });

  child.stderr.on("data", chunk => {
    console.error(chunk.toString());
  });

  child.on("close", () => {
    try {
      res.json(JSON.parse(output));
    } catch {
      res.status(500).json({ error: "Invalid JSON-RPC response", raw: output });
    }
  });

  child.stdin.write(JSON.stringify(req.body) + "\n");
  child.stdin.end();
});

app.listen(3000, () => {
  console.log("MCP HTTP test wrapper listening on http://localhost:3000");
});

Für komplexere Server sollten Sie den Prozess wiederverwenden, statt ihn pro Request neu zu starten. Für erste Vertragstests reicht das Muster aber aus.

Mehr zum Testen von Nicht-HTTP-Backends finden Sie im Beitrag API-Tests ohne Postman im Jahr 2026.

2. Kanonische Requests speichern

Speichern Sie für jeden relevanten MCP-Call einen Request:

• initialize
• tools/list
• tools/call
• resources/list
• resources/read
• prompts/list
• prompts/get

Beispiel für tools/call:

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

Legen Sie Varianten pro Tool an:

• gültige Eingabe
• fehlendes Pflichtfeld
• ungültiger Typ
• bekannter Upstream-Fehler
• leerer oder partieller Upstream-Response

3. Assertions hinzufügen

Automatisierte Tests sind nur wertvoll, wenn sie die Antwort validieren.

Für tools/list sollten Sie mindestens prüfen:

• $.result.tools existiert.
• $.result.tools.length ist größer als 0.
• jedes Tool hat name.
• jedes Tool hat description.
• jedes Tool hat inputSchema.
• jedes inputSchema ist gültig.
• erwartete Tool-Namen sind vorhanden.

Beispielhafte JSONPath-Checks:

$.result.tools
$.result.tools[0].name
$.result.tools[0].description
$.result.tools[0].inputSchema

Für einen erfolgreichen tools/call:

• $.result.isError ist false oder fehlt.
• $.result.content ist ein Array.
• $.result.content[0].type hat den erwarteten Wert.
• Text oder strukturierte Ausgabe enthält erwartbare Daten.

Für einen fehlerhaften tools/call:

• $.result.isError ist true.
• $.result.content[0].type ist text.
• Fehlermeldung oder Fehlercode ist stabil prüfbar.

Vermeiden Sie zu fragile String-Vergleiche. Prüfen Sie lieber auf stabile Fehlercodes, JSON-Felder oder Regex-Muster.

4. Upstream-APIs mocken

Die meisten MCP-Server wrappen externe Systeme:

• Wetter-APIs
• GitHub
• Linear
• Notion
• interne Datenbanken
• Observability-Plattformen
• Incident-Management-Systeme

CI sollte diese Systeme nicht bei jedem Commit live aufrufen.

Gründe:

• Rate Limits
• Kosten
• instabile Netzwerke
• nichtdeterministische Daten
• langsame Tests

Nutzen Sie dafür den Mock-Server in Apidog:

1. Definieren Sie jeden Upstream-Endpunkt als Mock-Route.
2. Hinterlegen Sie realistische Response-Bodies.
3. Konfigurieren Sie Ihren MCP-Server in Tests auf die Mock-URL.
4. Verwenden Sie in Produktion die echte URL.
5. Aktualisieren Sie Mock-Fixtures regelmäßig anhand realer Responses.

Beispiel-Konfiguration:

# CI
WEATHER_API_BASE_URL=https://mock.example.apidog.io

# Produktion
WEATHER_API_BASE_URL=https://api.weather.example.com

Der Workflow entspricht Contract-First-API-Entwicklung. Details dazu finden Sie in Vertrags-First-API-Entwicklung.

5. Testsuite in CI ausführen

Apidog-Projekte lassen sich über einen CLI-Runner ausführen. Der Runner führt gespeicherte Requests aus, evaluiert Assertions und beendet den Prozess bei Fehlern mit einem Nicht-Null-Exit-Code.

Ein minimaler GitHub-Actions-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 }}

Damit läuft der MCP-Vertrag bei jedem Push und Pull Request. Eine Änderung am Argumentschema eines Tools wird sichtbar, bevor sie Nutzer erreicht.

Wie gute Testabdeckung aussieht

Für einen vollständigen MCP-Server-Testplan in Apidog sollten Sie typischerweise erfassen:

• 1 initialize-Request mit Capability-Assertions
• 1 tools/list-Request mit Form- und Schema-Assertions
• 2 bis 4 tools/call-Requests pro Tool:
  • Happy Path
  • fehlendes Argument
  • ungültiger Typ
  • Upstream-Fehler
• 1 resources/list
• 1 resources/read pro Ressourcenfamilie
• 1 prompts/list
• 1 prompts/get pro Prompt-Template
• optional Parallel-Tests für konkurrierende tools/call-Requests

Für einen Server mit 10 Tools, 3 Ressourcen und 4 Prompts ergibt das schnell 50 bis 70 Requests.

Häufige Fehler beim Testen von MCP-Servern

initialize überspringen

Einige Server bauen ihr Tool-Register erst während des Handshakes auf. Wenn Sie direkt tools/list aufrufen, testen Sie nicht den realen Client-Ablauf.

Führen Sie immer zuerst initialize aus.

Auf exakte Fehlermeldungen prüfen

Fehlertexte ändern sich. Stabiler sind:

• isError: true
• Fehlercodes
• strukturierte Felder
• Regex statt exakter String

Mock und Produktion auseinanderlaufen lassen

Ein Mock, der andere Formen zurückgibt als die echte API, erzeugt falsche Sicherheit.

Aktualisieren Sie Mock-Fixtures regelmäßig mit echten Responses.

Streaming vergessen

HTTP-MCP-Server können Tool-Ergebnisse über Server-Sent Events streamen.

Aktivieren Sie SSE in den Request-Einstellungen und testen Sie den zusammengesetzten Stream.

Nebenläufigkeit ignorieren

Agenten-Loops können parallele tools/call-Requests auslösen. Wenn Ihr Server gemeinsamen Zustand ohne Schutz verwendet, bestehen Einzeltests, aber Produktion bricht.

Fügen Sie mindestens einen Parallel-Test hinzu.

Tool-Fehler als Protokollfehler zurückgeben

Tool-Fehler gehören in ein normales MCP-Ergebnis mit isError: true.

JSON-RPC-Errors sollten Protokoll- oder Transportprobleme signalisieren. Diese Trennung ist wichtig, weil Clients sonst die Verbindung schließen können.

Ähnliche Vertragsprobleme werden auch in 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, fand innerhalb einer Woche mehrere Regressionen über Assertions auf die Form von tools/list. Ohne Vertragstest wären diese Änderungen direkt bei allen Claude-Desktop-Nutzern im Unternehmen gelandet.

Ein Solo-Entwickler mit einem Open-Source-MCP-Server für Notion nutzt Apidog-Mocks, um die Testsuite in CI auszuführen, ohne Notions Rate Limits zu treffen. Die Mock-Fixtures liegen im Repository, sodass Contributors ohne API-Zugang entwickeln können.

Ein Plattformteam mit mehreren internen MCP-Servern nutzt einen gemeinsamen Apidog-Workspace für Server-Verträge. Neue Server starten mit einer Basis-Testsuite, und Reviewer vergleichen Schema-Unterschiede vor dem Merge.

Ein weiteres Team mit einem MCP-Server für eine interne Observability-Plattform führt dieselbe Suite gegen Staging und Produktion aus. Umgebungen unterscheiden nur URLs und Fixtures, nicht die Tests selbst.

Fazit

MCP ist Mainstream geworden, aber viele Testprozesse sind noch ad hoc. Behandeln Sie Ihren MCP-Server wie eine API:

1. Vertrag definieren.
2. Manuell mit Inspector und Stdio prüfen.
3. Kanonische Requests erfassen.
4. Assertions in Apidog anlegen.
5. Upstreams mocken.
6. Suite in CI ausführen.

Die wichtigsten Punkte:

• Ein MCP-Server ist eine JSON-RPC-API.
• initialize, tools/list und tools/call sind Pflichttests.
• Tool-Fehler sollten isError: true liefern, keine JSON-RPC-Protokollfehler.
• Mocken Sie externe APIs, damit Tests schnell und deterministisch bleiben.
• Führen Sie Vertragstests bei jedem Push aus.

Nächster Schritt: Öffnen Sie Apidog, erstellen Sie ein Projekt, fügen Sie Ihre manuell erfassten JSON-RPC-Bodies ein und starten Sie mit Assertions für tools/list.

FAQ

Was ist MCP?

MCP, das Model Context Protocol, ist Anthropic’s offene Spezifikation dafür, wie AI-Clients externe Tools, Ressourcen und Prompts aufrufen. Es verwendet 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-Inspector spricht direkt Stdio und eignet sich für manuelle Tests.

Für automatisierte Tests in Apidog ist ein dünner HTTP-Wrapper während CI praktisch. Der Produktionsverkehr kann weiterhin über Stdio laufen.

Wie mocke ich Upstream-APIs?

Definieren Sie jeden Upstream-Endpunkt als Mock in Apidog, richten Sie Ihren MCP-Server während Tests auf die Mock-URL und verwenden Sie zur Laufzeit Produktions-URLs.

Ein ähnliches Muster wird in API-Testtools für QA-Ingenieure beschrieben.

Was ist mit Streaming von Tool-Ergebnissen?

HTTP-MCP-Server können Tool-Ergebnisse über Server-Sent Events streamen. Aktivieren Sie SSE in den gespeicherten Requests und prüfen Sie den zusammengesetzten Stream.

Sollte ich die Protokollversion testen?

Ja. Setzen und prüfen Sie die protocolVersion im initialize-Flow. Versionsabweichungen können zu stiller Client-Inkompatibilität führen.

Kann ich gegen Claude Desktop testen?

Ja, als Smoke Test vor Releases. Verwenden Sie Claude Desktop aber nicht als primäre Regressionstest-Schleife. Es ist manuell, langsamer und weniger deterministisch als eine automatisierte Suite.

Nutzen Sie Apidog für Regressionstests und Claude Desktop für abschließende manuelle Prüfung.

Wo finde ich reale MCP-Server-Beispiele?

Das offizielle MCP-Server-Repository enthält Referenzimplementierungen für Dateisystem, GitHub, Slack, Postgres und viele weitere Integrationen. Die Tool-Definitionen dort sind gute Beispiele für saubere MCP-Formen.