Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
376 changes: 365 additions & 11 deletions internal/api/mcp_conformance_test.go

Large diffs are not rendered by default.

36 changes: 35 additions & 1 deletion internal/api/mcp_policy.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package api

import (
"encoding/json"
"math"
"net"
"net/http"
Expand All @@ -10,7 +11,9 @@ import (
"sync"
"time"

appmcp "github.com/labstack/fanout/internal/mcp"
mcpgoauth "github.com/modelcontextprotocol/go-sdk/auth"
"github.com/modelcontextprotocol/go-sdk/jsonrpc"
"golang.org/x/time/rate"
)

Expand Down Expand Up @@ -107,7 +110,12 @@ func (l *mcpToolLimiter) allow(key mcpToolKey) (bool, int) {
func (l *mcpToolLimiter) protect(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
info := mcpgoauth.TokenInfoFromContext(r.Context())
if info != nil && r.Method == http.MethodPost && r.Header.Get("Mcp-Method") == "tools/call" {
method, _, err := mcpRequestMethodAndName(r)
if err != nil {
appmcp.WriteHTTPMessageError(w, err)
return
}
if info != nil && method == "tools/call" {
client, _ := info.Extra["client_id"].(string)
if allowed, retry := l.allow(mcpToolKey{info.UserID, client}); !allowed {
// MCP 2026-07-28 server/tools#security-considerations requires
Expand All @@ -121,3 +129,29 @@ func (l *mcpToolLimiter) protect(next http.Handler) http.Handler {
next.ServeHTTP(w, r)
})
}

func mcpRequestMethodAndName(r *http.Request) (string, string, error) {
if r.Method != http.MethodPost {
return "", "", nil
}
message, err := appmcp.ReadHTTPMessage(r)
if err != nil {
return "", "", err
}
request, ok := message.(*jsonrpc.Request)
if !ok {
return "", "", nil
}
method, name := r.Header.Get("Mcp-Method"), r.Header.Get("Mcp-Name")
// Initialize selects legacy semantics regardless of headers. Only other
// modern requests have their headers checked against the body by the SDK.
if request.Method != "initialize" && r.Header.Get("MCP-Protocol-Version") >= appmcp.ProtocolVersion && method != "" && (method != "tools/call" || name != "") {
return method, name, nil
}
name = ""
var params map[string]json.RawMessage
if json.Unmarshal(request.Params, &params) == nil {
_ = json.Unmarshal(params["name"], &name)
}
return request.Method, name, nil
}
29 changes: 22 additions & 7 deletions internal/api/oauth.go
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,11 @@ func (h *MCPAuthorization) ProtectMCP(next http.Handler) http.Handler {
next.ServeHTTP(w, r)
return
}
requiredScope := requiredMCPToolScope(r)
requiredScope, err := requiredMCPToolScope(r)
if err != nil {
appmcp.WriteHTTPMessageError(w, err)
return
}
requiredScopes := []string{mcpReadScope}
if requiredScope != "" && requiredScope != mcpReadScope {
requiredScopes = append(requiredScopes, requiredScope)
Expand All @@ -112,6 +116,7 @@ func (h *MCPAuthorization) ProtectMCP(next http.Handler) http.Handler {
})
protected := mcpgoauth.RequireBearerToken(h.verifyMCPToken, &mcpgoauth.RequireBearerTokenOptions{
ResourceMetadataURL: h.metadataURL,
Scopes: []string{mcpReadScope},
})(scopeChecked)
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if !strings.EqualFold(strings.TrimSpace(r.Host), h.allowedHost) {
Expand All @@ -122,13 +127,12 @@ func (h *MCPAuthorization) ProtectMCP(next http.Handler) http.Handler {
})
}

func requiredMCPToolScope(r *http.Request) string {
// HTTPHandler requires the modern protocol; the SDK checks these headers
// against its decoded request before dispatch, including notifications.
if r.Method != http.MethodPost || r.Header.Get("Mcp-Method") != "tools/call" {
return ""
func requiredMCPToolScope(r *http.Request) (string, error) {
method, name, err := mcpRequestMethodAndName(r)
if err != nil || method != "tools/call" {
return "", err
}
return appmcp.RequiredToolScope(r.Header.Get("Mcp-Name"))
return appmcp.RequiredToolScope(name), nil
}

// ProtectBrowserMCP adapts an already-authenticated browser session to the
Expand Down Expand Up @@ -162,6 +166,17 @@ func (h *MCPAuthorization) ProtectBrowserMCP(sessions *appauth.BrowserSessions,
if user == nil {
return echo.NewHTTPError(http.StatusUnauthorized, "not authenticated")
}
if c.Request().Header.Get("MCP-Protocol-Version") < appmcp.ProtocolVersion {
return echo.NewHTTPError(http.StatusBadRequest, "browser MCP requires the modern protocol")
}
method, _, err := mcpRequestMethodAndName(c.Request())
if err != nil {
appmcp.WriteHTTPMessageError(c.Response(), err)
return nil
}
if method == "initialize" {
return echo.NewHTTPError(http.StatusBadRequest, "browser MCP requires the modern protocol")
}
ctx := context.WithValue(c.Request().Context(), browserMCPUserContextKey{}, *user)
request := c.Request().Clone(ctx)
request.Header.Set("Authorization", "Bearer "+browserMCPSessionBearer)
Expand Down
9 changes: 6 additions & 3 deletions internal/api/oauth_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ import (

"github.com/labstack/fanout/internal/auth"
"github.com/labstack/fanout/internal/config"
appmcp "github.com/labstack/fanout/internal/mcp"
appstore "github.com/labstack/fanout/internal/store"
mcpgoauth "github.com/modelcontextprotocol/go-sdk/auth"
)
Expand Down Expand Up @@ -271,9 +272,11 @@ func TestBrowserMCPUsesSessionWithoutWeakeningRemoteMCP(t *testing.T) {
t.Fatalf("browser MCP without CSRF proof = %d %s, want 403", csrfResponse.Code, csrfResponse.Body.String())
}

browser := serve(t, e, http.MethodPost, "/api/mcp", "", map[string]string{
"Authorization": "Bearer attacker-controlled",
"Fanout-Request": "1",
browser := serve(t, e, http.MethodPost, "/api/mcp", `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`, map[string]string{
"Authorization": "Bearer attacker-controlled",
"Fanout-Request": "1",
"MCP-Protocol-Version": appmcp.ProtocolVersion,
"Mcp-Method": "tools/list",
}, cookie)
if browser.Code != http.StatusNoContent {
t.Fatalf("session browser MCP = %d %s", browser.Code, browser.Body.String())
Expand Down
88 changes: 88 additions & 0 deletions internal/mcp/http.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
package mcp

import (
"bytes"
"context"
"errors"
"io"
"net/http"
"sync"
"time"

"github.com/modelcontextprotocol/go-sdk/jsonrpc"
"github.com/modelcontextprotocol/go-sdk/mcp"
)

const (
// Legacy sessions expire after 10 idle minutes; each user/OAuth-client pair
// may keep eight live sessions. Modern requests never enter this accounting.
legacySessionTimeout = 10 * time.Minute
legacySessionLimit = 8
)

// ReadHTTPMessage preserves the body for the SDK and excludes JSON-RPC batches.
func ReadHTTPMessage(r *http.Request) (jsonrpc.Message, error) {
if r.Body == nil {
return nil, io.EOF
}
body, err := io.ReadAll(http.MaxBytesReader(nil, r.Body, mcp.DefaultMaxRequestBodyBytes))
if err != nil {
return nil, err
}
_ = r.Body.Close()
r.Body = io.NopCloser(bytes.NewReader(body))
return jsonrpc.DecodeMessage(body)
}

func WriteHTTPMessageError(w http.ResponseWriter, err error) {
status := http.StatusBadRequest
var tooLarge *http.MaxBytesError
if errors.As(err, &tooLarge) {
status = http.StatusRequestEntityTooLarge
}
http.Error(w, http.StatusText(status), status)
}

func limitLegacySessions(server *mcp.Server) mcp.Middleware {
type principal struct{ user, client string }
var mu sync.Mutex
sessions := make(map[*mcp.ServerSession]principal)
return func(next mcp.MethodHandler) mcp.MethodHandler {
return func(ctx context.Context, method string, req mcp.Request) (mcp.Result, error) {
if method != "initialize" {
return next(ctx, method, req)
}
session, ok := req.GetSession().(*mcp.ServerSession)
extra := req.GetExtra()
if !ok || session == nil || session.ID() == "" || extra == nil || extra.TokenInfo == nil {
return next(ctx, method, req)
}
info := extra.TokenInfo
client, _ := info.Extra["client_id"].(string)
key := principal{info.UserID, client}
mu.Lock()
defer mu.Unlock()
live := make(map[*mcp.ServerSession]bool)
count := 0
for session := range server.Sessions() {
live[session] = true
if owner, exists := sessions[session]; exists && owner == key {
count++
}
}
for session := range sessions {
if !live[session] {
delete(sessions, session)
}
}
if count >= legacySessionLimit {
return nil, &jsonrpc.Error{Code: jsonrpc.CodeInvalidRequest, Message: "legacy session limit exceeded"}
}
result, err := next(ctx, method, req)
if err == nil {
sessions[session] = key
}
return result, err
}
}
}
73 changes: 55 additions & 18 deletions internal/mcp/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ const mcpUIExtension = "io.modelcontextprotocol/ui"

const ProtocolVersion = "2026-07-28"

var supportedProtocolVersions = []string{ProtocolVersion, "2025-11-25", "2025-06-18"}

const staticCatalogTTLMs = 5 * 60 * 1000

const serverInstructions = "Start with get_observability_overview for system health, use get_intelligence_snapshot for the latest precomputed anomalies and log patterns, get_service_topology for direct dependency edges (use this preset once for a service map; do not repeat the same map with query_telemetry), get_service_dependencies for bounded upstream or downstream reachability from a service, get_service_performance for latency, errors and slow operations across HTTP, gRPC and consumers, inspect_trace for one trace, and search_logs for application events. Treat schema, timestamps, provenance, and bounded time windows as authoritative. Dashboard tools are scoped to the authenticated user. For a custom chart in chat, use query_telemetry with one v1 panel; every chart view returns a dashboard fragment rendered by the shared panel renderer. Do not present empty results; state no matching data findings in the answer and prefer the signal a service actually has. Dashboards contain only panels that return data; text panels are exempt. To build a dashboard, read get_telemetry_schema, draft panels, run preview_panels until every non-text panel returns data, then create_dashboard. To change one, get_dashboard first and use edit_dashboard; replace only for a redesign the user asked for."
Expand Down Expand Up @@ -119,7 +121,7 @@ func newServer(queries Observability, dashboards *dashboard.Service, panels *pan
Name: "fanout",
Title: "Fanout Observability",
Version: version,
}, &mcp.ServerOptions{SupportedProtocolVersions: []string{ProtocolVersion}, Instructions: serverInstructions, Capabilities: &mcp.ServerCapabilities{
}, &mcp.ServerOptions{SupportedProtocolVersions: supportedProtocolVersions, Instructions: serverInstructions, Capabilities: &mcp.ServerCapabilities{
Extensions: map[string]any{
mcpUIExtension: map[string]any{"mimeTypes": []string{mcpAppMIME}},
},
Expand All @@ -140,7 +142,7 @@ func newServer(queries Observability, dashboards *dashboard.Service, panels *pan
s.registerPanelTools()
s.registerDashboardTools()
s.registerAppResources()
s.mcp.AddReceivingMiddleware(normalizeToolErrors, recoverToolPanic, addStaticCacheHints, filterMCPAppToolMetadata, s.validateToolArguments)
s.mcp.AddReceivingMiddleware(limitLegacySessions(s.mcp), normalizeToolErrors, recoverToolPanic, addStaticCacheHints, filterMCPAppToolMetadata, s.validateToolArguments)
return s
}

Expand Down Expand Up @@ -276,11 +278,25 @@ func filterMCPAppToolMetadata(next mcp.MethodHandler) mcp.MethodHandler {
func clientSupportsMCPApps(req mcp.Request) bool {
request, ok := req.(interface {
ClientCapabilities() *mcp.ClientCapabilities
ProtocolVersion() string
})
if !ok {
return false
}
capabilities := request.ClientCapabilities()
legacy := request.ProtocolVersion() < ProtocolVersion
if extra := req.GetExtra(); extra != nil && extra.Header != nil {
legacy = extra.Header.Get("MCP-Protocol-Version") < ProtocolVersion
}
// The SDK prefers per-request capabilities even on legacy sessions; their
// declaration belongs to initialize, including when its version negotiated down.
if legacy {
if session, ok := req.GetSession().(*mcp.ServerSession); ok && session != nil {
if initialized := session.InitializeParams(); initialized != nil {
capabilities = initialized.Capabilities
}
}
}
if capabilities == nil {
return false
}
Expand Down Expand Up @@ -312,33 +328,54 @@ func (s *Server) HTTPHandler() http.Handler {
// localhost Host heuristic because a legitimate local reverse proxy connects
// over loopback while preserving the public Host (for example,
// fanout.example.com); the heuristic otherwise rejects every browser MCP App.
handler := mcp.NewStreamableHTTPHandler(
modern := mcp.NewStreamableHTTPHandler(
func(*http.Request) *mcp.Server { return s.mcp },
&mcp.StreamableHTTPOptions{
Stateless: true,
PropagateRequestCancellation: true,
DisableLocalhostProtection: true,
},
)
legacy := mcp.NewStreamableHTTPHandler(
func(*http.Request) *mcp.Server { return s.mcp },
&mcp.StreamableHTTPOptions{
SessionTimeout: legacySessionTimeout,
DisableLocalhostProtection: true,
},
)
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// SDK v1.8 still accepts headerless legacy initialize requests even
// with SupportedProtocolVersions narrowed. Require the modern header
// here and reject legacy versions with the modern error body. Modern
// version negotiation, body mirrors and metadata belong to the SDK.
version := r.Header.Get("MCP-Protocol-Version")
if r.Method == http.MethodPost && version < ProtocolVersion {
data, _ := json.Marshal(mcp.UnsupportedProtocolVersionData{Supported: []string{ProtocolVersion}, Requested: version})
failure := &jsonrpc.Error{Code: mcp.CodeUnsupportedProtocolVersion, Message: "unsupported protocol version", Data: data}
if version == "" {
failure = &jsonrpc.Error{Code: mcp.CodeHeaderMismatch, Message: "MCP-Protocol-Version header is required"}
if r.Method == http.MethodPost {
// The SDK defaults headerless requests to 2025-03-26, which allows
// batches. Decode one message before entering that compatibility path.
message, err := ReadHTTPMessage(r)
if err != nil {
WriteHTTPMessageError(w, err)
return
}
if request, ok := message.(*jsonrpc.Request); ok {
if request.Method == "initialize" {
if r.Header.Get("MCP-Protocol-Version") >= ProtocolVersion {
// Initialize selects legacy semantics; the SDK otherwise
// rejects this header before negotiating the body version.
r = r.Clone(r.Context())
r.Header.Del("MCP-Protocol-Version")
}
legacy.ServeHTTP(w, r)
return
}
var params map[string]json.RawMessage
var meta mcp.Meta
if json.Unmarshal(request.Params, &params) == nil && json.Unmarshal(params["_meta"], &meta) == nil && meta[mcp.MetaKeyProtocolVersion] != nil {
modern.ServeHTTP(w, r)
return
}
}
body, _ := jsonrpc.EncodeMessage(&jsonrpc.Response{Error: failure})
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusBadRequest)
_, _ = w.Write(body)
}
if r.Header.Get("MCP-Protocol-Version") >= ProtocolVersion {
modern.ServeHTTP(w, r)
return
}
handler.ServeHTTP(w, r)
legacy.ServeHTTP(w, r)
})
}

Expand Down
17 changes: 11 additions & 6 deletions site/src/content/docs/guides/connect-over-mcp.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -64,10 +64,15 @@ Use your instance's public URL, then authorize the connection in your browser.

## Protocol

Fanout serves MCP protocol version `2026-07-28` over stateless Streamable
HTTP. Every request carries `MCP-Protocol-Version: 2026-07-28`; a request
without it, or with an earlier version, is rejected, and there are no
sessions or `initialize` handshake. Use a client that supports this version.
Fanout serves modern and legacy MCP clients concurrently over Streamable HTTP
on `/mcp`. Modern `2026-07-28` requests carry per-request metadata and
`MCP-Protocol-Version: 2026-07-28`, with no session or `initialize` handshake.
Legacy clients use `initialize` to negotiate `2025-11-25` or `2025-06-18` and
receive an `Mcp-Session-Id` bound to the authenticated user. Legacy sessions
expire after 10 idle minutes, with at most eight live sessions per user–OAuth
client pair. An expired session or a server restart requires re-initialization.
Versions `2025-03-26` and `2024-11-05` are not served. The browser's `/api/mcp`
route uses only the modern protocol.

On `/mcp` and `/api/mcp`, an `Origin` header must exactly match the RFC 6454
serialization of `FANOUT_PUBLIC_URL`. Malformed or untrusted origins receive
Expand All @@ -76,8 +81,8 @@ origins are accepted. Requests without `Origin` pass this check.

`tools/call` requests are limited to 20 per second per user–OAuth client pair,
with a burst of 100. Excess calls receive `429` with `Retry-After`. The in-process
agent is exempt. Client disconnects cancel in-flight tool calls, including DuckDB
queries.
agent is exempt. Modern client disconnects cancel in-flight tool calls, including
DuckDB queries.

## Scopes

Expand Down
Loading