126 lines
8.3 KiB
Markdown
126 lines
8.3 KiB
Markdown
# Configuration
|
|
|
|
All settings are environment variables. They are read case-insensitively from the process
|
|
environment and from an env file (the environment always wins). Unknown variables are ignored.
|
|
A blank value (`KEY=` in the env file) counts as unset for the optional secrets, URLs and
|
|
paths. List values accept commas or whitespace as separators.
|
|
|
|
## Which env file is read
|
|
|
|
The env file is never trusted just because it sits in the working directory: MCP clients start
|
|
stdio servers inside the project they work on, which can be a cloned repository carrying a
|
|
planted `.env` that switches off secret masking or the audit log or points `GITEA_URL` at
|
|
another host. The file is chosen in this order:
|
|
|
|
1. `--env-file PATH` of `serve` (and `setup`): used as given. It must exist and be a regular
|
|
file.
|
|
2. The `AEGIS_ENV_FILE` environment variable: same rules.
|
|
3. `./.env`, but only when it is a regular file (not a symlink), owned by the user running the
|
|
server, with no group or other permissions (mode 0600, which `setup` writes). Otherwise it is
|
|
ignored and one warning goes to stderr that says why and how to fix it:
|
|
`chmod 600 .env`, or pass `--env-file`.
|
|
|
|
Real environment variables take precedence over every file. A missing `./.env` is silent.
|
|
Containers pass settings as environment variables (`env_file:` in compose), not through the
|
|
working directory.
|
|
|
|
`.env.example` is the annotated template. `uv run aegis-gitea-mcp setup` fills one in for you
|
|
(see [getting-started.md](getting-started.md)). Secret settings never appear in logs, errors or
|
|
`repr` output.
|
|
|
|
Requirements that depend on how the server is started are checked at start, not on import:
|
|
`GITEA_TOKEN` for stdio, authentication for a non-loopback HTTP bind, complete OAuth settings
|
|
when OAuth is on.
|
|
|
|
## Gitea
|
|
|
|
| Variable | Default | Rules |
|
|
|---|---|---|
|
|
| `GITEA_URL` | required | `http` or `https`, must have a host, no credentials, query or fragment. A trailing `/api/v1` is removed. |
|
|
| `GITEA_TOKEN` | unset | Token for stdio and for admin-token mode on HTTP. Its scopes bound what the server can do. Required for stdio (exit code 2 without it). |
|
|
|
|
## Transport
|
|
|
|
| Variable | Default | Rules |
|
|
|---|---|---|
|
|
| `MCP_TRANSPORT` | `stdio` | `stdio` or `http`. `serve --transport` overrides it. |
|
|
| `MCP_HOST` | `127.0.0.1` | Bind address for HTTP. A non-loopback value refuses to start unless HTTP auth is configured. |
|
|
| `MCP_PORT` | `8080` | 1 to 65535. |
|
|
| `MCP_PATH` | `/mcp` | Starts with a single `/`, no query, spaces or trailing slash, not just `/`. |
|
|
| `MCP_BEARER_TOKEN` | unset | Static bearer token for HTTP (admin identity). At least 32 characters. Generate with `openssl rand -hex 32`. |
|
|
| `PUBLIC_BASE_URL` | unset | Public URL behind a reverse proxy. Same URL rules as `GITEA_URL`, and `https` unless the host is loopback. Required for OAuth. |
|
|
| `ALLOWED_HOSTS` | empty | Extra `Host` header values accepted behind a proxy. The loopback names with the port and the host of `PUBLIC_BASE_URL` are always allowed. Other `Host` values are rejected (DNS-rebinding protection). A non-loopback `MCP_HOST` with neither `PUBLIC_BASE_URL` nor `ALLOWED_HOSTS` logs a startup warning on stderr, because remote clients then get 421. |
|
|
| `FORWARDED_ALLOW_IPS` | `127.0.0.1` | Comma list of IP addresses or networks (or `*`) whose `X-Forwarded-For` and `X-Forwarded-Proto` headers are trusted. Set it to the address of the reverse proxy when it is not on the same host, for example a Docker network. Otherwise the per-IP rate limit sees the proxy address for every client. `*` trusts every peer and logs a warning: only use it when the port is reachable solely from the proxy, since clients could otherwise spoof their IP. |
|
|
|
|
## Per-user OAuth (HTTP only)
|
|
|
|
| Variable | Default | Rules |
|
|
|---|---|---|
|
|
| `OAUTH_ENABLED` | `false` | When true, the four settings below are required, or the server refuses to start (exit code 2, with the list of what is missing). |
|
|
| `GITEA_OAUTH_CLIENT_ID` | unset | Client id of the Gitea OAuth application (created by `setup`). |
|
|
| `GITEA_OAUTH_CLIENT_SECRET` | unset | Its client secret. |
|
|
| `TOKEN_ENCRYPTION_KEY` | unset | At least 32 characters. Encrypts stored user tokens. Losing it invalidates every stored login. |
|
|
| `OAUTH_SCOPES` | all `write:<category>` scopes | Granular Gitea scopes only (`read:` or `write:` plus activitypub, admin, issue, misc, notification, organization, package, repository, user). Anything else is rejected, because Gitea grants full access for unknown scope strings. Must not be empty. |
|
|
|
|
| `OAUTH_REDIRECT_ALLOWLIST` | empty | Comma list of redirect URIs MCP clients may register: exact URIs (`https://client.example/cb`) or prefixes ending in `/` that allow a whole host (`https://claude.ai/`). A bare origin without a path is refused. Empty accepts any https URI (and http on `localhost`, `127.0.0.1`, `[::1]`). With a list, https URIs must match it; loopback URIs stay allowed for native clients. Checked at registration and again at `/authorize`. |
|
|
|
|
`PUBLIC_BASE_URL` is also required for OAuth. The Gitea OAuth application's redirect URI is
|
|
`<PUBLIC_BASE_URL>/oauth/callback`.
|
|
|
|
## State
|
|
|
|
| Variable | Default | Rules |
|
|
|---|---|---|
|
|
| `DATA_DIR` | `~/.local/state/aegis-gitea-mcp` (`/var/lib/aegis-mcp` in the image) | `~` is expanded. Holds the token store (`oauth-tokens.json`, mode 0600) and the audit log. |
|
|
| `AUDIT_LOG_PATH` | `DATA_DIR/audit.log` | Path of the hash-chained audit log. See [audit-logging.md](audit-logging.md). The server opens it for append at startup and exits with code 2 and a message on stderr when it cannot. |
|
|
|
|
## Tool exposure
|
|
|
|
Everything is enabled by default. These settings only narrow it. A filtered tool is neither
|
|
listed nor callable.
|
|
|
|
| Variable | Default | Rules |
|
|
|---|---|---|
|
|
| `READ_ONLY` | `false` | Expose only read-only (GET) operations. `gitea_api_request` stays listed but accepts only GET. |
|
|
| `TOOLSETS` | `all` | Comma separated domains: `admin`, `repo`, `issue`, `pull`, `release`, `wiki`, `org`, `team`, `user`, `actions`, `hook`, `package`, `notification`, `misc`, or `all`. Unknown domains are rejected. `gitea_api_request` belongs to `misc`. |
|
|
| `DISABLED_TOOLS` | empty | Exact tool names to hide, lowercased on load. An unknown name is a startup error that lists the bad names. |
|
|
|
|
## Limits and safety
|
|
|
|
| Variable | Default | Rules |
|
|
|---|---|---|
|
|
| `REQUEST_TIMEOUT_SECONDS` | `30` | 1 to 600. Timeout of each Gitea request. |
|
|
| `MAX_TOOL_RESPONSE_ITEMS` | `200` | At least 1. Longer lists are cut and reported in `truncated`. |
|
|
| `MAX_TOOL_RESPONSE_CHARS` | `60000` | At least 1. Upper bound of one serialized result. |
|
|
| `MAX_BINARY_BYTES` | `5242880` | At least 1. Larger binary bodies fail with `payload_too_large`. |
|
|
| `SECRET_DETECTION_MODE` | `mask` | `off`, `mask` or `block`. See below. |
|
|
| `LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` or `CRITICAL`. Logs go to stderr. |
|
|
| `EXPOSE_ERROR_DETAILS` | `false` | When true, the exception class name is added to internal and transport errors. Never a stack trace. Do not enable in production. |
|
|
| `RATE_LIMIT_PER_MINUTE` | `120` | At least 1. Per client on the HTTP MCP endpoint, keyed by a hash of the Authorization header, else the client IP. Excess requests get 429. Only the first rejected request per client and minute is written to the audit log. Tracking is in memory and bounded (idle clients are forgotten). |
|
|
|
|
Secret detection: `mask` replaces secret-like strings in results with a placeholder, `block`
|
|
withholds a whole result that contains one (`secret_blocked`), `off` disables pattern matching.
|
|
The server's own tokens (Gitea token, bearer token, OAuth client secret, the calling user's
|
|
token) and secret values you submit in a request body are always redacted by exact match. The
|
|
tools that exist to return a new credential (create token, runner registration token, OAuth
|
|
application, deploy token) are exempt from pattern masking so the credential stays usable.
|
|
|
|
## Profiles
|
|
|
|
Read-only assistant for issues and code:
|
|
|
|
```bash
|
|
READ_ONLY=true
|
|
TOOLSETS=repo,issue,pull,release,wiki
|
|
```
|
|
|
|
Everything except instance administration and credentials:
|
|
|
|
```bash
|
|
TOOLSETS=repo,issue,pull,release,wiki,org,team,hook,actions,package,notification,misc
|
|
DISABLED_TOOLS=gitea_user_create_token
|
|
```
|
|
|
|
(`gitea_user_create_token` must be a registered name, see [tools.md](tools.md); the server
|
|
refuses to start if a name in `DISABLED_TOOLS` does not exist.)
|