rpc/mcp, cmd/mcp: add streamable HTTP transport

[AskAlexSharov]

Serve streamable HTTP (the current MCP transport, spec 2025-03-26 — which deprecated SSE) at /mcp on the same listener as the existing SSE endpoints. Applies to both the embedded server (--mcp.addr/--mcp.port, default 127.0.0.1:8553) and the standalone mcp binary (--transport http; sse kept as a deprecated alias). Existing SSE clients keep working unchanged at /sse + /message.

Details:

• MCPTransport.ServeSSE becomes ListenAndServe: one mux-owned http.Server hosts both transports, replacing the WithHTTPServer pre-wiring hack.
• SSE sessions are closed explicitly on shutdown so http.Server.Shutdown does not hang on live event streams.
• The kv.WithNonBlockingAcquire request-context wrap (fail-fast BeginRo) now covers both transports in embedded mode.
• Docs updated; recommended Claude Code setup is now claude mcp add --transport http erigon http://127.0.0.1:8553/mcp.

New tools-level clients can connect with streamable HTTP while nothing changes for current setups.

Verified end-to-end against a live node: initialize → session → tools/call eth_blockNumber over /mcp, and /sse still serving event streams.

[Copilot]

Pull request overview

Adds support for MCP “streamable HTTP” transport served at /mcp while keeping legacy SSE compatibility (/sse + /message) on the same listener, for both embedded MCP (Erigon node) and the standalone mcp binary.

Changes:

• Replace the previous SSE-only serving entrypoint with a single HTTP server/mux that hosts both streamable HTTP (/mcp) and SSE (/sse + /message).
• Update embedded node startup + standalone CLI (--transport http, with sse as a deprecated alias) to use the new unified HTTP transport.
• Update docs and add a transport-level test validating both endpoints are served from one port.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
rpc/mcp/transport_test.go	New test verifying /mcp (streamable HTTP) and /sse are both served from ListenAndServe.
rpc/mcp/standalone.go	Renames/rewires standalone HTTP serving entrypoint to ListenAndServe.
rpc/mcp/mcp.go	Updates transport interface; implements unified serveHTTP mux that serves both transports and applies request-context wrapping.
rpc/mcp/mcp_test.go	Removes the old SSE-handler wiring test superseded by the new combined-transport test.
node/eth/backend.go	Embedded MCP now starts via ListenAndServe and logs both endpoints.
docs/site/docs/fundamentals/mcp.mdx	Docs updated to recommend streamable HTTP at /mcp, with SSE kept for older clients.
cmd/mcp/main.go	Adds --transport http (and keeps sse as deprecated alias), updates help text and serving path.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

rpc/mcp/mcp.go:1015

• In serveHTTP's ctx-cancel shutdown path, an httpServer.Shutdown error is silently ignored (the function may return nil even if shutdown timed out/failed). That makes shutdown failures invisible to callers and can mask hung connections.

		sse.CloseSessions()
		if err := httpServer.Shutdown(shutdownCtx); err != nil {
			_ = httpServer.Close()
		}

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

rpc/mcp/mcp.go:1021

• In the ctx-cancel shutdown path, any error returned by httpServer.Shutdown is currently dropped (it only triggers a Close). This can mask real shutdown failures (e.g. context deadline exceeded) and make diagnosing stuck connections harder. Return the shutdown error after joining the serve goroutine (unless it’s ErrServerClosed).

		shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
		defer cancel()
		sse.CloseSessions()
		if err := httpServer.Shutdown(shutdownCtx); err != nil {
			_ = httpServer.Close()
		}
		// Join the serve goroutine; this also surfaces a bind/serve error
		// that raced with the cancellation instead of dropping it.
		if err := <-errCh; err != nil && !errors.Is(err, http.ErrServerClosed) {
			return err
		}
		return nil

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

rpc/mcp/mcp.go:1020

• In the ctx-cancellation shutdown path, the error from httpServer.Shutdown is ignored. If Shutdown times out or otherwise fails, serveHTTP can still return nil (e.g., if the serve goroutine returns http.ErrServerClosed), which masks an unsuccessful/partial shutdown and makes callers think the server stopped cleanly.

		if err := httpServer.Shutdown(shutdownCtx); err != nil {
			_ = httpServer.Close()
		}