stacklok / stacklok/toolhive

Upgrade thv inspector to MCP Inspector v2

Open
#6,151 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

cli enhancement needs-triage
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-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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.