> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-server-langgraph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables Reference

> This document lists all environment variables used by the MCP Server LangGraph application. - `JWT_SECRET_KEY` (REQUIRED)

This document lists all environment variables used by the MCP Server LangGraph application.

### Required Environment Variables

#### Core Application

* **`JWT_SECRET_KEY`** (REQUIRED)
  * Purpose: Secret key for JWT token signing and validation
  * Type: String (minimum 32 characters recommended)
  * Example: `export JWT_SECRET_KEY="your-secure-secret-key-here"`
  * Used by: Authentication, Authorization, OpenAPI validation
  * Security: ⚠️ **CRITICAL** - Must be kept secret and never committed to version control

#### LLM API Keys

At least one LLM provider API key is required for the agent to function:

* **`ANTHROPIC_API_KEY`**
  * Purpose: API key for Claude models
  * Provider: Anthropic
  * Example: `export ANTHROPIC_API_KEY="sk-ant-..."`

* **`OPENAI_API_KEY`**
  * Purpose: API key for GPT models
  * Provider: OpenAI
  * Example: `export OPENAI_API_KEY="sk-..."`

* **`GOOGLE_API_KEY`**
  * Purpose: API key for Gemini models
  * Provider: Google
  * Example: `export GOOGLE_API_KEY="AIza..."`

#### Authentication & Authorization

* **`KEYCLOAK_CLIENT_SECRET`**
  * Purpose: OAuth client secret for Keycloak SSO integration
  * Type: String
  * Default: None (SSO disabled if not set)
  * Example: `export KEYCLOAK_CLIENT_SECRET="your-keycloak-secret"`

* **`OPENFGA_STORE_ID`**
  * Purpose: OpenFGA store ID for fine-grained authorization
  * Type: UUID string
  * Example: `export OPENFGA_STORE_ID="01H..."`
  * Setup: Run `make setup-openfga` to generate

* **`OPENFGA_MODEL_ID`**
  * Purpose: OpenFGA model ID for authorization rules
  * Type: UUID string
  * Example: `export OPENFGA_MODEL_ID="01H..."`
  * Setup: Run `make setup-openfga` to generate

#### HIPAA Compliance (Optional)

* **`HIPAA_INTEGRITY_SECRET`**
  * Purpose: HMAC secret for data integrity checksums (HIPAA 164.312(c)(1))
  * Type: String (minimum 32 characters)
  * Required: Only if processing Protected Health Information (PHI)
  * Example: `export HIPAA_INTEGRITY_SECRET="your-secure-hipaa-secret"`

#### GDPR/HIPAA/SOC2 Compliance Storage (ADR-0041)

<Warning>
  **Production Critical**: Use PostgreSQL storage backend in production. In-memory storage is for development/testing ONLY and will block GDPR endpoints in production.
</Warning>

* **`GDPR_STORAGE_BACKEND`**
  * Purpose: Storage backend for compliance data (user profiles, preferences, consents, conversations, audit logs)
  * Type: String
  * Values:
    * `postgres` - PostgreSQL storage (production)
    * `memory` - In-memory storage (development/testing only)
  * Default: `memory`
  * Example: `export GDPR_STORAGE_BACKEND="postgres"`
  * Production: **MUST be set to `postgres`**
  * See: [ADR-0041: PostgreSQL GDPR Storage](/architecture/adr-0041-postgresql-gdpr-storage)

* **`GDPR_POSTGRES_URL`**
  * Purpose: PostgreSQL connection string for GDPR compliance data
  * Type: PostgreSQL connection URL
  * Required: Only if `GDPR_STORAGE_BACKEND=postgres`
  * Example: `export GDPR_POSTGRES_URL="postgresql://gdpr_user:secure_pass@db.example.com:5432/gdpr"`
  * Note: Use separate database for compliance data isolation
  * See: [GDPR Storage Configuration](/deployment/gdpr-storage-configuration)

**Retention Requirements**:

* User profiles: Until deletion request (GDPR Article 17)
* Preferences: Until deletion request
* Consents: 7 years (GDPR Article 7, legal requirement)
* Conversations: 90 days (GDPR Article 5(1)(e), configurable)
* Audit logs: 7 years (HIPAA §164.316(b)(2)(i), SOC2 CC6.6)

**Production Guard**: If `GDPR_STORAGE_BACKEND=memory` in production, GDPR endpoints will be blocked to prevent data loss and compliance violations.

### Optional Environment Variables

#### Observability & Monitoring

* **`LANGSMITH_API_KEY`**
  * Purpose: LangSmith tracing and observability
  * Default: Disabled if not set
  * Example: `export LANGSMITH_API_KEY="ls__..."`

* **`LANGSMITH_PROJECT`**
  * Purpose: LangSmith project name
  * Default: "mcp-server-langgraph"
  * Example: `export LANGSMITH_PROJECT="my-project"`

* **`OTEL_EXPORTER_OTLP_ENDPOINT`**
  * Purpose: OpenTelemetry collector endpoint
  * Default: "[http://localhost:4317](http://localhost:4317)"
  * Example: `export OTEL_EXPORTER_OTLP_ENDPOINT="http://jaeger:4317"`

* **`LOG_JSON_INDENT`**
  * Purpose: JSON log indentation for readability
  * Type: Integer
  * Default: None (compact JSON)
  * Example: `export LOG_JSON_INDENT=2`

#### Cloud Provider Integration

##### AWS

* **`AWS_REGION`**
  * Purpose: AWS region for services
  * Example: `export AWS_REGION="us-east-1"`

* **`AWS_ACCESS_KEY_ID`** & **`AWS_SECRET_ACCESS_KEY`**
  * Purpose: AWS credentials
  * Example: `export AWS_ACCESS_KEY_ID="AKIA..."`

##### Google Cloud Platform

* **`GCP_PROJECT_ID`**
  * Purpose: GCP project identifier
  * Example: `export GCP_PROJECT_ID="my-project"`

* **`GOOGLE_APPLICATION_CREDENTIALS`**
  * Purpose: Path to GCP service account key file
  * Example: `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"`

##### Azure

* **`AZURE_MONITOR_CONNECTION_STRING`**
  * Purpose: Azure Monitor connection string
  * Example: `export AZURE_MONITOR_CONNECTION_STRING="InstrumentationKey=..."`

* **`AZURE_MONITOR_INSTRUMENTATION_KEY`**
  * Purpose: Azure Monitor instrumentation key
  * Example: `export AZURE_MONITOR_INSTRUMENTATION_KEY="..."`

#### External Services

##### Elasticsearch

* **`ELASTICSEARCH_USERNAME`** & **`ELASTICSEARCH_PASSWORD`**
  * Purpose: Elasticsearch authentication
  * Example: `export ELASTICSEARCH_USERNAME="elastic"`

* **`ELASTICSEARCH_API_KEY`**
  * Purpose: Elasticsearch API key authentication
  * Example: `export ELASTICSEARCH_API_KEY="..."`

##### Datadog

* **`DATADOG_API_KEY`**
  * Purpose: Datadog monitoring integration
  * Example: `export DATADOG_API_KEY="..."`

##### Splunk

* **`SPLUNK_HEC_TOKEN`** & **`SPLUNK_HEC_ENDPOINT`**
  * Purpose: Splunk HTTP Event Collector
  * Example: `export SPLUNK_HEC_ENDPOINT="https://splunk:8088"`

* **`SPLUNK_ACCESS_TOKEN`** & **`SPLUNK_REALM`**
  * Purpose: Splunk Observability Cloud
  * Example: `export SPLUNK_REALM="us0"`

#### Secrets Management

* **`INFISICAL_TOKEN`**
  * Purpose: Infisical secrets management authentication
  * Default: Falls back to environment variables if not set
  * Example: `export INFISICAL_TOKEN="st.xxx.yyy.zzz"`
  * Note: Application works without Infisical (uses .env fallback)

### Environment Configuration Files

#### Development (.env)

Create a `.env` file in the project root for local development:

```properties theme={null}
## Core (Required)
JWT_SECRET_KEY=development-secret-key-change-in-production

## LLM Provider (at least one required)
ANTHROPIC_API_KEY=sk-ant-your-key-here
## OPENAI_API_KEY=sk-your-key-here
## GOOGLE_API_KEY=your-key-here

## Authentication (Optional)
## KEYCLOAK_CLIENT_SECRET=keycloak-secret
## OPENFGA_STORE_ID=01H...
## OPENFGA_MODEL_ID=01H...

## Observability (Optional)
## LANGSMITH_API_KEY=ls__your-key
LOG_JSON_INDENT=2
```

#### Production

**⚠️ Security Warning**: Never commit `.env` files to version control!

Use one of these approaches for production:

1. **Environment variables** - Set directly in deployment environment
2. **Infisical** - Centralized secrets management (recommended)
3. **Kubernetes Secrets** - For Kubernetes deployments
4. **Cloud provider secrets** - AWS Secrets Manager, GCP Secret Manager, Azure Key Vault

### OpenAPI Schema Validation

To run OpenAPI schema validation locally, you must set:

```bash theme={null}
export JWT_SECRET_KEY="your-secret-key"
```

Then run:

```bash theme={null}
make validate-openapi
```

Or:

```bash theme={null}
python scripts/validation/validate_openapi.py
```

The validation will fail with the following error if `JWT_SECRET_KEY` is not set:

```yaml theme={null}
CRITICAL: JWT secret key not configured. Set JWT_SECRET_KEY environment variable
or configure via Infisical. The service cannot start without a secure secret key.
```

### CI/CD Configuration

GitHub Actions workflows automatically inject required secrets from repository secrets:

* `.github/workflows/ci.yaml` - Main CI pipeline
* `.github/workflows/pr-checks.yaml` - Pull request checks
* `.github/workflows/quality-tests.yaml` - Quality test suite

Required repository secrets:

* `JWT_SECRET_KEY`
* `ANTHROPIC_API_KEY` (for production deployment)
* `KUBECONFIG_PROD` (for Kubernetes deployment)

### Quick Setup

#### Minimal Setup (Development)

```bash theme={null}
## 1. Copy environment template
cp .env.example .env

## 2. Set required variables
export JWT_SECRET_KEY="development-secret-$(openssl rand -hex 16)"
export ANTHROPIC_API_KEY="your-anthropic-key"

## 3. Verify configuration
make test-unit
```

#### Full Setup (with Infrastructure)

```bash theme={null}
## 1. Set core variables
export JWT_SECRET_KEY="$(openssl rand -hex 32)"
export ANTHROPIC_API_KEY="your-anthropic-key"

## 2. Start infrastructure
make dev-setup

## 3. Get OpenFGA IDs from setup output
export OPENFGA_STORE_ID="from-setup-output"
export OPENFGA_MODEL_ID="from-setup-output"

## 4. Run tests
make test
```

### Troubleshooting

#### "JWT\_SECRET\_KEY not configured" error

**Solution**: Set the JWT secret key:

```bash theme={null}
export JWT_SECRET_KEY="$(openssl rand -hex 32)"
```

#### "HIPAA\_INTEGRITY\_SECRET not configured" error

**Solution**: Either:

1. Set the secret: `export HIPAA_INTEGRITY_SECRET="$(openssl rand -hex 32)"`
2. Skip HIPAA tests: `pytest -m "not hipaa"`

#### "No LLM API key found" error

**Solution**: Set at least one LLM provider API key:

```bash theme={null}
export ANTHROPIC_API_KEY="your-key"
## or
export OPENAI_API_KEY="your-key"
## or
export GOOGLE_API_KEY="your-key"
```

### Security Best Practices

1. ✅ **Never commit secrets to version control**
2. ✅ **Use different secrets for dev/staging/prod**
3. ✅ **Rotate secrets regularly (every 90 days)**
4. ✅ **Use strong random values** (minimum 32 characters)
5. ✅ **Restrict secret access** (principle of least privilege)
6. ✅ **Monitor secret usage** (audit logs)
7. ✅ **Use secrets management tools** (Infisical, Vault, cloud providers)

### References

* [Infisical Documentation](https://infisical.com/docs)
* [OpenFGA Setup Guide](/guides/openfga-setup)
* [Keycloak Integration](/guides/keycloak-sso)
* [Environment Setup Guide](/reference/development/ide-setup)