Configuration

Copy .env.example to .env and set values before starting:

cp .env.example .env

OAuth/OIDC Settings (Primary)

Variable	Required	Default	Description
`GITEA_URL`	Yes	-	Base URL of your Gitea instance
`OAUTH_MODE`	No	`false`	Enables OAuth-oriented validation settings
`GITEA_OAUTH_CLIENT_ID`	Yes when `OAUTH_MODE=true`	-	OAuth client id
`GITEA_OAUTH_CLIENT_SECRET`	Yes when `OAUTH_MODE=true`	-	OAuth client secret
`OAUTH_EXPECTED_AUDIENCE`	No	empty	Additional accepted JWT audience beyond the MCP resource and Gitea client id
`OAUTH_CACHE_TTL_SECONDS`	No	`300`	OIDC discovery/JWKS cache TTL
`OAUTH_STATE_SECRET`	Yes when `OAUTH_MODE=true`	-	HMAC secret for signed OAuth state wrappers; must be at least 32 characters (e.g. `openssl rand -hex 32`)
`OAUTH_REDIRECT_ALLOWLIST`	No	empty	Additional allowed redirect URIs for OAuth clients

Variable	Required	Default	Description
`MCP_HOST`	No	`127.0.0.1`	Interface to bind to
`MCP_PORT`	No	`8080`	Port to listen on
`PUBLIC_BASE_URL`	No	empty	Public HTTPS base URL advertised in OAuth metadata (recommended behind reverse proxy)
`ALLOW_INSECURE_BIND`	No	`false`	Explicit opt-in required for `0.0.0.0` bind
`LOG_LEVEL`	No	`INFO`	`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
`STARTUP_VALIDATE_GITEA`	No	`true`	Validate OIDC discovery endpoint at startup
`DCR_ENABLED`	No	`true`	Enable dynamic client registration at `/register`
`DCR_STORAGE_PATH`	No	`/var/lib/aegis-mcp/dcr_clients.json`	Persisted OAuth client registry path. Written with owner-only (`0o600`) permissions on POSIX hosts

Variable	Required	Default	Description
`MAX_AUTH_FAILURES`	No	`5`	Failed auth attempts before rate limiting
`AUTH_FAILURE_WINDOW`	No	`300`	Window in seconds for auth failure counting
`RATE_LIMIT_PER_MINUTE`	No	`60`	Per-IP request limit
`TOKEN_RATE_LIMIT_PER_MINUTE`	No	`120`	Per-token request limit
`MAX_FILE_SIZE_BYTES`	No	`1048576`	Max file payload returned by read tools
`MAX_TOOL_RESPONSE_ITEMS`	No	`200`	Max list items in tool responses
`MAX_TOOL_RESPONSE_CHARS`	No	`20000`	Max chars in text fields
`REQUEST_TIMEOUT_SECONDS`	No	`30`	Upstream timeout for Gitea calls
`SECRET_DETECTION_MODE`	No	`mask`	`off`, `mask`, `block`
`REPO_AUTHZ_CACHE_TTL_SECONDS`	No	`60`	TTL for cached per-user repository permission checks

Variable	Required	Default	Description
`WRITE_MODE`	No	`false`	Enables write tools
`WRITE_REPOSITORY_WHITELIST`	Required if write mode enabled and allow-all disabled	empty	Comma-separated `owner/repo` allow list
`WRITE_ALLOW_ALL_TOKEN_REPOS`	No	`false`	Allow all repos accessible by token

Variable	Required	Default	Description
`AUTOMATION_ENABLED`	No	`false`	Enables automation endpoints
`AUTOMATION_SCHEDULER_ENABLED`	No	`false`	Enables scheduler loop
`AUTOMATION_STALE_DAYS`	No	`30`	Age threshold for stale issue checks

These are retained for compatibility but not used for OAuth-protected MCP tool execution:

Start

Operating

Internals

Security

Reference

Generated from the docs/ directory. Edit the docs, not the wiki, then re-run the wiki sync.