Documentation
¶
Overview ¶
Package httpsse provides an HTTP proxy implementation for Server-Sent Events (SSE) used in communication between the client and MCP server.
Package httpsse provides MCP ping functionality for HTTP SSE proxies.
Index ¶
- func NewMCPPinger(proxy *HTTPSSEProxy) healthcheck.MCPPinger
- type HTTPSSEProxy
- func (p *HTTPSSEProxy) ForwardResponseToClients(_ context.Context, msg jsonrpc2.Message) error
- func (p *HTTPSSEProxy) GetMessageChannel() chan jsonrpc2.Message
- func (p *HTTPSSEProxy) IsRunning() (bool, error)
- func (p *HTTPSSEProxy) SendMessageToDestination(msg jsonrpc2.Message) error
- func (p *HTTPSSEProxy) Start(_ context.Context) error
- func (p *HTTPSSEProxy) Stop(ctx context.Context) error
- type MCPPinger
- type Option
- type Proxy
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewMCPPinger ¶ added in v0.0.46
func NewMCPPinger(proxy *HTTPSSEProxy) healthcheck.MCPPinger
NewMCPPinger creates a new MCP pinger for HTTP SSE proxies
Types ¶
type HTTPSSEProxy ¶
type HTTPSSEProxy struct {
// contains filtered or unexported fields
}
HTTPSSEProxy encapsulates the HTTP proxy functionality for SSE transports. It provides SSE endpoints and JSON-RPC message handling.
func NewHTTPSSEProxy ¶
func NewHTTPSSEProxy( host string, port int, trustProxyHeaders bool, prometheusHandler http.Handler, middlewares []types.NamedMiddleware, opts ...Option, ) *HTTPSSEProxy
NewHTTPSSEProxy creates a new HTTP SSE proxy for transports.
func (*HTTPSSEProxy) ForwardResponseToClients ¶
ForwardResponseToClients routes one message from the shared backend to the SSE session(s) it belongs to. Every message the backend emits arrives here untagged, so delivery is decided by JSON-RPC shape (see routing.go):
- a *jsonrpc2.Response goes only to the session encoded in its routed ID, with the client's original ID restored (routeResponse);
- a notification is broadcast if it is global, otherwise dropped (routeNotification);
- a server-initiated ping is answered (answerBackendPing); any other server-initiated request is rejected back to the backend (rejectServerRequest).
It never delivers a message to a session that did not originate it.
func (*HTTPSSEProxy) GetMessageChannel ¶
func (p *HTTPSSEProxy) GetMessageChannel() chan jsonrpc2.Message
GetMessageChannel returns the channel for messages to/from the destination.
func (*HTTPSSEProxy) IsRunning ¶ added in v0.9.1
func (p *HTTPSSEProxy) IsRunning() (bool, error)
IsRunning checks if the proxy is running.
func (*HTTPSSEProxy) SendMessageToDestination ¶
func (p *HTTPSSEProxy) SendMessageToDestination(msg jsonrpc2.Message) error
SendMessageToDestination sends a message to the destination via the message channel.
type MCPPinger ¶ added in v0.0.46
type MCPPinger struct {
// contains filtered or unexported fields
}
MCPPinger implements healthcheck.MCPPinger for HTTP SSE proxies
func (*MCPPinger) Ping ¶ added in v0.0.46
Ping sends a JSON-RPC ping request to the MCP server and waits for the response Following the MCP ping specification: https://modelcontextprotocol.io/specification/2025-03-26/basic/utilities/ping
type Option ¶ added in v0.13.0
type Option func(*HTTPSSEProxy)
Option configures an HTTPSSEProxy.
func WithAuthInfoHandler ¶ added in v0.29.2
WithAuthInfoHandler sets the RFC 9728 OAuth protected resource discovery handler. When nil (the default), requests to /.well-known/ return a clean JSON 404.
func WithPrefixHandlers ¶ added in v0.29.2
WithPrefixHandlers sets additional HTTP handlers that are mounted outside the middleware chain, keyed by URL path prefix.
func WithReadTimeout ¶ added in v0.30.0
WithReadTimeout overrides http.Server.ReadTimeout for this proxy, which bounds reading the entire request (headers + body). Zero or negative values are ignored so the constructor's default (defaultReadTimeout) is preserved.
func WithSessionStorage ¶ added in v0.13.0
WithSessionStorage injects a custom storage backend into the session manager. When not provided, the proxy uses in-memory LocalStorage (single-replica default). Provide a Redis-backed storage for multi-replica deployments so all replicas share the same session store.
Architectural note: HTTPSSEProxy is used by StdioTransport for stdio-backed MCP servers. Response routing (ForwardResponseToClients) and POST handling are both local to the instance holding the live SSE connection, so Redis storage enables cross-replica session metadata sharing but does NOT solve cross-replica message delivery — a POST accepted on replica B won't reach a client whose SSE connection is on replica A. Callers must ensure an external load balancer provides session affinity (sticky sessions) when using distributed storage with this proxy.
Prefer Streamable HTTP (ProxyModeStreamableHTTP), also supported on StdioTransport, which does not have this affinity constraint.
Note: response routing and graceful disconnect use a separate in-memory liveSSESessions registry, not the session manager, so any Storage implementation is safe to inject here.
func WithSessionTTL ¶ added in v0.28.0
WithSessionTTL overrides the session inactivity timeout used by this proxy. Zero or negative values are ignored so the constructor's default is preserved.
type Proxy ¶
type Proxy interface {
// Start starts the proxy.
Start(ctx context.Context) error
// Stop stops the proxy.
Stop(ctx context.Context) error
// GetMessageChannel returns the channel for messages to/from the destination.
GetMessageChannel() chan jsonrpc2.Message
// GetResponseChannel returns the channel for receiving messages from the destination.
GetResponseChannel() <-chan jsonrpc2.Message
// SendMessageToDestination sends a message to the destination.
SendMessageToDestination(msg jsonrpc2.Message) error
// ForwardResponseToClients delivers a message from the destination to the
// client session(s) it belongs to. Implementations must never deliver a
// message to a session that did not originate it.
ForwardResponseToClients(ctx context.Context, msg jsonrpc2.Message) error
// SendResponseMessage sends a message to the response channel.
SendResponseMessage(msg jsonrpc2.Message) error
}
Proxy defines the interface for proxying messages between clients and destinations.
Source Files