Skip to content

Upgrade thv inspector to MCP Inspector v2 #6151

Description

@danbarr

Summary

thv inspector is pinned to MCP Inspector v1 (ghcr.io/modelcontextprotocol/inspector:0.21.2, set in cmd/thv/app/inspector/version.go:10). Inspector v2.0.0 shipped alongside the 2026-07-28 MCP spec revision and brings full cross-compatibility between the legacy and modern spec, which our current integration doesn't get. v1 is now deprecated upstream (security fixes only, under the v1-latest tag), so we should move to v2 rather than keep tracking the v1 line.

This is not a simple version bump. Renovate already has an unscheduled major-bump branch open (see the Dependency Dashboard, #561), but a straight tag swap will break thv inspector because v2 is a genuine rearchitecture:

  • Single port instead of two. v2's container exposes only CLIENT_PORT (default 6274). Our current implementation binds and forwards a separate UI port and MCP-proxy port (cmd/thv/app/inspector.go:34-68, --ui-port/--mcp-proxy-port flags) — that split no longer exists on the v2 side.
  • New required env var to bind on all interfaces. v2's Dockerfile needs both HOST=0.0.0.0 and DANGEROUSLY_BIND_ALL_INTERFACES=true. We only set HOST today (cmd/thv/app/inspector.go:149); without the second var the container likely refuses to bind and the forwarded port becomes unreachable.
  • Auth token handling changed. v1's MCP_PROXY_AUTH_TOKEN doesn't exist in v2. The token is now MCP_INSPECTOR_API_TOKEN, injected server-side into the served HTML rather than read purely from a URL query param.
  • Config/CLI model changed substantially. --config now means a read-only session file and --catalog is the writable server list (see upstream's MCP server configuration doc). It's not yet clear whether our current deep-link approach (?transport=...&serverUrl=..., built in buildInspectorURL, cmd/thv/app/inspector.go:243-251) still auto-connects to a server under v2, or whether we need to switch to writing a catalog file instead.

Proposed next steps

  1. Spike thv inspector against the v2 image locally to confirm exactly what breaks (port model, env vars, deep-link URL).
  2. Update buildInspectorContainerOptions, the env vars passed to the container, and buildInspectorURL to match v2's model.
  3. Update inspector/version.go to pin the v2 tag once the above is verified working.
  4. Check e2e tests for thv inspector (test/e2e/) for assumptions baked in about the two-port model.

Additional context

Metadata

Metadata

Assignees

No one assigned

    Labels

    cliChanges that impact CLI functionalityenhancementNew feature or requestneeds-triageIssue needs initial triage by a maintainer

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions