Configuration

mcpgate works out of the box with zero configuration. Use .env and YAML files for advanced setups.

Configuration priority

mcpgate loads configuration from multiple sources. Higher priority overrides lower:

Environment variables / .env — Highest priority. Manual configuration.
/data/gateway.env — Written by the setup wizard. Persists across restarts.
Auto-generated defaults — Secrets generated on first start if not provided.

Core settings

Variable	Description	Required
`BASE_URL`	Public URL where mcpgate is accessible	Wizard or env
`ADMIN_USERS`	Comma-separated admin email addresses	Wizard or env
`COMPANY_DOMAINS`	Allowed email domains (e.g. `@yourcompany.com`)	No (derived from admin email)
`DEFAULT_TIMEZONE`	IANA timezone (default: `Europe/Berlin`)	No

Security

Variable	Description	Auto-generated?
`ENCRYPTION_KEY`	AES-256 key for token encryption (base64)	Yes
`JWT_SECRET`	Secret for signing session tokens	Yes
`REDIS_PASSWORD`	Redis authentication password	Set in docker-compose.yaml

Auto-generated secrets are persisted in /data/gateway.env so they survive container restarts.

SSO / OIDC

Configure your identity provider for team sign-in. Works with any OIDC-compliant provider.

Variable	Description
`OIDC_ISSUER_URL`	Provider's issuer URL (auto-discovers endpoints)
`OIDC_CLIENT_ID`	OAuth client ID from your IdP
`OIDC_CLIENT_SECRET`	OAuth client secret

Provider examples:

# Google
OIDC_ISSUER_URL=https://accounts.google.com

# Microsoft
OIDC_ISSUER_URL=https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0

# Okta
OIDC_ISSUER_URL=https://your-domain.okta.com

Redirect URI: {BASE_URL}/auth/callback

Without OIDC, mcpgate uses broker login (Google/Microsoft via mcpgate.de) — no setup needed.

Branding

White-label the dashboard with your company identity. Configurable via setup wizard or environment variables.

Variable	Description
`BRAND_NAME`	Company name shown in header
`BRAND_COLOR`	Primary accent color (hex)
`BRAND_LOGO_URL`	Logo URL (relative or absolute)
`BRAND_FAVICON_URL`	Favicon URL

Service credentials

Each service requires its own credentials. Configure via the setup wizard or .env. See .env.example in the repository for the complete reference with setup instructions per service.

Service categories

Category	Auth type	Examples
Gateway services	API key / token (shared)	Grafana, Sentry, Jenkins, Home Assistant, Joan
OAuth services	OAuth Client ID/Secret (users connect individually)	Jira, Notion, Figma, GitLab, Slack
Google ecosystem	Google OAuth + SSO	Google Workspace, Grafana (SSO), Metabase (SSO)

YAML extensions

Services are defined in YAML files under modules/. Each file describes actions, auth, and metadata:

service: my_service
extends: false
meta:
  display_name: My Service
  description: What this service does
  icon: /static/images/service-icons/my-service.svg
  brand_color: "#4285f4"
  category: gateway
  setup_fields:
    - env: MY_SERVICE_API_KEY
      label: API Key
      type: password
base_url: https://api.myservice.com/v1
auth:
  type: header
  env_var: MY_SERVICE_API_KEY
  header_name: Authorization
  header_template: "Bearer TOKEN"

actions:
  list_items:
    endpoint: /items
    method: GET
    mode: read
    response:
      transform: items

Place custom extensions in modules/custom/ — they are auto-discovered on startup.

Access control

Configure in config/access_control.yaml:

domains:
  - yourcompany.com
  - subsidiary.com

guests:
  - external.partner@example.com

blocked_services:
  external.partner@example.com:
    - google_workspace
    - slack

Hot-reloadable: curl -X POST http://localhost:8642/admin/reload

Hook configuration

See Hooks for policy and enrichment hook configuration in config/tool_hooks.yaml.