MCP Inspector – Entwickler-Guide

Worum geht's?

Der MCP Inspector ist das offizielle interaktive Entwickler-Tool zum Testen und Debuggen von Model-Context-Protocol-(MCP)-Servern. Du kannst dich damit mit einem Server verbinden, seine Tools auflisten und aufrufen, seine Resources auslesen, seine Prompts rendern und den rohen Protokoll-Traffic mitverfolgen – ohne den Server vorher in einen vollständigen LLM-Client einbinden zu müssen. Dieser Guide behandelt die Architektur, alle Startmöglichkeiten, die Konfigurationsoberfläche und das Sicherheitsmodell.

Du suchst stattdessen eine Schritt-für-Schritt-Anleitung durch die Felder der Web-UI? Siehe den MCP Inspector User Guide.

Repository: https://github.com/modelcontextprotocol/inspector Package: @modelcontextprotocol/inspector (npm) Runtime-Voraussetzung: Node.js ^22.7.5

1. Was es ist und wann du es einsetzt

Der Inspector sitzt zwischen dir und einem MCP-Server und gibt dir einen praktischen Einblick in alles, was der Server über das Protokoll bereitstellt. Greif dazu, wenn du:

einen MCP-Server baust und Tools, Resources und Prompts verifizieren willst, bevor du ihn an Claude, Cursor oder VS Code anbindest;
eine Verbindung debuggen musst – Capability-Aushandlung, Transport-Fehler, Auth-Handshakes;
einen Drittanbieter-Server (npm-/PyPI-Paket) inspizieren willst, bevor du ihm vertraust;
Grenzfälle durchspielen musst – ungültige Eingaben, fehlende Argumente, Fehlerantworten – interaktiv oder per Skript.

Er ergänzt die umfassendere MCP-Arbeit aus dem MCP Connector Guide for Claude: In jenem Guide geht es um das Bauen und Ausliefern von Connectors, in diesem um das Inspizieren und Debuggen.

2. Architektur

Der Inspector besteht aus zwei zusammenarbeitenden Prozessen:

+----------------------+        +----------------------+        +------------------+
|  MCP Inspector       |  HTTP  |  MCP Proxy           | stdio  |  Your MCP server |
|  Client (MCPI)       | <----> |  (MCPP)              | SSE    |  (node/python/…) |
|  React web UI        |        |  Node.js bridge      | HTTP   |                  |
|  http://localhost:6274        |  http://localhost:6277        |                  |
+----------------------+        +----------------------+        +------------------+

Komponente	Name	Standard-Port	Rolle
Inspector Client	MCPI	`6274`	React-Web-UI, mit der du im Browser interagierst
Inspector Proxy	MCPP	`6277`	Node.js-Bridge, die den Server startet/verbindet und Transports übersetzt

Warum zwei Prozesse?

Ein Browser-Tab kann keinen lokalen Prozess starten oder eine beliebige stdio-Pipe öffnen. Der Proxy (MCPP) erledigt das auf deinem Rechner und stellt es der Web-UI (MCPI) über HTTP bereit. Der Proxy setzt außerdem die Session-Token-Authentifizierung durch, die weiter unten in §8 beschrieben wird.

Die Portnummern sind eine T9-Tastatur-Eselsbrücke: MCPI → 6274, MCPP → 6277.

3. Voraussetzungen

Node.js ^22.7.5 (der Inspector erzwingt diese Engine).
Den Befehl, um deinen Server lokal zu starten (für STDIO), oder eine erreichbare URL (für SSE / Streamable HTTP).
Alle Secrets, die der Server selbst benötigt (API-Keys, Tokens) – als Umgebungsvariablen oder Header übergeben, niemals fest im Code hinterlegt.

4. Schnellstart

Der Inspector läuft über npx ganz ohne Installationsschritt.

Reine UI

npx @modelcontextprotocol/inspector

Das startet beide Prozesse und öffnet http://localhost:6274 mit einer vorab authentifizierten Session-Token-URL, die im Terminal ausgegeben wird.

Ein veröffentlichtes Paket inspizieren

# npm package
npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /Users/you/Desktop

# PyPI package (via uvx)
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/my-repo

Einen lokal entwickelten Server inspizieren

# TypeScript: pass the runtime + entrypoint + args
npx @modelcontextprotocol/inspector node build/index.js arg1 arg2

# Python (uv project)
npx @modelcontextprotocol/inspector uv --directory path/to/server run package-name args...

Umgebungsvariablen und eigene Ports übergeben

# -e injects env vars into the spawned server process
npx @modelcontextprotocol/inspector -e API_KEY=value node build/index.js

# Override the UI and proxy ports
CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node build/index.js

Alles nach dem Paketnamen ist der Server-Befehl

In npx @modelcontextprotocol/inspector node build/index.js --flag behandelt der Inspector node als Command und build/index.js --flag als Arguments. Diese werden direkt auf die UI-Felder abgebildet, die im User Guide dokumentiert sind.

Docker

docker run --rm \
  -p 127.0.0.1:6274:6274 \
  -p 127.0.0.1:6277:6277 \
  -e HOST=0.0.0.0 \
  -e MCP_AUTO_OPEN_ENABLED=false \
  ghcr.io/modelcontextprotocol/inspector:latest

5. UI-Modus vs. CLI-Modus

	UI-Modus (Standard)	CLI-Modus (`--cli`)
Am besten für	Erkundung, manuelles Testen, OAuth-Debugging	Skripting, CI, Automatisierung, schnelle Einzelaufrufe
Ausgabe	Interaktive Browser-UI	Klartext / JSON nach stdout
Auth-UX	Session-Token in der URL	Kein Browser; Token bei Bedarf per env

Der CLI-Modus führt dieselbe Proxy-Logik aus, überspringt aber den Browser komplett.

# List tools of a local server
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

# Call a tool with arguments
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name mytool --tool-arg key=value

# Talk to a remote HTTP server
npx @modelcontextprotocol/inspector --cli https://my-server.example.com \
  --transport http --method tools/list

# Send a custom header (e.g. an API key)
npx @modelcontextprotocol/inspector --cli https://my-server.example.com \
  --header "X-API-Key: value" --method tools/list

# Drive it from a config file entry
npx @modelcontextprotocol/inspector --cli --config ./mcp.json --server myserver --method tools/list

Gängige --method-Werte spiegeln die MCP-Spezifikation wider: tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get.

6. Konfigurationsdatei (`mcp.json`)

Statt Befehle immer wieder neu einzutippen, kannst du Server-Definitionen in einer Konfigurationsdatei ablegen und eine davon per Name auswählen. Das Format entspricht der vertrauten mcpServers-Struktur, die Claude Desktop und andere Clients verwenden:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["build/index.js"],
      "env": { "API_KEY": "value" }
    },
    "sse-server": {
      "type": "sse",
      "url": "http://localhost:3000/sse"
    },
    "http-server": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Lade sie und wähle einen Server:

npx @modelcontextprotocol/inspector --config ./mcp.json --server my-server

Hin und zurück mit der UI

Die Buttons Server Entry und Servers File in der UI geben genau dieses JSON aus. Konfiguriere einen Server einmal visuell, kopiere ihn heraus und commite ihn in mcp.json für wiederholbare Läufe und CI.

7. Umgebungsvariablen (beim Start)

Diese werden auf dem Prozess gesetzt, der den Inspector startet (nicht zu verwechseln mit den Umgebungsvariablen des Servers selbst, die über -e übergeben werden):

Variable	Zweck	Hinweise
`CLIENT_PORT`	Port für die Web-UI (MCPI)	Standard `6274`
`SERVER_PORT`	Port für den Proxy (MCPP)	Standard `6277`
`HOST`	Interface, an das sich der Proxy bindet	Standard localhost; `0.0.0.0` nur in vertrauenswürdigen Netzwerken setzen
`MCP_PROXY_AUTH_TOKEN`	Den Proxy-Session-Token auf einen festen Wert pinnen	Andernfalls pro Lauf automatisch generiert
`ALLOWED_ORIGINS`	Komma-getrennte Allowlist für DNS-Rebinding-/Origin-Prüfungen	z. B. `http://localhost:6274`
`MCP_AUTO_OPEN_ENABLED`	Browser beim Start automatisch öffnen	Für Docker / headless auf `false` setzen
`DANGEROUSLY_OMIT_AUTH`	Proxy-Auth komplett deaktivieren	Nicht verwenden – siehe §8

8. Authentifizierung & das Sicherheitsmodell

Standardmäßig generiert der Proxy bei jedem Start einen zufälligen Session-Token und gibt eine vorausgefüllte URL aus:

🔑 Session token: 3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4
🔗 http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=3a1c267f...

Öffnest du diese URL, wird die UI automatisch authentifiziert. Öffnest du stattdessen ein nacktes http://localhost:6274, wirst du aufgefordert, den Token unter Configuration → Proxy Session Token einzufügen.

Niemals die Authentifizierung deaktivieren

Der Proxy kann lokale Prozesse starten und sich mit lokalen Servern verbinden. DANGEROUSLY_OMIT_AUTH=true entfernt die Token-Schranke, was – laut der Warnung des Projekts selbst – deinen Rechner für eine Kompromittierung aus der Ferne öffnet: „Visiting a malicious website or viewing a malicious advertisement could allow an attacker to remotely compromise your computer."

Lass die standardmäßige Token-Auth aktiviert. Lass den Proxy an localhost gebunden. Setze HOST=0.0.0.0 nur in einem Netzwerk, dem du voll vertraust, und kombiniere es mit ALLOWED_ORIGINS.

Die Auth zum Server selbst (ein separates Thema) wird in der UI konfiguriert:

Custom Headers / Bearer Token – für SSE- und Streamable-HTTP-Server, die einen Authorization: Bearer …-Header oder einen API-Key-Header erwarten.
OAuth-2.0-Flow – der Inspector kann den vollständigen Authorization-Code-Flow ausführen, inklusive Metadata-Discovery und dynamischer Client-Registrierung, und das resultierende Access-Token einschleusen. Siehe den User Guide (Abschnitt Authentication & Open Auth Settings) für die Schritt-für-Schritt-Anleitung Feld für Feld.

9. Am Inspector selbst entwickeln

Wenn du am Inspector-Quellcode arbeitest (statt ihn nur zu nutzen):

npm run dev      # run client + proxy in watch mode
npm run build    # production build
npm start        # serve the built app

Um gegen einen lokalen Checkout des MCP SDK zu entwickeln:

npm run dev:sdk "cd sdk && npm run examples:simple-server:w"

10. Typischer Workflow & Troubleshooting

Iterative Server-Entwicklung:

Starte den Inspector mit deinem Server.
Verifiziere Konnektivität und Capability-Aushandlung (prüfe den Notifications-Bereich).
Nimm eine Änderung vor → baue den Server neu → Reconnect in der UI.
Teste die betroffenen Tools/Resources erneut und beobachte das Nachrichtenprotokoll.
Prüfe die Fehlerbehandlung mit ungültigen Eingaben und fehlenden Argumenten.

Häufige Probleme:

Symptom	Wahrscheinliche Ursache	Lösung
"Connection Error — did you add the proxy session token?"	UI ohne Token geöffnet	Verwende die ausgegebene URL oder füge den Token unter Configuration ein
"Error connecting to MCP Inspector Proxy"	Proxy läuft nicht / falscher Port	Bestätige MCPP auf `6277`; prüfe `SERVER_PORT`
Server startet und beendet sich dann	Falsche Command/Arguments, fehlende Umgebungsvariable	Prüfe den Startbefehl erneut; ergänze Variablen über `-e` oder die UI
Tool-Aufruf läuft in einen Timeout	Lang laufendes Tool überschreitet das Request-Timeout	Erhöhe Request Timeout im Configuration-Panel (siehe User Guide §7)

Weiterführende Lektüre

MCP Inspector User Guide – die Referenz der Web-Interface-Felder (Transport Type, Command, Arguments, Auth, OAuth, Configuration).
MCP Connector Guide for Claude – MCP-Server/Connectors bauen und deployen.
MCP Inspector on GitHub
MCP Inspector docs (modelcontextprotocol.io)

1. Was es ist und wann du es einsetzt​

2. Architektur​

3. Voraussetzungen​

4. Schnellstart​

Reine UI​

Ein veröffentlichtes Paket inspizieren​

Einen lokal entwickelten Server inspizieren​

Umgebungsvariablen und eigene Ports übergeben​

Docker​

5. UI-Modus vs. CLI-Modus​

6. Konfigurationsdatei (mcp.json)​

7. Umgebungsvariablen (beim Start)​

8. Authentifizierung & das Sicherheitsmodell​

9. Am Inspector selbst entwickeln​

10. Typischer Workflow & Troubleshooting​

Weiterführende Lektüre​