Skip to content

Agent Mesh

node: perform the MCP handshake once in the stdio bridge

Antonio Ojea4da1f4a60241
diff --git a/internal/node/service.go b/internal/node/service.go
index 321b166a..ff869725 100644
--- a/internal/node/service.go
+++ b/internal/node/service.go
@@ -79,9 +79,10 @@ func (b *baseService) Info() *api.ServiceInfo { return b.info }
func (b *baseService) Handler() http.Handler { return b.handler }
// Init builds the ingress handler for the backend: URL -> reverse-proxy,
-// Command -> StdioBridge (the local SSE/POST HTTP route only - mesh
-// sessions get their own subprocess via MCPService.backendTransport
-// instead of this one). MCPService extends this; it does not replace it.
+// Command -> StdioBridge, one process shared by every caller, with the
+// bridge owning the id space and the MCP handshake. Probes and tool
+// listings get their own subprocess via MCPService.backendTransport.
+// MCPService extends this; it does not replace it.
func (b *baseService) Init(ctx context.Context) error {
switch x := b.backend.(type) {
case *api.RegisterServiceRequest_TargetUrl:
diff --git a/internal/node/stdio_bridge.go b/internal/node/stdio_bridge.go
index 6a72e6b4..1f30f6c7 100644
--- a/internal/node/stdio_bridge.go
+++ b/internal/node/stdio_bridge.go
@@ -16,6 +16,7 @@ package node
import (
"bufio"
+ "context"
"encoding/json"
"io"
"net/http"
@@ -27,9 +28,9 @@ import (
)
// StdioBridge backs the POST HTTP ingress route for a command-backed service
-// (registered via baseService.Init). It is not used for mesh sessions - see
-// MCPService.backendTransport, which gives those their own subprocess
-// instead of sharing this one.
+// (registered via baseService.Init), which is what a mesh caller's
+// /sam/{peer}/mcp/{service} request lands on. Probes and tool listings go
+// through MCPService.backendTransport and a subprocess of their own instead.
//
// One backend process serves every authorized caller, so the bridge owns the
// JSON-RPC id space: each request's id is replaced with a bridge-assigned
@@ -38,6 +39,13 @@ import (
// the same id can no longer receive each other's replies. There is no
// broadcast (SSE) side: with a shared process, a server-initiated message
// cannot be attributed to a caller, so it is not delivered to any of them.
+//
+// Stdio MCP is one session per process, and a server written with the Go or
+// TypeScript SDK refuses a second initialize on it. Every caller opens its
+// own session, so the bridge performs the handshake once, on behalf of the
+// first caller, and answers every later initialize from the backend's reply.
+// What is lost is per-caller capability negotiation: all callers see what the
+// first one negotiated.
type StdioBridge struct {
cmd *exec.Cmd
stdin io.WriteCloser
@@ -54,6 +62,17 @@ type StdioBridge struct {
// the backend is not reading, and the backend may not be reading because
// it is blocked writing stdout, which only deliver (needing mu) drains.
writeMu sync.Mutex
+
+ // handshakeMu guards the three fields below. handshake is the result
+ // object of the backend's initialize reply once one succeeded; while an
+ // initialize is in flight, handshaking is closed when it concludes, so
+ // callers arriving meanwhile wait for it rather than send their own.
+ // initializedSent records that the backend has had its one
+ // notifications/initialized.
+ handshakeMu sync.Mutex
+ handshake json.RawMessage
+ handshaking chan struct{}
+ initializedSent bool
}
type pendingCall struct {
@@ -157,71 +176,188 @@ func (b *StdioBridge) ServeHTTP(w http.ResponseWriter, r *http.Request) {
return
}
originalID, isCall := msg["id"]
+ var method string
+ _ = json.Unmarshal(msg["method"], &method)
- var call *pendingCall
- var toBackend []byte
- if isCall {
- call = &pendingCall{originalID: originalID, reply: make(chan []byte, 1)}
- b.mu.Lock()
- if b.closed {
- b.mu.Unlock()
- http.Error(w, "Backend process is no longer running", http.StatusServiceUnavailable)
+ switch {
+ case isCall && method == "initialize":
+ if cached, forward := b.claimHandshake(r.Context()); !forward {
+ if cached == nil {
+ return
+ }
+ b.writeReply(w, originalID, cached)
return
}
- b.nextID++
- bridgeID := b.nextID
- b.calls[bridgeID] = call
- b.mu.Unlock()
- defer func() {
- b.mu.Lock()
- delete(b.calls, bridgeID)
- b.mu.Unlock()
- }()
-
- msg["id"] = json.RawMessage(strconv.FormatUint(bridgeID, 10))
- toBackend, err = json.Marshal(msg)
- if err != nil {
- http.Error(w, "Failed to encode request", http.StatusInternalServerError)
+ // This caller carries the handshake; whatever the backend answers,
+ // or fails to, settles it for the callers waiting on it.
+ var result json.RawMessage
+ defer func() { b.settleHandshake(result) }()
+ line := b.roundTrip(w, r, msg, originalID)
+ if line == nil {
+ return
+ }
+ var reply struct {
+ Result json.RawMessage `json:"result"`
+ }
+ if json.Unmarshal(line, &reply) == nil && len(reply.Result) > 0 {
+ result = reply.Result
+ }
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusOK)
+ _, _ = w.Write(line)
+ return
+ case !isCall && method == "notifications/initialized":
+ if !b.claimInitialized() {
+ w.WriteHeader(http.StatusAccepted)
return
}
- } else {
- toBackend = body
}
+ if !isCall {
+ if b.writeBackend(w, body) {
+ w.WriteHeader(http.StatusAccepted)
+ }
+ return
+ }
+ if line := b.roundTrip(w, r, msg, originalID); line != nil {
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusOK)
+ _, _ = w.Write(line)
+ }
+}
+
+// claimHandshake decides what an initialize gets: the cached result
+// (cached, false), the right to perform the handshake (nil, true), or
+// nothing because the caller went away while waiting (nil, false).
+func (b *StdioBridge) claimHandshake(ctx context.Context) (cached json.RawMessage, forward bool) {
+ for {
+ b.handshakeMu.Lock()
+ if b.handshake != nil {
+ cached = b.handshake
+ b.handshakeMu.Unlock()
+ return cached, false
+ }
+ inFlight := b.handshaking
+ if inFlight == nil {
+ b.handshaking = make(chan struct{})
+ b.handshakeMu.Unlock()
+ return nil, true
+ }
+ b.handshakeMu.Unlock()
+ select {
+ case <-inFlight:
+ case <-ctx.Done():
+ return nil, false
+ }
+ }
+}
+
+// settleHandshake records the outcome of the handshake in flight and wakes
+// the callers waiting on it. A nil result means it failed: the next caller
+// performs its own.
+func (b *StdioBridge) settleHandshake(result json.RawMessage) {
+ b.handshakeMu.Lock()
+ defer b.handshakeMu.Unlock()
+ if result != nil {
+ b.handshake = result
+ }
+ if b.handshaking != nil {
+ close(b.handshaking)
+ b.handshaking = nil
+ }
+}
+
+// claimInitialized reports whether this notifications/initialized is the
+// one the backend gets.
+func (b *StdioBridge) claimInitialized() bool {
+ b.handshakeMu.Lock()
+ defer b.handshakeMu.Unlock()
+ if b.initializedSent {
+ return false
+ }
+ b.initializedSent = true
+ return true
+}
+
+// writeReply answers a call from the bridge itself, with the caller's id.
+func (b *StdioBridge) writeReply(w http.ResponseWriter, id, result json.RawMessage) {
+ encoded, err := json.Marshal(map[string]json.RawMessage{
+ "jsonrpc": json.RawMessage(`"2.0"`),
+ "id": id,
+ "result": result,
+ })
+ if err != nil {
+ http.Error(w, "Failed to encode reply", http.StatusInternalServerError)
+ return
+ }
+ w.Header().Set("Content-Type", "application/json")
+ w.WriteHeader(http.StatusOK)
+ _, _ = w.Write(encoded)
+}
+
+// writeBackend hands one line to the backend, answering the caller itself
+// when it cannot. It reports whether the line was written.
+func (b *StdioBridge) writeBackend(w http.ResponseWriter, line []byte) bool {
b.mu.Lock()
isClosed := b.closed
b.mu.Unlock()
if isClosed {
http.Error(w, "Backend process is no longer running", http.StatusServiceUnavailable)
- return
+ return false
}
// If the backend closes between the check and the write, the write
// fails or lands in a dead pipe; either way the reader's shutdown has
- // closed call.reply and the select below answers 503.
+ // closed call.reply and roundTrip's select answers 503.
b.writeMu.Lock()
- _, err = b.stdin.Write(append(toBackend, '\n'))
+ _, err := b.stdin.Write(append(line, '\n'))
b.writeMu.Unlock()
if err != nil {
http.Error(w, "Failed to write to process stdin", http.StatusInternalServerError)
- return
+ return false
}
+ return true
+}
- if !isCall {
- w.WriteHeader(http.StatusAccepted)
- return
+// roundTrip sends a call to the backend under a bridge-assigned id and
+// returns the reply with the caller's id restored, or nil after answering
+// the caller with the reason there is none.
+func (b *StdioBridge) roundTrip(w http.ResponseWriter, r *http.Request, msg map[string]json.RawMessage, originalID json.RawMessage) []byte {
+ call := &pendingCall{originalID: originalID, reply: make(chan []byte, 1)}
+ b.mu.Lock()
+ if b.closed {
+ b.mu.Unlock()
+ http.Error(w, "Backend process is no longer running", http.StatusServiceUnavailable)
+ return nil
+ }
+ b.nextID++
+ bridgeID := b.nextID
+ b.calls[bridgeID] = call
+ b.mu.Unlock()
+ defer func() {
+ b.mu.Lock()
+ delete(b.calls, bridgeID)
+ b.mu.Unlock()
+ }()
+
+ msg["id"] = json.RawMessage(strconv.FormatUint(bridgeID, 10))
+ toBackend, err := json.Marshal(msg)
+ if err != nil {
+ http.Error(w, "Failed to encode request", http.StatusInternalServerError)
+ return nil
+ }
+ if !b.writeBackend(w, toBackend) {
+ return nil
}
select {
case <-r.Context().Done():
- return
+ return nil
case line, ok := <-call.reply:
if !ok {
http.Error(w, "Backend process exited before answering", http.StatusServiceUnavailable)
- return
+ return nil
}
- w.Header().Set("Content-Type", "application/json")
- w.WriteHeader(http.StatusOK)
- _, _ = w.Write(line)
+ return line
}
}
diff --git a/internal/node/stdio_bridge_test.go b/internal/node/stdio_bridge_test.go
index 479833d2..e04caa34 100644
--- a/internal/node/stdio_bridge_test.go
+++ b/internal/node/stdio_bridge_test.go
@@ -20,6 +20,7 @@ import (
"io"
"net/http"
"net/http/httptest"
+ "strconv"
"strings"
"sync"
"testing"
@@ -370,3 +371,142 @@ func TestStdioBridge_ServeHTTP_RefusesAfterBackendExit(t *testing.T) {
t.Errorf("POST after exit: status = %d, want 503", rec.Code)
}
}
+
+// post issues one POST to the bridge from its own goroutine and returns the
+// recorder and a channel closed when ServeHTTP returns.
+func post(b *StdioBridge, body string) (*httptest.ResponseRecorder, chan struct{}) {
+ rec := httptest.NewRecorder()
+ done := make(chan struct{})
+ go func() {
+ b.ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/", strings.NewReader(body)))
+ close(done)
+ }()
+ return rec, done
+}
+
+func await(t *testing.T, done chan struct{}) {
+ t.Helper()
+ select {
+ case <-done:
+ case <-time.After(2 * time.Second):
+ t.Fatal("ServeHTTP did not return")
+ }
+}
+
+func replyOf(t *testing.T, rec *httptest.ResponseRecorder) map[string]json.RawMessage {
+ t.Helper()
+ if rec.Code != http.StatusOK {
+ t.Fatalf("status = %d, body %s, want 200", rec.Code, rec.Body.String())
+ }
+ var got map[string]json.RawMessage
+ if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+ t.Fatalf("reply is not JSON: %v", err)
+ }
+ return got
+}
+
+// Stdio MCP is one session per process and a server built with the Go or
+// TypeScript SDK refuses a second initialize on it. Every mesh caller opens
+// its own session against the shared process, so the bridge handshakes once
+// and answers the rest itself, each under its own id; the backend also gets
+// exactly one notifications/initialized.
+func TestStdioBridge_HandshakesOnceForEveryCaller(t *testing.T) {
+ b, stdoutWriter, stdinBuf := newPipeBridge()
+ defer func() { _ = stdoutWriter.Close() }()
+
+ const serverInfo = `{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"strict","version":"1"}}`
+ recA, doneA := post(b, `{"jsonrpc":"2.0","id":"a-1","method":"initialize","params":{}}`)
+ bridgeID := bridgeIDOf(t, stdinBuf, 1)
+ _, _ = stdoutWriter.Write([]byte(`{"jsonrpc":"2.0","id":` + bridgeID + `,"result":` + serverInfo + `}` + "\n"))
+ await(t, doneA)
+ if got := replyOf(t, recA); string(got["id"]) != `"a-1"` || !strings.Contains(string(got["result"]), `"strict"`) {
+ t.Fatalf("first caller got %s", recA.Body.String())
+ }
+
+ recB, doneB := post(b, `{"jsonrpc":"2.0","id":7,"method":"initialize","params":{}}`)
+ await(t, doneB)
+ got := replyOf(t, recB)
+ if string(got["id"]) != `7` {
+ t.Errorf("second caller's reply id = %s, want its own 7", got["id"])
+ }
+ if !strings.Contains(string(got["result"]), `"strict"`) {
+ t.Errorf("second caller's result = %s, want the backend's handshake", got["result"])
+ }
+ if lines := stdinBuf.lines(); len(lines) != 1 {
+ t.Fatalf("backend saw %d lines, want only the first initialize: %q", len(lines), lines)
+ }
+
+ for _, body := range []string{`{"jsonrpc":"2.0","method":"notifications/initialized"}`, `{"jsonrpc":"2.0","method":"notifications/initialized"}`} {
+ rec, done := post(b, body)
+ await(t, done)
+ if rec.Code != http.StatusAccepted {
+ t.Fatalf("notification status = %d, want 202", rec.Code)
+ }
+ }
+ if lines := stdinBuf.lines(); len(lines) != 2 || !strings.Contains(lines[1], "notifications/initialized") {
+ t.Fatalf("backend saw %q, want one initialize and one initialized", lines)
+ }
+
+ // Everything after the handshake still reaches the backend per call.
+ recC, doneC := post(b, `{"jsonrpc":"2.0","id":"c","method":"tools/list"}`)
+ bridgeID = bridgeIDOf(t, stdinBuf, 3)
+ _, _ = stdoutWriter.Write([]byte(`{"jsonrpc":"2.0","id":` + bridgeID + `,"result":{"tools":[]}}` + "\n"))
+ await(t, doneC)
+ if got := replyOf(t, recC); string(got["id"]) != `"c"` {
+ t.Errorf("tools/list reply id = %s, want \"c\"", got["id"])
+ }
+}
+
+// A burst of joiners initializes at the same instant. Only one handshake may
+// reach the backend; the others wait for its outcome instead of racing it.
+func TestStdioBridge_ConcurrentInitializesWaitForTheFirst(t *testing.T) {
+ b, stdoutWriter, stdinBuf := newPipeBridge()
+ defer func() { _ = stdoutWriter.Close() }()
+
+ const callers = 8
+ recs := make([]*httptest.ResponseRecorder, callers)
+ dones := make([]chan struct{}, callers)
+ for i := range callers {
+ recs[i], dones[i] = post(b, `{"jsonrpc":"2.0","id":`+strconv.Itoa(i)+`,"method":"initialize","params":{}}`)
+ }
+ bridgeID := bridgeIDOf(t, stdinBuf, 1)
+ // Give the stragglers time to have sent their own initialize if they were
+ // going to; the backend must still see exactly one.
+ time.Sleep(50 * time.Millisecond)
+ if lines := stdinBuf.lines(); len(lines) != 1 {
+ t.Fatalf("backend saw %d initializes before answering, want 1", len(lines))
+ }
+ _, _ = stdoutWriter.Write([]byte(`{"jsonrpc":"2.0","id":` + bridgeID + `,"result":{"serverInfo":{"name":"s"}}}` + "\n"))
+ for i := range callers {
+ await(t, dones[i])
+ if got := replyOf(t, recs[i]); string(got["id"]) != strconv.Itoa(i) {
+ t.Errorf("caller %d got id %s", i, got["id"])
+ }
+ }
+ if lines := stdinBuf.lines(); len(lines) != 1 {
+ t.Fatalf("backend saw %d lines, want 1", len(lines))
+ }
+}
+
+// A handshake the backend refuses is nobody's handshake: the caller that
+// carried it gets the error, and the next caller performs its own.
+func TestStdioBridge_FailedHandshakeIsNotCached(t *testing.T) {
+ b, stdoutWriter, stdinBuf := newPipeBridge()
+ defer func() { _ = stdoutWriter.Close() }()
+
+ recA, doneA := post(b, `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}`)
+ bridgeID := bridgeIDOf(t, stdinBuf, 1)
+ _, _ = stdoutWriter.Write([]byte(`{"jsonrpc":"2.0","id":` + bridgeID + `,"error":{"code":-32602,"message":"unsupported protocol version"}}` + "\n"))
+ await(t, doneA)
+ if got := replyOf(t, recA); got["error"] == nil {
+ t.Fatalf("first caller got %s, want the backend's error", recA.Body.String())
+ }
+
+ recB, doneB := post(b, `{"jsonrpc":"2.0","id":2,"method":"initialize","params":{}}`)
+ bridgeID = bridgeIDOf(t, stdinBuf, 2)
+ _, _ = stdoutWriter.Write([]byte(`{"jsonrpc":"2.0","id":` + bridgeID + `,"result":{"serverInfo":{"name":"s"}}}` + "\n"))
+ await(t, doneB)
+ if got := replyOf(t, recB); got["result"] == nil {
+ t.Fatalf("second caller got %s, want its own handshake to succeed", recB.Body.String())
+ }
+}