Documentation
¶
Index ¶
- Constants
- Variables
- func GetOrLaunch(l *Launcher, serverID string) (*mcp.Connection, error)
- func GetOrLaunchForSession(l *Launcher, serverID, sessionID string) (*mcp.Connection, error)
- func LogConnectionError(errCtx ConnectionErrorContext, err error)
- type ConnectionErrorContext
- type ConnectionKey
- type ConnectionMetadata
- type ConnectionState
- type HealthMonitor
- type Launcher
- type MountPolicy
- type MountRoot
- type PoolConfig
- type ServerState
- type SessionConnectionPool
- func (p *SessionConnectionPool) Delete(backendID, sessionID string)
- func (p *SessionConnectionPool) Get(backendID, sessionID string) (*mcp.Connection, bool)
- func (p *SessionConnectionPool) GetMetadata(backendID, sessionID string) (*ConnectionMetadata, bool)
- func (p *SessionConnectionPool) List() []ConnectionKey
- func (p *SessionConnectionPool) RecordError(backendID, sessionID string)
- func (p *SessionConnectionPool) Set(backendID, sessionID string, conn *mcp.Connection)
- func (p *SessionConnectionPool) Size() int
- func (p *SessionConnectionPool) Stop()
Constants ¶
const ( // DefaultIdleTimeout is the maximum duration a STDIO-backend connection can remain unused // before being removed from the session pool. Set to 6 hours to accommodate long-running // workflow tasks (e.g. ML training, large builds) that may not make MCP calls for extended // periods. Note: this is distinct from HTTP backend keepalive (config.DefaultKeepaliveInterval) // which keeps the remote session alive on the HTTP server side; STDIO connections run as local // child processes whose sessions are bounded only by this pool eviction window. DefaultIdleTimeout = 6 * time.Hour DefaultCleanupInterval = 5 * time.Minute DefaultMaxErrorCount = 10 )
Default configuration values
const AllowedMountRootsEnvVar = "MCP_GATEWAY_ALLOWED_MOUNT_ROOTS"
AllowedMountRootsEnvVar names the environment variable used by operators to override the trusted host mount roots. The value is a comma-separated list of "path" or "path:ro" / "path:rw" entries (defaults to read-only).
const ( // DefaultHealthCheckInterval is the recommended periodic health check interval (spec §8). DefaultHealthCheckInterval = 30 * time.Second )
Variables ¶
var ErrServerNotFound = errors.New("server not found in config")
ErrServerNotFound is returned by getServerConfig when the requested server ID is not present in the gateway configuration.
Functions ¶
func GetOrLaunch ¶
func GetOrLaunch(l *Launcher, serverID string) (*mcp.Connection, error)
GetOrLaunch returns an existing connection or launches a new one
func GetOrLaunchForSession ¶
func GetOrLaunchForSession(l *Launcher, serverID, sessionID string) (*mcp.Connection, error)
GetOrLaunchForSession returns a session-aware connection or launches a new one This is used for stateful stdio backends that require persistent connections
func LogConnectionError ¶ added in v0.3.26
func LogConnectionError(errCtx ConnectionErrorContext, err error)
LogConnectionError logs detailed diagnostics for a launcher connection failure, including command context, captured stderr, and actionable hints based on the error type and execution environment.
Types ¶
type ConnectionErrorContext ¶ added in v0.3.26
type ConnectionErrorContext struct {
ServerID string
SessionID string
Command string
Args []string
Env map[string]string
RunningInContainer bool
IsDirectCommand bool
StartupTimeout time.Duration
StderrOutput string
}
ConnectionErrorContext holds all context needed to produce a detailed connection failure diagnostic. Fields left at their zero values are omitted from the output.
type ConnectionKey ¶
ConnectionKey uniquely identifies a connection by backend and session
func (ConnectionKey) String ¶
func (k ConnectionKey) String() string
String returns a string representation of the connection key
type ConnectionMetadata ¶
type ConnectionMetadata struct {
Connection *mcp.Connection
CreatedAt time.Time
LastUsedAt time.Time
RequestCount int
ErrorCount int
State ConnectionState
}
ConnectionMetadata tracks information about a pooled connection
type ConnectionState ¶
type ConnectionState string
ConnectionState represents the state of a pooled connection
const ( ConnectionStateActive ConnectionState = "active" ConnectionStateIdle ConnectionState = "idle" ConnectionStateClosed ConnectionState = "closed" )
type HealthMonitor ¶ added in v0.2.12
type HealthMonitor struct {
// contains filtered or unexported fields
}
HealthMonitor periodically checks backend server health and automatically restarts servers that are in an error state (MCP Gateway Specification §8).
func NewHealthMonitor ¶ added in v0.2.12
func NewHealthMonitor(l *Launcher, interval time.Duration) *HealthMonitor
NewHealthMonitor creates a health monitor for the given launcher.
func (*HealthMonitor) Start ¶ added in v0.2.12
func (hm *HealthMonitor) Start()
Start begins periodic health checks in a background goroutine.
func (*HealthMonitor) Stop ¶ added in v0.2.12
func (hm *HealthMonitor) Stop()
Stop signals the health monitor to stop and waits for it to finish.
type Launcher ¶
type Launcher struct {
// contains filtered or unexported fields
}
Launcher manages backend MCP server connections
func (*Launcher) GetServerState ¶ added in v0.2.11
func (l *Launcher) GetServerState(serverID string) ServerState
GetServerState returns the observed runtime state for a single server.
type MountPolicy ¶ added in v0.4.9
type MountPolicy struct {
// Roots is the allowlist of host roots. An empty list denies all mounts.
Roots []MountRoot
}
MountPolicy is the typed configuration boundary that determines which host paths a container-backed MCP server may bind-mount. It is owned by the launcher (the trusted component that starts backend processes) and is never derived from MCP server configuration.
func DefaultMountPolicy ¶ added in v0.4.9
func DefaultMountPolicy() MountPolicy
DefaultMountPolicy builds the default allowlist: the agent workspace (read-only) and the temporary directory root (read-write, used for gateway logs and large payload exchange). Operators may override the allowlist with AllowedMountRootsEnvVar.
func (MountPolicy) ValidateContainerArgs ¶ added in v0.4.9
func (p MountPolicy) ValidateContainerArgs(args []string) error
ValidateContainerArgs validates the container runtime arguments used to launch a backend MCP server. Every bind-mount declaration must satisfy the policy and no policy-bypassing runtime option may be present.
func (MountPolicy) ValidateMount ¶ added in v0.4.9
func (p MountPolicy) ValidateMount(spec string) error
ValidateMount checks a single "source:dest:mode" declaration against the policy.
type MountRoot ¶ added in v0.4.9
type MountRoot struct {
// Path is the host directory root (canonicalized when the policy is built).
Path string
// Writable reports whether "rw" mounts are permitted under this root.
Writable bool
}
MountRoot is a trusted host directory that container-backed MCP servers are permitted to mount from. Writable is an explicit, trusted policy decision: mounts under a root are forced read-only unless the root allows writes.
type PoolConfig ¶
type PoolConfig struct {
IdleTimeout time.Duration
CleanupInterval time.Duration
MaxErrorCount int
}
PoolConfig configures the connection pool
type ServerState ¶ added in v0.2.11
type ServerState struct {
Status string // "running" | "stopped" | "error"
StartedAt time.Time // zero value means never started
LastError string // most recent error message, if any
}
ServerState represents the observed runtime state of a backend server.
type SessionConnectionPool ¶
type SessionConnectionPool struct {
// contains filtered or unexported fields
}
SessionConnectionPool manages connections keyed by (backend, session)
func NewSessionConnectionPool ¶
func NewSessionConnectionPool(ctx context.Context) *SessionConnectionPool
NewSessionConnectionPool creates a new connection pool with default config
func NewSessionConnectionPoolWithConfig ¶
func NewSessionConnectionPoolWithConfig(ctx context.Context, config PoolConfig) *SessionConnectionPool
NewSessionConnectionPoolWithConfig creates a new connection pool with custom config
func (*SessionConnectionPool) Delete ¶
func (p *SessionConnectionPool) Delete(backendID, sessionID string)
Delete removes a connection from the pool
func (*SessionConnectionPool) Get ¶
func (p *SessionConnectionPool) Get(backendID, sessionID string) (*mcp.Connection, bool)
Get retrieves a connection from the pool
func (*SessionConnectionPool) GetMetadata ¶
func (p *SessionConnectionPool) GetMetadata(backendID, sessionID string) (*ConnectionMetadata, bool)
GetMetadata returns metadata for a connection (for testing/monitoring)
func (*SessionConnectionPool) List ¶
func (p *SessionConnectionPool) List() []ConnectionKey
List returns all connection keys in the pool (for monitoring/debugging)
func (*SessionConnectionPool) RecordError ¶
func (p *SessionConnectionPool) RecordError(backendID, sessionID string)
RecordError increments the error count for a connection
func (*SessionConnectionPool) Set ¶
func (p *SessionConnectionPool) Set(backendID, sessionID string, conn *mcp.Connection)
Set adds or updates a connection in the pool
func (*SessionConnectionPool) Size ¶
func (p *SessionConnectionPool) Size() int
Size returns the number of connections in the pool
func (*SessionConnectionPool) Stop ¶
func (p *SessionConnectionPool) Stop()
Stop gracefully shuts down the connection pool