Documentation
¶
Overview ¶
Package streaminghttp implements the MCP streaming HTTP transport. It mounts as a standard net/http handler and provides ordered bidirectional JSON-RPC over long-lived streaming responses (Server-Sent Events style) plus normal request/response for RPC calls initiated by the client.
Responsibilities
- Session creation & validation (via sessions.SessionHost)
- Authentication (pluggable auth.Authenticator; OIDC or manual config)
- Capability discovery (invokes mcpservice.ServerCapabilities getters)
- Ordered outbound event fan-out (progress, listChanged, resource updates)
- Subscription bridging (resources/updated per session + URI)
Construction
h, err := streaminghttp.New(
ctx,
"https://api.example/mcp", // public endpoint base
host, // sessions.SessionHost implementation
server, // mcpservice.ServerCapabilities
authenticator, // auth.Authenticator
// Security metadata inferred from authenticator (implements auth.SecurityDescriptor)
)
Exactly one auth mode must be supplied: discovery or manual OIDC metadata.
Session Context Lifetimes ¶
The handler derives a parent context per session (decoupled from individual HTTP request cancellation) allowing long-lived subscription forwarders to run while individual RPC requests time out or disconnect. Cancellation occurs on explicit session termination or invalidation.
Scaling ¶
Horizontal scale relies on a shared SessionHost. Each node handles any mix of requests; ordering for a given session is preserved by the host's stream semantics, not sticky routing.
Protected Resource Metadata (PRM)
When OIDC discovery or manual metadata is configured, the handler exposes a .well-known/protected-resource-metadata endpoint advertising issuer, jwks_uri and supported authorization parameters, enabling clients to bootstrap without out-of-band configuration.
Error Handling ¶
Transport-level errors map to HTTP status codes; MCP-level errors are serialized as JSON-RPC error responses. Authentication failures surface a WWW-Authenticate challenge per the authorization spec.
Example (mount in net/http):
mux := http.NewServeMux()
mux.Handle("/mcp/", h) // route prefix
http.ListenAndServe(":8080", mux)
Index ¶
Constants ¶
This section is empty.
Variables ¶
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*newConfig)
Option configures the StreamingHTTPHandler.
func WithLogger ¶
WithLogger sets the slog handler used by the server. If not provided, logs are discarded.
func WithRealm ¶ added in v0.7.1
WithRealm sets the HTTP authentication realm advertised in WWW-Authenticate challenges. If empty (default), the realm attribute is omitted entirely per RFC 6750 (it is optional) keeping challenges concise. Provide a short stable token (e.g. "mcp") if you want clients to bucket credentials across multiple handlers.
func WithSecurityConfig ¶ added in v0.7.0
func WithSecurityConfig(sc auth.SecurityConfig) Option
WithSecurityConfig provides a unified security configuration for both advertisement and (if the authenticator supports it) consistency checks.
func WithServerName ¶
WithServerName sets a human-readable server name surfaced in PRM.
func WithVerboseRequestLogging ¶ added in v0.7.5
WithVerboseRequestLogging enables leading/trailing edge logging for each HTTP request that passes through the top-level StreamingHTTPHandler.ServeHTTP. This is off by default to avoid log noise in high-throughput deployments. When enabled, two info logs are emitted per request:
http.req.start (immediately after context enrichment) http.req.end (after downstream handler completes) with duration
type StreamingHTTPHandler ¶
type StreamingHTTPHandler struct {
// contains filtered or unexported fields
}
StreamingHTTPHandler implements the stream HTTP transport protocol of the Model Context Protocol.
func New ¶
func New(ctx context.Context, publicEndpoint string, host sessions.SessionHost, server mcpservice.ServerCapabilities, authenticator auth.Authenticator, opts ...Option) (*StreamingHTTPHandler, error)
New constructs a StreamingHTTPHandler using required formal parameters and optional settings.
Required:
- publicEndpoint: externally visible URL of the MCP endpoint (scheme, host, path)
- host: sessions.SessionHost implementation (horizontal-scale ready)
- server: mcpserver.ServerCapabilities implementation
- authenticator: auth.Authenticator implementation (may also implement auth.SecurityDescriptor)
Authentication configuration resolution order:
- Explicit WithSecurityConfig option (highest precedence)
- authenticator implements auth.SecurityDescriptor (inferred)
If neither produces a security config but an authenticator is supplied, the handler will operate without advertising well-known security metadata. If no authenticator and no security config are provided New returns an error.
func (*StreamingHTTPHandler) ServeHTTP ¶
func (h *StreamingHTTPHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
Source Files