AegisGitea-MCP/docs/configuration.md

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
OAUTH_REDIRECT_ALLOWLIST	No	empty	Additional allowed redirect URIs for OAuth clients

MCP Server Settings

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

Security and Limits

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

Write Mode

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

Automation

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

Legacy Compatibility Variables

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

• GITEA_TOKEN
• MCP_API_KEYS
• AUTH_ENABLED