config

Documentation

Overview

Package config defines the gateway configuration schema (YAML for the standalone daemon; hoop later constructs these structs from connection opts).

Index

• type Approvals
• type AuthServer
• type Backend
• type Config
  • func Load(path string) (*Config, error)
  • func (c *Config) EffectivePolicy(backend string) Policy
  • func (c *Config) Validate() error
• type Inbound
• type OAuthClient
• type Optimizer
• type Policy
• type Telemetry
• type ToolOverride

Types

type Approvals

type Approvals struct {
	// Timeout for a pending approval; expiry denies the call. Default 5m.
	Timeout time.Duration `yaml:"timeout,omitempty"`
	// APIToken guards the resolution endpoints (env expansion applies).
	APIToken string `yaml:"api_token,omitempty"`
}

Approvals configures the review workflow.

type AuthServer

type AuthServer struct {
	Issuer string `yaml:"issuer"` // external URL of this gateway
	// Upstream federates login to a company IdP; empty = local users file.
	Upstream *OAuthClient `yaml:"upstream,omitempty"`
	// SigningKeyFile is a PEM EC/RSA key; generated if absent.
	SigningKeyFile string `yaml:"signing_key_file,omitempty"`
	// AccessTokenTTL default 1h.
	AccessTokenTTL time.Duration `yaml:"access_token_ttl,omitempty"`
}

AuthServer configures the embedded OAuth AS.

type Backend

type Backend struct {
	// Transport: "stdio" | "streamable-http".
	Transport string `yaml:"transport"`

	// stdio: command line to spawn. Env expansion applies to Env values.
	Command []string          `yaml:"command,omitempty"`
	Env     map[string]string `yaml:"env,omitempty"`

	// streamable-http: remote endpoint.
	URL     string            `yaml:"url,omitempty"`
	Headers map[string]string `yaml:"headers,omitempty"`

	// Auth selects the outbound token source for remote backends:
	// "none" | "static" (Headers carry it) | "passthrough" | "oauth".
	Auth string `yaml:"auth,omitempty"`

	// OAuth holds manual OAuth client settings. The client discovers empty
	// fields (RFC 9728/8414) and registers itself via DCR (RFC 7591).
	OAuth *OAuthClient `yaml:"oauth,omitempty"`

	// Policy overrides global policy for this backend.
	Policy *Policy `yaml:"policy,omitempty"`
}

Backend describes one MCP server.

type Config

type Config struct {
	Listen string `yaml:"listen"` // e.g. 127.0.0.1:8000

	// Inbound selects how callers authenticate to the gateway.
	Inbound Inbound `yaml:"inbound"`

	// Backends: one entry per MCP server. One backend = plain proxy;
	// several = aggregation (tools prefixed "<name>_").
	Backends map[string]Backend `yaml:"backends"`

	// Policy is the global policy; per-backend Policy overrides fields.
	Policy Policy `yaml:"policy"`

	// Approvals configures the hold-and-review workflow.
	Approvals Approvals `yaml:"approvals"`

	// Telemetry configures OTel/Prometheus.
	Telemetry Telemetry `yaml:"telemetry"`

	// WALDir enables session recording when set: one JSONL file per session.
	WALDir string `yaml:"wal_dir"`

	// AuthServer enables the embedded OAuth authorization server.
	AuthServer *AuthServer `yaml:"auth_server,omitempty"`

	// Optimizer enables semantic tool filtering.
	Optimizer *Optimizer `yaml:"optimizer,omitempty"`
}

Config is the root gateway configuration.

func Load

func Load(path string) (*Config, error)

Load reads and validates a YAML config, expanding ${ENV} references in string values.

func (*Config) EffectivePolicy

func (c *Config) EffectivePolicy(backend string) Policy

EffectivePolicy merges the global policy with a backend override.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks structural invariants.

type Inbound

type Inbound struct {
	// Mode: "anonymous" | "local" | "static" | "oidc" | "github" | "awssts".
	Mode string `yaml:"mode"`

	// Static bearer token (mode=static). Env expansion applies.
	Token string `yaml:"token,omitempty"`

	// OIDC settings (mode=oidc).
	Issuer   string   `yaml:"issuer,omitempty"`
	Audience string   `yaml:"audience,omitempty"`
	Scopes   []string `yaml:"scopes,omitempty"`

	// GitHub settings (mode=github): validate tokens against the GitHub API.
	GitHubAllowedOrgs []string `yaml:"github_allowed_orgs,omitempty"`

	// AWS STS settings (mode=awssts).
	AWSRoleMappings map[string]string `yaml:"aws_role_mappings,omitempty"` // role ARN pattern → subject
}

Inbound authentication modes.

type OAuthClient

type OAuthClient struct {
	Issuer       string   `yaml:"issuer,omitempty"`
	ClientID     string   `yaml:"client_id,omitempty"`
	ClientSecret string   `yaml:"client_secret,omitempty"`
	Scopes       []string `yaml:"scopes,omitempty"`
	// PerUser keys grants by (backend, user) instead of (backend).
	PerUser bool `yaml:"per_user,omitempty"`
	// TokenExchange enables RFC 8693: exchange the inbound subject token
	// for an upstream token instead of running an authorization flow.
	TokenExchange bool `yaml:"token_exchange,omitempty"`
}

OAuthClient is manual outbound OAuth configuration.

type Optimizer

type Optimizer struct {
	// TopK tools exposed per tools/list based on session purpose. 0 = off.
	TopK int `yaml:"top_k"`
	// Purpose feeds the built-in lexical scorer, which matches it against
	// tool name+description. Embedding providers plug in behind the same
	// interface.
	Purpose string `yaml:"purpose,omitempty"`
}

Optimizer configures semantic tool filtering.

type Policy

type Policy struct {
	AllowedTools []string `yaml:"allowed_tools,omitempty"` // globs; empty = all
	DeniedTools  []string `yaml:"denied_tools,omitempty"`  // globs; win over allow

	// ApprovalTools require human approval before execution (globs).
	ApprovalTools []string `yaml:"approval_tools,omitempty"`

	// BlockSampling / BlockElicitation gate server-initiated requests.
	// Default true (deny). nil means unset and resolves to true.
	BlockSampling    *bool `yaml:"block_sampling,omitempty"`
	BlockElicitation *bool `yaml:"block_elicitation,omitempty"`

	// OnRugPull: "kill" (default) | "alert".
	OnRugPull string `yaml:"on_rug_pull,omitempty"`

	// Budgets. Zero = unlimited.
	MaxResultKB     int            `yaml:"max_result_kb,omitempty"`
	MaxCallsPerSess int            `yaml:"max_calls_per_session,omitempty"`
	ToolRateLimits  map[string]int `yaml:"tool_rate_limits,omitempty"` // tool glob → calls/min

	// Overrides rewrite the tool catalog.
	Overrides map[string]ToolOverride `yaml:"overrides,omitempty"` // tool name → override
}

Policy is the inspection policy.

type Telemetry

type Telemetry struct {
	// PrometheusPath exposes /metrics when set (e.g. "/metrics").
	PrometheusPath string `yaml:"prometheus_path,omitempty"`
	// OTLPEndpoint enables trace export when set (host:port, gRPC).
	OTLPEndpoint string `yaml:"otlp_endpoint,omitempty"`
	ServiceName  string `yaml:"service_name,omitempty"`
}

Telemetry configures observability.

type ToolOverride

type ToolOverride struct {
	Name        string `yaml:"name,omitempty"`
	Description string `yaml:"description,omitempty"`
}

ToolOverride renames a tool and/or rewrites its description.