MCP-Server in CI prüfen: Warum tools/list allein nicht ausreicht

Die Integration von Model Context Protocol (MCP)-Servern in bestehende IT-Infrastrukturen schreitet rasant voran. Doch während viele Entwicklerteams darauf vertrauen, dass ein Server startet und die verfügbaren Tools über die tools/list-Route meldet, reicht das längst nicht mehr aus. Ein MCP-Server kann technisch korrekt initialisieren, alle erwarteten Funktionen auflisten – und dennoch in der Praxis scheitern, weil Berechtigungen, Authentifizierung, Umgebungsvariablen oder nachgelagerte Systeme nicht wie konfiguriert funktionieren.

Um diese Lücke zu schließen, hat das Tool `mcp-probe` mit der Version 1.8.0 entscheidende Verbesserungen erhalten. Es geht nicht mehr nur um oberflächliche Checks, sondern um echte CI-Gates, die sicherstellen, dass ein MCP-Server die Anforderungen erfüllt, die später auch ein KI-Agent stellen wird. Der Fokus liegt auf Warnungen, die nun CI-Pipelines blockieren können, echten Tool-Aufrufen mit realen Eingaben und der Überprüfung von Authentifizierungsflüssen.

Warum einfache Schema-Checks gefährlich sind

Ein verbreitetes Missverständnis lautet: Wenn ein MCP-Server startet und die tools/list-Route ein sauberes Schema zurückgibt, funktioniert er einwandfrei. Doch diese Annahme ignoriert kritische Fehlerquellen:

• Authentifizierungsprobleme, die zu 401-Fehlern bei Tool-Aufrufen führen.
• Falsche Rollen oder Berechtigungen, die zwar den Server starten lassen, aber echte Abfragen blockieren.
• Fehlende CI-Integration, bei der Werkzeuge zwar deklariert sind, aber nie mit den tatsächlichen Produktionsparametern getestet werden.
• Degradierte Zustände, die kein hartes Failure auslösen, aber die Funktionalität stark einschränken.

Ein klassisches Beispiel: Ein Datenbank-Tool arbeitet mit Admin-Berechtigungen, scheitert aber mit Read-Only-Rollen – obwohl der Server selbst keine Fehler meldet. Solche Szenarien werden erst sichtbar, wenn echte Eingaben verarbeitet und die Antworten auf Plausibilität geprüft werden.

Was sich in mcp-probe 1.8.0 geändert hat

Die neue Version setzt auf drei zentrale Verbesserungen, die MCP-Server in CI-Pipelines zuverlässiger machen:

1. Warnungen können CI-Pipelines blockieren

Bisher beendete mcp-probe die Ausführung mit einem Exit-Code 0, selbst wenn Warnungen auftraten. Das verhinderte unerwartete Pipeline-Fehlschläge in bestehenden Projekten. Mit der neuen Option --fail-on-warn ändert sich das Verhalten:

npx @k08200/mcp-probe@latest --config mcp-probe.config.json --github-summary --fail-on-warn

Jetzt können folgende Szenarien CI-Pipelines unterbrechen:

• Probleme bei der OAuth-Weiterleitung, die ein Browserfenster erfordern.
• 401- oder 403-Fehler bei Tool-Aufrufen mit eingeschränkten Berechtigungen.
• Unvollständige Readiness-Checks, die zwar die Existenz eines Tools bestätigen, aber keine sinnvollen Testdaten verarbeiten.

Diese strenge Prüfung ist besonders wichtig, weil viele MCP-Fehler nicht als Crashs sichtbar werden, sondern als stille Einschränkungen, die erst im Betrieb auffallen.

2. Der doctor-Modus prüft echte Workflow-Ausführungen

Der doctor-Befehl überprüfte bisher nur, ob in einer GitHub-Actions-Workflow-Datei ein mcp-probe-Schritt existiert. Doch das reicht nicht aus. Die neue Version verlangt, dass alle relevanten Flags in einem einzigen Ausführungsschritt kombiniert werden:

✅ Korrekt:

- run: npx @k08200/mcp-probe@latest --config mcp-probe.config.json --github-summary --fail-on-warn

❌ Unzureichend:

- run: npx @k08200/mcp-probe@latest --config mcp-probe.config.json
- run: npx @k08200/mcp-probe ./server.js --github-summary --fail-on-warn

Im zweiten Beispiel werden zwar die benötigten Flags verwendet, aber nicht in einer einzigen, durchgehenden Prüfung. Das neue Verhalten stellt sicher, dass der gesamte Konfigurationssatz – inklusive GitHub-Summaries und Warnbehandlung – tatsächlich getestet wird.

3. Tool-Aufrufe werden mit echten Eingaben validiert

Für konfigurationsbasierte Checks können Entwickler nun explizit festlegen, welche Tools erwartet werden und welche Eingaben für einen sinnvollen Test verwendet werden sollen. Ein Beispiel für die Konfiguration:

{
  "servers": [
    {
      "name": "datadog",
      "target": "
      "transport": "http",
      "headers": {
        "Authorization": "Bearer ${DATADOG_MCP_TOKEN}"
      },
      "expectedTools": ["logs_query"],
      "forbiddenTools": ["delete_dashboard", "rotate_api_key"],
      "toolsFile": "./datadog.tools.json"
    }
  ]
}

Wird sowohl expectedTools als auch toolsFile angegeben, muss für jedes erwartete Tool eine sidecar-Eingabe bereitgestellt werden. Das bedeutet:

• Es wird nicht nur geprüft, ob das Tool existiert.
• Es wird überprüft, ob es mit den tatsächlichen Eingaben des Agenten funktioniert.

Für Datenbank-Tools könnte das bedeuten:

• Wird die Read-Only-Rolle korrekt durchgesetzt?
• Werden Zeilenlimits eingehalten?
• Werden sensible Daten oder Stack Traces in den Antworten vermieden?

Praktische Beispiele: Was wirklich geprüft wird

Die eigentliche Stärke von mcp-probe liegt in der Validierung von realen Tool-Aufrufen mit aussagekräftigen Eingaben. Ein Beispiel für eine Testkonfiguration:

{
  "tools": {
    "logs_query": {
      "input": {
        "query": "service:web status:error",
        "timeframe": "1h"
      },
      "expect": {
        "status": "pass",
        "not_error_code": [401, 403],
        "requiredFields": ["source", "freshness"],
        "maxRows": 100
      }
    }
  }
}

Hier wird nicht nur abgefragt, ob das Tool logs_query existiert. Es wird getestet:

• Ob die Abfrage mit den angegebenen Parametern funktioniert.
• Ob die API mit den erwarteten Fehlercodes antwortet.
• Ob die Antwort die geforderten Felder wie source und freshness enthält.
• Ob die Zeilenbegrenzung auf 100 eingehalten wird.

Solche Tests sind entscheidend, um sicherzustellen, dass ein MCP-Server später auch in der Produktion zuverlässig arbeitet – insbesondere, wenn er von KI-Agenten genutzt wird, die keine manuellen Fehlerbehebungen vornehmen können.

Fazit: Von oberflächlichen Checks zu echten Vertragstests

Die neuen Funktionen von mcp-probe 1.8.0 markieren einen wichtigen Schritt hin zu robusten CI-Pipelines für MCP-Server. Statt sich auf einfache Schema-Validierungen zu verlassen, können Teams nun:

• Warnungen als Blockaden für CI einrichten.
• Sicherstellen, dass alle relevanten Flags in einem einzigen Workflow-Schritt kombiniert werden.
• Echte Tool-Aufrufe mit aussagekräftigen Eingaben und Plausibilitätsprüfungen testen.

Das Ziel ist klar: CI sollte nicht nur prüfen, ob ein Server startet, sondern ob er den Vertrag erfüllt, den später ein KI-Agent nutzen wird.

Mit diesen Verbesserungen wird mcp-probe zu einem unverzichtbaren Werkzeug für Teams, die MCP-Server in Produktionsumgebungen einsetzen – und dabei auf Zuverlässigkeit und Sicherheit setzen müssen.