Upgrade thv inspector to MCP Inspector v2
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 2.2k
- Forks
- 300
- Avg merge
- 1d 15h
- Merged PRs (30d)
- 184
Description
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-portflags) — 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.0andDANGEROUSLY_BIND_ALL_INTERFACES=true. We only setHOSTtoday (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_TOKENdoesn't exist in v2. The token is nowMCP_INSPECTOR_API_TOKEN, injected server-side into the served HTML rather than read purely from a URL query param. - Config/CLI model changed substantially.
--confignow means a read-only session file and--catalogis 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 inbuildInspectorURL,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
- Spike
thv inspectoragainst the v2 image locally to confirm exactly what breaks (port model, env vars, deep-link URL). - Update
buildInspectorContainerOptions, the env vars passed to the container, andbuildInspectorURLto match v2's model. - Update
inspector/version.goto pin the v2 tag once the above is verified working. - Check e2e tests for
thv inspector(test/e2e/) for assumptions baked in about the two-port model.
Additional context
- Inspector v2.0.0 release notes
- Upstream MCP server configuration doc
- Renovate is already aware of the major bump (Dependency Dashboard #561) but has it gated as unscheduled.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by testing the v2 container locally, then read cmd/thv/app/inspector.go, especially buildInspectorContainerOptions and buildInspectorURL, plus cmd/thv/app/inspector/version.go. Check test/e2e/ for two-port assumptions. Done means the v2 tag is pinned, ports and environment variables work, deep-link or catalog configuration connects correctly, and the e2e tests pass.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, go
- Domain
- cli, devtools, testing-qa
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100