Skip to content

Agent Mesh

node: serve MCP stateless

Tomas Tormoa0896afd5b11
diff --git a/internal/node/mcp.go b/internal/node/mcp.go
index de44fa25..6b1ee90c 100644
--- a/internal/node/mcp.go
+++ b/internal/node/mcp.go
@@ -148,13 +148,18 @@ func NewUnauthenticatedMCPServer(controlPlaneURL string) *mcp.Server {
return mcpServer
}
+// MCP 2026-07-28 removed sessions, and the SDK serves it over HTTP only in
+// stateless mode; a stateful server also refuses legacy clients that already
+// send the new per-request _meta version tag.
+var streamableOptions = &mcp.StreamableHTTPOptions{Stateless: true}
+
// NewUnauthenticatedMCPHandler creates an HTTP handler for the unauthenticated MCP server.
func NewUnauthenticatedMCPHandler(controlPlaneURL string) http.Handler {
mcpServer := NewUnauthenticatedMCPServer(controlPlaneURL)
streamableHandler := mcp.NewStreamableHTTPHandler(func(request *http.Request) *mcp.Server {
return mcpServer
- }, nil)
+ }, streamableOptions)
mux := http.NewServeMux()
mux.Handle("/mcp", streamableHandler)
@@ -171,10 +176,10 @@ func NewMCPHandler(node *SamNode) http.Handler {
// Per agent, not per node: the SDK gives a tool handler the session's
// context rather than the request's, so the only place to bind who the
- // session belongs to is where the session's server is chosen.
+ // request belongs to is where its server is chosen.
streamableHandler := mcp.NewStreamableHTTPHandler(func(request *http.Request) *mcp.Server {
return servers.forAgent(agentFromLocalGateway(request))
- }, nil)
+ }, streamableOptions)
mux := http.NewServeMux()
mux.Handle("/mcp", streamableHandler)
diff --git a/internal/node/mcp_handlers_test.go b/internal/node/mcp_handlers_test.go
index ade4e0de..207602eb 100644
--- a/internal/node/mcp_handlers_test.go
+++ b/internal/node/mcp_handlers_test.go
@@ -830,6 +830,35 @@ func TestNewMCPHandler_RegistersFindRemoteTools(t *testing.T) {
}
}
+// A legacy-version client that also sends the 2026-07-28 per-request _meta
+// tag must be served, not refused as a new-protocol request; a stateful SDK
+// handler answers it with -32022.
+func TestNewMCPHandler_AcceptsLegacyRequestWithProtocolVersionMeta(t *testing.T) {
+ srv := httptest.NewServer(NewMCPHandler(&SamNode{BiscuitTimeout: 500 * time.Millisecond}))
+ defer srv.Close()
+
+ body := `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"tc","version":"0.0.1"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2025-11-25"}}}`
+ req, err := http.NewRequest(http.MethodPost, srv.URL+"/mcp", strings.NewReader(body))
+ if err != nil {
+ t.Fatal(err)
+ }
+ req.Header.Set("Content-Type", "application/json")
+ req.Header.Set("Accept", "application/json, text/event-stream")
+ req.Header.Set("Mcp-Protocol-Version", "2025-11-25")
+ resp, err := http.DefaultClient.Do(req)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer func() { _ = resp.Body.Close() }()
+ out, _ := io.ReadAll(resp.Body)
+ if resp.StatusCode != http.StatusOK || !strings.Contains(string(out), `"protocolVersion":"2025-11-25"`) {
+ t.Fatalf("initialize with _meta protocol version tag: status %d body %s", resp.StatusCode, out)
+ }
+ if resp.Header.Get("Mcp-Session-Id") != "" {
+ t.Errorf("stateless handler must not issue Mcp-Session-Id, got %q", resp.Header.Get("Mcp-Session-Id"))
+ }
+}
+
func TestHandleDescribeRemoteTool_EmptyPeerID(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
diff --git a/internal/node/mcp_test.go b/internal/node/mcp_test.go
index 41dfbf63..4447d40c 100644
--- a/internal/node/mcp_test.go
+++ b/internal/node/mcp_test.go
@@ -70,8 +70,9 @@ func TestMCPHandler_HTTP(t *testing.T) {
}
defer func() { _ = resp2.Body.Close() }()
- if resp2.StatusCode != http.StatusOK && resp2.StatusCode != http.StatusBadRequest {
- t.Errorf("Expected status OK or BadRequest on /mcp, got %d", resp2.StatusCode)
+ // Stateless servers have no standalone SSE stream; the spec reserves 405 for that.
+ if resp2.StatusCode != http.StatusMethodNotAllowed {
+ t.Errorf("Expected status MethodNotAllowed on GET /mcp, got %d", resp2.StatusCode)
}
}
diff --git a/site/content/docs/reference/node-api.md b/site/content/docs/reference/node-api.md
index a937a09e..071a59e9 100644
--- a/site/content/docs/reference/node-api.md
+++ b/site/content/docs/reference/node-api.md
@@ -30,7 +30,7 @@ proxy path does not accept it there.
|---|---|---|
| `GET /healthz`, `GET /readyz` | none | `200` while the process is up. Every other route except `/debug/*` answers `503` until the node is connected to the mesh, so a `503` on `/mcp` is the practical readiness signal. |
| `GET /metrics` | token | Prometheus metrics (`sam_node_*`). |
-| `POST /mcp` | token | The MCP server (Streamable HTTP). `/` is an alias. |
+| `POST /mcp` | token | The MCP server (Streamable HTTP, sessionless: no `Mcp-Session-Id`, `GET` answers `405`). `/` is an alias. |
| `GET /v1/models` | token | Models served by every reachable inference provider. |
| `POST /v1/chat/completions`, `POST /v1/completions` | token | OpenAI-compatible inference, routed to a provider of the requested model. |
| `GET /sam/service/discover` | token | Discover services on the mesh. |