docs: explain why GET /api/mcp deliberately answers 405 in stateless mode

2026-09-08 14:07:54 +00:00
parent aedc388535
commit a0b5565a63
4 changed files with 30 additions and 5 deletions
@@ -25,6 +25,15 @@ func callerFromContext(c *gin.Context) Caller {
 // Handler serves the MCP endpoint. It is stateless: no session resumption, each
 // request self-contained, which is what lets it sit behind ordinary request
 // middleware with no special casing.
+//
+// Stateless mode also means this handler is POST-only in practice: the SDK's
+// StreamableHTTPHandler hardcodes a 405 for GET whenever Stateless is true,
+// because a stateless server has no session to open the server-to-client SSE
+// stream against. The GET route is still registered deliberately (see
+// handlers.go) so a client probing for the endpoint sees a protocol-correct
+// 405 rather than gin's 404 — the MCP spec expects exactly that response from
+// a server that does not offer the GET/SSE leg. Nothing here should route GET
+// requests differently or try to make them do anything else.
 func Handler() gin.HandlerFunc {
 	return func(c *gin.Context) {
 		caller := callerFromContext(c)