Unified Configuration Parameter Reference¶

Created: 2026-05-10 Status: Living document — update on every PR that adds, renames, or removes a configuration parameter. See also configuration.md for full parameter semantics.

Purpose¶

The MCP Gateway Registry is configured identically across three deployment surfaces. The same logical parameter carries a different name, lives in a different file, and is verified with a different command depending on how you deploy. This document maps every parameter across all three surfaces so that:

• Operators can find the right variable name for their deployment.
• Reviewers can confirm a new parameter was wired through all three surfaces.
• The naming drift between SCREAMING_SNAKE_CASE, snake_case, and camelCase is visible and intentional, not accidental.

The Three Deployment Surfaces¶

Verifying configuration via the API¶

The registry already exposes a configuration dump endpoint — we do not need to build one for this effort:

These endpoints are the authoritative source for what the running registry actually sees — always use them to verify before filing a "config not applied" bug.

Current limitation: Bearer token does not work on /api/config/full or /api/config/export (2026-05-10)¶

Verified against a deployed registry (https://<registry-host>) using a signed JWT from the "Generate JWT Token" UI flow (a self-signed admin token with is_admin=true, the same token family registry_management.py uses):

Root cause: the 401 text matches the session-cookie-only helpers in registry/auth/dependencies.py:30,74 (get_current_user and get_user_session_data), not the 403 "Admin access required" that the handler itself would raise. That means the Depends(enhanced_auth) chain for these two endpoints resolves into a cookie-session-only path on this deployment and never reaches the is_admin check.

Workarounds for now: - Use the UI at Settings → System Config → Configuration (logged in as admin via browser). - Or curl -b cookies.txt after logging into the UI and saving the session cookie. - Or hit /api/config (works with Bearer) for the subset of fields exposed there.

Cookie-based curl attempt (2026-05-10). Retested with a manually captured mcp_gateway_session cookie (1,737 bytes, Starlette-signed). nginx returned HTTP 401 with WWW-Authenticate: Bearer, meaning the auth-server's /validate rejected the cookie via validate_session_cookie() (auth_server/server.py:630). Most likely causes: cookie expired, SECRET_KEY rotated since the cookie was issued, or the cookie was issued on a different host. Net effect: even the documented cookie-only path is brittle for out-of-band testing — browser session is the only reliable path right now.

Follow-up work: /api/config/full and /api/config/export should accept Bearer JWTs for admin callers too. The fix is in registry/auth/dependencies.py — widen the enhanced_auth path so Bearer admin tokens are accepted on these endpoints. Separate issue to be filed once we confirm intent (some deployments may deliberately keep these cookie-only as defense-in-depth).

How to read the tables¶

Each logical-group table has columns:

Conventions: - A blank cell means the parameter is not configurable on that surface — either it is deployment-specific (e.g. CloudFront only applies to ECS) or the wiring is missing (flag this in a PR). - — in Purpose means the parameter mirrors the row directly above. - Secrets/sensitive values are flagged with (secret) — these must use AWS Secrets Manager (Terraform) or existingSecret / secretKeyRef (Helm), never plain values in version control.

Group 1 — Registry Identity & Card¶

Registry metadata used for federation, discovery, and the header UI.

Group 2 — Deployment Mode & UI Visibility¶

Controls registry-vs-gateway integration and which tabs render in the UI. See configuration.md#deployment-mode-configuration.

Group 3 — Auth Server URLs & JWT¶

Internal and external URLs for the auth server, plus internal JWT signing.

Group 4 — Gateway Host Configuration¶

Affects only with-gateway deployments (nginx reverse proxy).

Group 5 — Registry API Auth (Static Tokens)¶

Enterprise-perimeter auth for registry APIs without full IdP validation. See docs/registry-api-auth.md.

Group 6 — Registration Webhook (Issue #742)¶

Fire-and-forget POST on register/delete.

Group 7 — Registration Gate / Admission Control (Issue #809)¶

Fail-closed external approval of registrations.

Group 7a — Agent Batch API (Issue #956)¶

Async batch register/patch/replace/delete for agent cards, drained by an in-process worker. Helm renders these into the registry-batch-config ConfigMap (non-secret).

Group 8 — Federation (Peer Registries)¶

Static-token and OAuth2 config for peer-to-peer federation.

Group 9 — Workday ASOR Federation¶

Single URL; disables itself when unset.

Group 10 — AWS Agent Registry Federation¶

Group 11 — M2M Direct Client Registration (Issue #851)¶

Group 12 — Auth Provider Selection¶

Per-server Connect overrides¶

These live on the server entry (registration form / server JSON), not in global config, and are surfaced through GET /api/servers/{path}/connect-config to shape that server's Connect dialog:

12a — Keycloak¶

12b — Amazon Cognito¶

12c — Microsoft Entra ID¶

12d — Okta¶

12e — Auth0¶

12f — GitHub / Google OAuth Apps (login, not SKILL.md fetching)¶

Group 13 — Session Cookie Security¶

Group 13a — Tool-level Access Enforcement (Issue #1026)¶

Controls the per-user tool allowlist filter applied at the registry REST endpoints and the MCP tools/list JSON-RPC response. The allowlist is resolved from the mcp-scopes collection used by existing server-level access checks. All three values are non-sensitive.

Group 13b — Custom Entity Types¶

Admin-defined, schema-driven catalog types (catalog-only; never proxied or executed). These are registry-only — the auth-server does not read them. All three values are non-sensitive. When the Main switch is off (default) the dynamic tabs and /api/custom* endpoints are not registered, so there is no behavior change.

Group 13c — Update Check (Admin Banner, Issue #1218)¶

Background poll of the GitHub Releases API that surfaces a newer registry version in an admin-only banner (GET /api/system/update-check). Registry-only and non-sensitive. Fail-silent (never affects registry operation, so it is air-gap safe) and skipped on dev/local builds (a plain docker compose up has BUILD_VERSION unset; build_and_run.sh sets it to a non-semver git-describe string that the version parser skips). Set the enable flag to false for air-gapped clusters or to silence the banner.

Group 14 — GitHub Private Repo Access (for SKILL.md fetching)¶

Only the Helm mcpgw subchart and Docker expose these today.

Group 15 — Storage Backend¶

Group 16 — AI / LLM¶

Group 17 — MCP Server Security Scanning¶

Group 18 — A2A Agent Security Scanning¶

Group 19 — Skill Security Scanning¶

Group 20 — Embeddings / Vector Search¶

Used by registry and mcpgw services.

Group 20a — Registration Deduplication¶

Advisory check that surfaces likely-duplicate servers when a user registers a new one. Reuses the embedding model from Group 20 — the query embedder and the persisted-corpus embedder must be the same model for cosine scores to be meaningful. Used by the registry service only. Path uniqueness remains the only hard rule; this feature is purely advisory and never blocks registration.

Weights must sum to 1.0 ± 0.001 or the registry process refuses to start (validated in Settings).

Group 21 — ANS (Agent Naming Service)¶

Group 22 — External Registry Tags¶

Group 23 — MCPGW Server (MCP Gateway server component)¶

Group 24 — Audit & Application Logging¶

Group 25 — OTLP / OpenTelemetry Export¶

Group 26 — Grafana / Observability Pipeline¶

Group 27 — Anonymous Usage Telemetry¶

Group 28 — AgentCore Token Refresher¶

OAuth per-client-id secrets. These are dynamic and named after the client_id.

Group 29 — Container Registry Credentials (CI only)¶

Used only by the publish workflow; not by the running registry.

Group 29 — Extra Environment Variable Injection (Issue #1000)¶

User-supplied environment variables passed to the registry, auth-server, and mcpgw containers in addition to the chart-managed variables. Each surface enforces a reserved-name list so users cannot override chart-managed values; the canonical list lives in charts/<subchart>/reserved-env-names.txt and is the shared source of truth across all three surfaces.

Reserved names (shared across all three surfaces): - charts/registry/reserved-env-names.txt - charts/auth-server/reserved-env-names.txt - charts/mcpgw/reserved-env-names.txt

Collision enforcement per surface: - Docker / Docker Compose: build_and_run.sh runs validate_extra_env preflight on every start; rejects reserved-name collisions with the exact file and line number. - Terraform / ECS: terraform plan uses a validation block on each *_extra_env variable that reads the same reserved-env-names.txt via file() and rejects reserved names with contains(). - Helm: registry.validateExtraEnv / auth-server.validateExtraEnv / mcpgw.validateExtraEnv helpers in _helpers.tpl fail helm template/install with a clear error if a reserved name is supplied via extraEnv.

Secret handling: For production secrets, prefer Kubernetes extraEnvFrom (Helm) or AWS Secrets Manager ARNs wired into the task definition's secrets block (Terraform; see mongodb_connection_string_secret_arn as a reference pattern) rather than passing plaintext values via *_extra_env. The extra_env/*.env files on the Docker surface are plaintext on disk and should not be used for production secrets.

Group 30 — Infrastructure-Only (Terraform and Helm) Parameters¶

These have no .env equivalent because they describe the infrastructure, not the running registry.

Terraform / ECS infrastructure¶

Helm / chart-only¶

Checklist for new parameters¶

When you add a new configuration parameter:

• Add to .env.example with description and default.
• Wire through docker-compose.yml (and .podman.yml, .prebuilt.yml, .dhi.yml) service env blocks.
• Add Terraform variable in terraform/aws-ecs/variables.tf, pass through main.tf and the module, map to ECS task env in modules/mcp-gateway/ecs-services.tf, and document in terraform.tfvars.example.
• Add Helm values default in charts/<subchart>/values.yaml AND the stack charts/mcp-gateway-registry-stack/values.yaml; wire into the subchart's templates/deployment.yaml and (if sensitive) templates/secret.yaml.
• Register the field in registry/api/config_routes.py CONFIG_GROUPS so it appears on Settings → System Config and in GET /api/config/full. Mark sensitive values with is_sensitive=True.
• Add a new row to the appropriate group in this file. If it belongs in a brand-new group, add a new group section. Confirmed by reviewer before merge.

If one of the three surfaces legitimately does not apply, leave the cell blank and explain in the PR description — do not silently omit.