docs: document OIDC auth for HTTP servers and advanced CLI flags

CONTRIBUTING.md

@@ -151,6 +151,24 @@ Or run manually:
 echo '{"mcpServers": {...}}' | ./awmg --config-stdin
 ```
 
+### Advanced Flags
+
+```bash
+# Custom log directory
+./awmg --config config.toml --log-dir /path/to/logs
+
+# Load environment file
+./awmg --config config.toml --env .env
+
+# Increase verbosity
+./awmg --config config.toml -v
+
+# Custom payload directory and size threshold
+./awmg --config config.toml --payload-dir /tmp/payloads --payload-size-threshold 1048576
+```
+
+See [docs/ENVIRONMENT_VARIABLES.md](docs/ENVIRONMENT_VARIABLES.md) for the full list of environment variable overrides.
+
 ### Testing with Codex
 
 You can test MCPG with Codex (in another terminal):

docs/CONFIGURATION.md

@@ -142,6 +142,24 @@ Run `./awmg --help` for full CLI options. Key flags:
 - **`headers`** (optional): HTTP headers to include in requests (for `type: "http"` servers)
   - Map of header name to value (e.g., `{"Authorization": "Bearer token"}`)
 
+- **`auth`** (optional, HTTP servers only): Upstream authentication configuration
+  - Only supported for `type: "http"` servers; using `auth` with stdio servers returns a validation error
+  - Currently supports one `type`:
+    - `"github-oidc"` — Obtains a GitHub Actions OIDC token and attaches it as `Authorization: Bearer <token>` on every request to the HTTP backend. Requires the GitHub Actions job to have `permissions: { id-token: write }`.
+  - **`audience`** (optional): OIDC token audience. Defaults to the server's `url` value.
+  - Tokens are cached per audience and automatically refreshed before expiry.
+  - Example:
+    ```json
+    "my-http-server": {
+      "type": "http",
+      "url": "https://my-internal-mcp.example.com",
+      "auth": {
+        "type": "github-oidc",
+        "audience": "https://my-internal-mcp.example.com"
+      }
+    }
+    ```
+
 - **`tools`** (optional): List of tool names intended to be exposed from this server
   - **Note**: This field is stored but not currently enforced at runtime; all tools from the backend are always exposed regardless of this value
   - Example: `["get_file_contents", "search_code"]`

docs/ENVIRONMENT_VARIABLES.md

@@ -60,6 +60,15 @@ When running `awmg proxy`, these variables configure the upstream GitHub API:
 | `GITHUB_SERVER_URL` | GitHub server URL; proxy auto-derives API endpoint: `*.ghe.com` → `copilot-api.*.ghe.com`, GHES → `<host>/api/v3`, `github.com` → `api.github.com` | (falls back to `api.github.com`) |
 | `GH_TOKEN` / `GITHUB_TOKEN` / `GITHUB_PERSONAL_ACCESS_TOKEN` | GitHub auth token for the proxy to forward requests (checked in priority order) | (required for upstream auth) |
 
+## GitHub Actions OIDC Variables
+
+When any HTTP server uses `auth.type = "github-oidc"`, the gateway reads these environment variables (set automatically by the GitHub Actions runner when `permissions: { id-token: write }` is granted):
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ACTIONS_ID_TOKEN_REQUEST_URL` | GitHub Actions OIDC token endpoint. Required when any HTTP server uses `auth.type = "github-oidc"`. | (set by GitHub Actions) |
+| `ACTIONS_ID_TOKEN_REQUEST_TOKEN` | Bearer token used to authenticate the OIDC token request. Used alongside `ACTIONS_ID_TOKEN_REQUEST_URL`. | (set by GitHub Actions) |
+
 ## DIFC / Guard Policy Configuration
 
 These environment variables configure guard policies (e.g., AllowOnly policies for restricting tool access to specific GitHub repositories):