Fix/stdio jsonrpc handshake

pkg/gateway/run.go

@@ -394,11 +394,15 @@ func (g *Gateway) Run(ctx context.Context) error {
 		g.authTokenWasGenerated = wasGenerated
 	}
 
-	// Start the server
+	// Start the server.
+	//
+	// NOTE: Some transports (e.g. stdio) run asynchronously and return immediately,
+	// while others (HTTP/SSE) block until the server shuts down.
 	switch transport {
 	case "stdio":
 		log.Log("> Start stdio server")
-		return g.startStdioServer(ctx, os.Stdin, os.Stdout)
+		g.startStdioServer(ctx, os.Stdin, os.Stdout)
+		return nil
 
 	case "sse":
 		log.Log("> Start sse server on port", g.Port)

pkg/gateway/transport.go

@@ -13,9 +13,19 @@ import (
 	"github.com/docker/mcp-gateway/pkg/health"
 )
 
+// startStdioServer starts the MCP server using stdio transport.
+//
+// The stdio transport blocks while processing input/output, so it must be
+// started asynchronously to keep the gateway lifecycle consistent with
+// other transports (HTTP/SSE).
 func (g *Gateway) startStdioServer(ctx context.Context, _ io.Reader, _ io.Writer) error {
 	transport := &mcp.StdioTransport{}
-	return g.mcpServer.Run(ctx, transport)
+
+	go func() {
+		_ = g.mcpServer.Run(ctx, transport)
+	}()
+
+	return nil
 }
 
 func (g *Gateway) startSseServer(ctx context.Context, ln net.Listener) error {

pkg/gateway/transport_stdio_test.go

@@ -0,0 +1,38 @@
+package gateway
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+func TestStartStdioServer_DoesNotBlock(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	impl := &mcp.Implementation{}
+	opts := &mcp.ServerOptions{}
+
+	g := &Gateway{
+		mcpServer: mcp.NewServer(impl, opts),
+	}
+
+	done := make(chan struct{})
+
+	go func() {
+		err := g.startStdioServer(ctx, nil, nil)
+		if err != nil {
+			t.Errorf("unexpected error: %v", err)
+		}
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// ok
+	case <-time.After(100 * time.Millisecond):
+		t.Fatal("startStdioServer blocked, expected non-blocking behavior")
+	}
+}