Configuration

All configuration is done through environment variables. Copy .env.example to .env and set the values before starting the server.

cp .env.example .env

Gitea Settings

Variable	Required	Default	Description
`GITEA_URL`	Yes	—	Base URL of your Gitea instance (e.g. `https://gitea.example.com`)
`GITEA_TOKEN`	Yes	—	API token of the Gitea bot user

The GITEA_TOKEN must be a token belonging to a user that has at least read access to all repositories you want the AI to access. The server validates the token on startup by calling the Gitea /api/v1/user endpoint.

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
`MCP_DOMAIN`	No	—	Public domain name (used for Traefik labels in Docker)
`LOG_LEVEL`	No	`INFO`	Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
`STARTUP_VALIDATE_GITEA`	No	`true`	Validate Gitea token and connectivity at startup via `/api/v1/user`

If startup validation fails with 403 Forbidden, the token is authenticated but lacks permission to access /api/v1/user. Grant the bot user token the required API scope/permissions, or temporarily set STARTUP_VALIDATE_GITEA=false in controlled troubleshooting environments.

Authentication Settings

Variable	Required	Default	Description
`AUTH_ENABLED`	No	`true`	Enable or disable API key authentication
`MCP_API_KEYS`	Yes (if auth enabled)	—	Comma-separated list of valid API keys
`MAX_AUTH_FAILURES`	No	`5`	Number of failed attempts before rate limiting an IP
`AUTH_FAILURE_WINDOW`	No	`300`	Time window in seconds for counting failures

API Key Requirements

Minimum length: 32 characters
Recommended: generate with make generate-key (produces 64-character hex keys)
Multiple keys: separate with commas — useful during key rotation

# Single key
MCP_API_KEYS=abc123...

# Multiple keys (grace period during rotation)
MCP_API_KEYS=newkey123...,oldkey456...

Warning: Setting AUTH_ENABLED=false disables all authentication. Only do this in isolated development environments.

File Access Settings

Variable	Required	Default	Description
`MAX_FILE_SIZE_BYTES`	No	`1048576`	Maximum file size the server will return (bytes). Default: 1 MB
`REQUEST_TIMEOUT_SECONDS`	No	`30`	Timeout for upstream Gitea API calls (seconds)

Audit Logging Settings

Variable	Required	Default	Description
`AUDIT_LOG_PATH`	No	`/var/log/aegis-mcp/audit.log`	Absolute path for the JSON audit log file

The directory is created automatically if it does not exist (requires write permission).

Full Example

# Gitea
GITEA_URL=https://gitea.example.com
GITEA_TOKEN=abcdef1234567890abcdef1234567890

# Server
MCP_HOST=127.0.0.1
MCP_PORT=8080
MCP_DOMAIN=mcp.example.com
LOG_LEVEL=INFO
STARTUP_VALIDATE_GITEA=true

# Auth
AUTH_ENABLED=true
MCP_API_KEYS=a1b2c3d4e5f6...64chars
MAX_AUTH_FAILURES=5
AUTH_FAILURE_WINDOW=300

# Limits
MAX_FILE_SIZE_BYTES=1048576
REQUEST_TIMEOUT_SECONDS=30

# Audit
AUDIT_LOG_PATH=/var/log/aegis-mcp/audit.log

3.3 KiB Raw Blame History