Testing & Debugging

The launcher prints a URL that contains a one-time session token, and you open that URL. The token exists because the Node process behind the page can spawn processes on your machine, so every /api/* route is guarded by a per-launch token. Treat the token like a password: do not paste the URL into a ticket, a chat or a screen share, do not commit it to a script, and if you must pin one for a scripted launch set the MCP_INSPECTOR_API_TOKEN environment variable from a secret store instead of typing a value. The Inspector documents an environment switch that disables the check entirely; use it only on a machine where nothing else can reach the port. By default the web client binds localhost and accepts only loopback origins, and binding all interfaces is refused unless you explicitly opt in, which you should not do on a shared network.

The tab bar adapts to what the server declares. The ones you will use most:

The web client is also a good place to complete an OAuth flow by hand: it stores the resulting tokens on disk, where the CLI can reuse them (see Authorization).

The Inspector treats the protocol era as a per-server setting. legacy (before 2026-07-28: initialize and sessions) is the default, modern pins exactly 2026-07-28 with no fallback, and auto probes server/discover and falls back to initialize. A debugging tool does not probe by default because a probe can stall against a silent stdio server and pollutes the transcript you are trying to read. The consequence for scripts is important: an ad-hoc CLI run is legacy unless you pass --protocol-era modern, so every command on this page states its era. The Python and TypeScript builds serve both eras, while the Java SDK and Spring AI 2.0.x speak 2025-11-25 only and must be tested with --protocol-era legacy (see Spring Boot MCP Servers). Running the modern era against them fails as expected:

Each CLI run connects, sends the single request named by --method, prints the result and exits. The server is a positional command for stdio, a URL with --transport http for Streamable HTTP, or a named entry of a catalog or config file (--config with --server). The flags that matter for testing, all confirmed with mcp-inspector --cli --help (2.8.0):

The CLI declares no elicitation capability, so a tool that asks the user a question cannot complete through it; that is why the contract script below tests the multi-round-trip step with curl.

On any non-zero exit the CLI writes one JSON line to stderr, {"error":{"code":"unreachable","message":"..."}} for instance, so a script can branch on code instead of scraping prose. A tools/call with isError: true still prints its payload on stdout and then exits 5, so a && chain stops there. The full reference is the Inspector’s CLI client page; the launcher, web, TUI, era and authorization pages are linked from the Inspector overview.

The script was run on 2026-09-29 against freshly started servers, with these outcomes:

The stdio runs have five steps because step 6 needs HTTP, and the two Spring runs have five because they use the legacy era, where the multi-round-trip step is skipped. The standalone FastMCP 4 build on Python MCP Servers is not part of this table. The server pages show how each build is started: Python, Python in FastAPI, Node.js and Spring Boot. Point INSPECTOR at a local node_modules/.bin/mcp-inspector when the Inspector is not installed globally.

The contract needs a running server. The layer under it does not, and it is much faster. The Python SDK’s Client accepts the MCPServer object itself and connects to it in-process, with no subprocess and no port:

This ran against mcp 2.2.0 and printed in-process test passed. The Client docstring says this in-process form is meant for tests. See the Python SDK documentation. For the Java build, @SpringBootTest with a random port and the MCP Java SDK client is the equivalent, in the style of Unit and Integration Testing; the TypeScript SDK ships a client that connects over stdio or Streamable HTTP for the same purpose (see Building MCP Clients).

A stdio server has one more property that the Inspector will not catch, because it tolerates stray lines on stdout: nothing but JSON-RPC may be written there. This script sends one request and fails if any stdout line is not JSON. It passed for the Python and TypeScript stdio servers and failed, naming the offending line, for a copy of the Python server with one print() added.

A script that must react differently to an unreachable server and to a tool error uses the exit code and the single JSON line on stderr:

Run against a closed port, this printed unreachable (the error object was {"code":"unreachable","message":"Version negotiation probe failed: fetch failed"}, with exit 4).

Where the server sits behind OAuth, use --stored-auth-only so that a CI run can never start a browser flow and hang: with no usable token the CLI fails fast with auth_required and exit 3, and with a token it proceeds. Two ways to supply the credential without putting a secret in the repository are a token that was already obtained on the runner and stored by the Inspector, or a short-lived token that the job requests from your identity provider and passes in an environment variable:

MCP_TEST_TOKEN comes from the repository’s secret store (in a workflow, a secrets expression mapped to env), is never echoed, and belongs to a test client with the least scope needed. Against a stub that answered every request with 401, this command sent the Authorization header and exited 3; a real token-issuing setup is described on Authorization. Do not reuse a token that was issued for another service: an MCP server must accept only tokens issued for itself. The CLI also offers --print-handoff, --wait-for-auth and --use-stored-auth for the case where a human completes the browser flow on another machine; they are described on the Inspector’s Authorization page.

The Python SDK emits an OpenTelemetry server span for every request when a tracer provider is configured, and it continues the trace from the traceparent in _meta. In a run with a console exporter, the tools/call search_docs span carried the parent span id 00f067aa0ba902b7 from the header, with the attributes mcp.method.name and gen_ai.tool.name. The server code only has to configure the provider, keep logs on stderr, and add its own child spans:

The run printed only the JSON result on stdout and, on stderr, the log line INFO trace=0af7651916cd43dd8448eb211c80319c docs-assistant search_docs component=algebra query_len=6 together with the spans. It needs opentelemetry-api and opentelemetry-sdk (1.45.0 here) next to mcp. Because the stdout of a stdio server is the protocol, logging.basicConfig() alone would also be safe, since the standard library logs to stderr by default; the explicit handler is there to attach the trace id. See the OpenTelemetry Python documentation.

The TypeScript SDK exposes the request’s _meta as ctx.mcpReq._meta, with the reserved io.modelcontextprotocol/* keys already lifted out, so traceparent is readable there. The installed @modelcontextprotocol packages contain no OpenTelemetry references, so the server continues the trace itself, with the OpenTelemetry API’s propagator:

Install @opentelemetry/api, @opentelemetry/core, @opentelemetry/sdk-trace-base and @opentelemetry/sdk-trace-node (1.9.1 for the API and 2.11.0 for the others in this run) next to the MCP packages. The files type-check with tsc --noEmit. Through the Inspector the log line carried traceId 0af7651916cd43dd8448eb211c80319c and the exported span had parentSpanId 00f067aa0ba902b7, with only the JSON result on stdout. The default ConsoleSpanExporter of the OpenTelemetry SDK prints to standard output, which is exactly the mistake a stdio server cannot afford, so the demo exporter writes to stderr instead.

Spring Boot logs to the console, which is standard output. On a stdio Spring server that would corrupt the protocol, and it did: without configuration the server wrote its log lines on stdout. The cure is either logging.threshold.console=off (see Spring Boot MCP Servers) or a Logback configuration whose console appender targets System.err. The second keeps the logs, and a tool method can receive the request’s _meta as an McpMeta parameter (a Spring AI annotation-package type whose get(String) reads a key) and copy traceparent into the logging MDC:

Started in stdio mode through a wrapper script (passing Spring’s own -- options directly after java -jar made the Inspector hand its trailing flags to java, which printed its usage text, so a run.sh wrapper that holds the whole command is the reliable form), the server wrote every log line to stderr, and the line for the tool call read INFO [traceparent=00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01] d.e.d.DocsTools - search_docs component=algebra queryLength=6, while stdout carried only the JSON result. The McpSyncRequestContext type also offers debug, info, warn and error; those send protocol log notifications, which belong to the deprecated channel, so prefer SLF4J. For real tracing, Spring Boot’s own Micrometer-based tracing can export to an OpenTelemetry collector, and the same traceparent value is what a bridge would read from McpMeta; that setup was not run, so only the MDC correlation above is shown. The Java SDK speaks protocol 2025-11-25, where _meta carries what the client puts there; hosts that support trace propagation send traceparent in it. See the Spring AI MCP server annotations and the Logback ConsoleAppender documentation. The agent-level view of the same data is on Observability for Agents.

Logs and traces must never contain secrets. Log the tool name, the sizes and identifiers of arguments, and the outcome; do not log bearer tokens, Authorization headers or whole arguments that may carry personal data. The web Inspector masks secrets in its own views, but your server’s log files do not.