FIX stdio URL bug with proxyMode #2935

slyt3 · 2025-12-07T18:10:37Z

Problem

So deploying an MCPServer with transport: stdio and proxyMode: streamable-http, the status URL shows incorectly returns /sse endpoint instead of /mcp

Example

apiVersion: toolhive.stacklok.dev/v1alpha1
kind: MCPServer
metadata:
  name: arxiv
  namespace: toolhive-system
spec:
  image: ghcr.io/stacklok/dockyard/uvx/arxiv-mcp-server:0.3.1
  transport: stdio
  proxyMode: streamable-http
  proxyPort: 8080

Expected status URL:

http://arxiv.toolhive-system.svc.cluster.local:8080/mcp

Actual status URL:

http://arxiv.toolhive-system.svc.cluster.local:8080/sse#arxiv

Root Cause

The bug is in pkg/transport/url.go

This code is old and it shows that its treating stdio same as sse and ignoring proxyMode

isSSE := transportType == types.TransportTypeSSE.String() || 
         transportType == types.TransportTypeStdio.String()

So thinking logically we should assume that stdio always use SSE endpoint but stdio can use it either

proxyMode: sse → /sse endpoint
proxyMode: streamable-http → /mcp endpoint (default)

And the controller at cmd/thv-operator/controllers/mcpserver_controller.go:395 only passes Transport, never ProxyMode:

OLD CODE TOO missing proxyMode parameter

mcpServer.Status.URL = transport.GenerateMCPServerURL(
    mcpServer.Spec.Transport,
    host,
    int(mcpServer.GetProxyPort()),
    mcpServer.Name,
    "",
)

Solution

So I Added proxyMode parameter to GenerateMCPServerURL() function:

func GenerateMCPServerURL(transportType string, proxyMode string, host string, 
    port int, containerName, remoteURL string) string

Logic:

For stdio transport: Use proxyMode to easily determine endpoint
- proxyMode: "streamable-http" → /mcp
- proxyMode: "sse" → /sse#name
- proxyMode: "" (empty) → defaults to /mcp (matches CRD default)
For other transports: JUST Ignore proxyMode its behaviour doesnt change xD
- sse transport → always /sse#name
- streamable-http transport → always /mcp

Type Conversions

Added string() conversions where ProxyMode is a typed string (was stuck on this one for whole night, was going crazy i just needed to convert ProxyMode string to function call, so proxyMode is defined as type ProxyMode string:

string(r.Config.ProxyMode)

Testing

Unit Tests (15/15 passing)

$ go test ./pkg/transport/... -v -run TestGenerateMCPServerURL

Key test cases covering the bug:

Test	Transport	ProxyMode	Expected	Result
Bug case	stdio	streamable-http	`/mcp`	✅ PASS
Edge case	stdio	sse	`/sse#name`	✅ PASS
Default	stdio	"" (empty)	`/mcp`	✅ PASS
Unchanged	sse	(ignored)	`/sse#name`	✅ PASS
Unchanged	streamable-http	(ignored)	`/mcp`	✅ PASS

All 15 tests pass including targetURI path handling.

Changes

7 files changed:

pkg/transport/url.go - Added proxyMode parameter and logic
pkg/transport/url_test.go - Added comprehensive test coverage
cmd/thv-operator/controllers/mcpserver_controller.go - Updated call site
pkg/runner/runner.go - Updated call site with type conversion
pkg/workloads/manager.go - Updated call site with type conversion
pkg/workloads/types/types.go - Updated call site with empty string default
pkg/vmcp/workloads/k8s.go - Updated call site with type conversion

Build status:

$ go build ./...

Impact

This fix ensures stdio transport respects the proxyMode setting:

Config	Before (Bug)	After (Fixed)
stdio + streamable-http	`/sse` ❌	`/mcp` ✅
stdio + sse	`/sse` ✅	`/sse` ✅
stdio + (empty)	`/sse` ❌	`/mcp` ✅
sse transport	`/sse` ✅	`/sse` ✅
streamable-http transport	`/mcp` ✅	`/mcp` ✅

Soooo since CRD is default for proxyMode is streamable-http` bug affects the default stdio configuration

Fixes #2920

codecov · 2025-12-08T13:59:53Z

Codecov Report

❌ Patch coverage is 73.68421% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 56.37%. Comparing base (28797fa) to head (8f11963).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
...d/thv-operator/controllers/mcpserver_controller.go	0.00%	1 Missing ⚠️
pkg/runner/runner.go	0.00%	1 Missing ⚠️
pkg/vmcp/workloads/k8s.go	0.00%	1 Missing ⚠️
pkg/workloads/manager.go	0.00%	1 Missing ⚠️
pkg/workloads/types/types.go	0.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2935   +/-   ##
=======================================
  Coverage   56.36%   56.37%           
=======================================
  Files         323      323           
  Lines       31763    31777   +14     
=======================================
+ Hits        17904    17915   +11     
- Misses      12330    12333    +3     
  Partials     1529     1529

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

jhrozek

Thanks for working on this fix - the core approach of adding proxyMode to GenerateMCPServerURL is correct.

However, there's a bug in one of the call sites that would have been caught by testing the CLI (not just unit tests). Please make sure to test your changes end-to-end before submitting PRs - running thv run with different transport/proxyMode combinations and then thv list would have revealed the issue in WorkloadFromContainerInfo.

See inline comments for details.

jhrozek · 2025-12-10T13:19:50Z

pkg/workloads/types/types.go

 	url := ""
 	if port > 0 {
-		url = transport.GenerateMCPServerURL(transportType, transport.LocalhostIPv4, port, name, "")
+		url = transport.GenerateMCPServerURL(transportType, "", transport.LocalhostIPv4, port, name, "")


This is passing an empty string for proxyMode, but the actual value from runConfig.ProxyMode isn't loaded until line 93. The URL gets generated before we know what the proxy mode is.

If you run thv run with --transport stdio --proxy-mode sse and then thv list, you'll see the URL shows /mcp instead of /sse#name.

The fix is to move the loadRunConfigFields call before the URL generation:

transportType := labels.GetTransportType(container.Labels) tType, err := types.ParseTransportType(transportType) if err != nil { tType = types.TransportTypeSSE } // Load RunConfig first so we have proxyMode available ctx := context.Background() runConfig, err := loadRunConfigFields(ctx, name) if err != nil { return core.Workload{}, err } // Now we can generate the URL with the correct proxyMode url := "" if port > 0 { url = transport.GenerateMCPServerURL(transportType, runConfig.ProxyMode, transport.LocalhostIPv4, port, name, "") }

jhrozek · 2025-12-10T13:19:50Z

pkg/transport/url_test.go

 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
-			url := GenerateMCPServerURL(tt.transportType, tt.host, tt.port, tt.containerName, tt.targetURI)
+			url := GenerateMCPServerURL(tt.transportType, tt.proxyMode, tt.host, tt.port, tt.containerName, tt.targetURI) // ✅ ADD proxyMode parameter


Leftover comment from development - please remove before merging.

Suggested change

url := GenerateMCPServerURL(tt.transportType, tt.proxyMode, tt.host, tt.port, tt.containerName, tt.targetURI) // ✅ ADD proxyMode parameter

url := GenerateMCPServerURL(tt.transportType, tt.proxyMode, tt.host, tt.port, tt.containerName, tt.targetURI)

jhrozek · 2025-12-10T13:19:50Z

pkg/transport/url.go

+		// Default to streamable-http if proxyMode is empty (matches CRD default)
+		effectiveProxyMode := proxyMode
+		if effectiveProxyMode == "" {
+			effectiveProxyMode = "streamable-http"


Minor: consider using the typed constant types.ProxyModeStreamableHTTP.String() instead of the magic string. Same for "sse" on line 32. Not a blocker, but it's more consistent with the rest of the codebase.

slyt3 · 2025-12-10T13:45:09Z

Thankyou for your response, i will look into it and fix

FIX stdio URL bug with proxyMode

8f11963

github-actions bot added the size/XS Extra small PR: < 100 lines changed label Dec 8, 2025

fix: Format code to pass lint checks

81c08ce

jhrozek requested changes Dec 10, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

FIX stdio URL bug with proxyMode #2935

FIX stdio URL bug with proxyMode #2935

Uh oh!

slyt3 commented Dec 7, 2025 •

edited

Loading

Uh oh!

codecov bot commented Dec 8, 2025

Uh oh!

jhrozek left a comment

Uh oh!

jhrozek Dec 10, 2025

Uh oh!

jhrozek Dec 10, 2025

Uh oh!

jhrozek Dec 10, 2025

Uh oh!

slyt3 commented Dec 10, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	url := GenerateMCPServerURL(tt.transportType, tt.proxyMode, tt.host, tt.port, tt.containerName, tt.targetURI) // ✅ ADD proxyMode parameter
	url := GenerateMCPServerURL(tt.transportType, tt.proxyMode, tt.host, tt.port, tt.containerName, tt.targetURI)

FIX stdio URL bug with proxyMode #2935

Are you sure you want to change the base?

FIX stdio URL bug with proxyMode #2935

Uh oh!

Conversation

slyt3 commented Dec 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Example

Root Cause

Solution

Logic:

Type Conversions

Testing

Unit Tests (15/15 passing)

Changes

Impact

Uh oh!

codecov bot commented Dec 8, 2025

Codecov Report

Uh oh!

jhrozek left a comment

Choose a reason for hiding this comment

Uh oh!

jhrozek Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

jhrozek Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

jhrozek Dec 10, 2025

Choose a reason for hiding this comment

Uh oh!

slyt3 commented Dec 10, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

slyt3 commented Dec 7, 2025 •

edited

Loading