Configuration

This guide covers all configuration options for the FRED MCP Server, including environment variables, client setup, and advanced settings.

Environment Variables

The FRED MCP Server uses environment variables for configuration. These can be set in your client configuration or system environment.

Required Variables

FRED_API_KEY

string

required

Your FRED API key from the Federal Reserve Bank of St. Louis.How to obtain:

Visit fred.stlouisfed.org/docs/api/api_key.html
Register for a free account
Request an API key (instant approval)

Never commit your API key to version control. Use environment variables or secure key management.

Optional Variables

FRED_BASE_URL

string

default:"https://api.stlouisfed.org/fred"

Override the FRED API base URL. Useful for:

Using proxy servers
Testing with mock services
Enterprise deployments with custom endpoints

LOG_LEVEL

string

default:"info"

Control the verbosity of server logs.Options:

debug: Detailed debugging information
info: General information messages
warn: Warning messages only
error: Error messages only

MAX_RETRIES

number

default:"3"

Maximum number of retry attempts for failed API requests.

TIMEOUT_MS

number

default:"30000"

Request timeout in milliseconds (default: 30 seconds).

Client Configurations

Claude Desktop

Basic Configuration
Advanced Configuration
Multiple Instances

{
  "mcpServers": {
    "fred-mcp": {
      "command": "fred-mcp-server",
      "env": {
        "FRED_API_KEY": "your_api_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "fred-mcp": {
      "command": "fred-mcp-server",
      "env": {
        "FRED_API_KEY": "your_api_key_here",
        "LOG_LEVEL": "debug",
        "MAX_RETRIES": "5",
        "TIMEOUT_MS": "60000"
      }
    }
  }
}

{
  "mcpServers": {
    "fred-production": {
      "command": "fred-mcp-server",
      "env": {
        "FRED_API_KEY": "production_key"
      }
    },
    "fred-development": {
      "command": "fred-mcp-server",
      "env": {
        "FRED_API_KEY": "development_key",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Docker Configuration

Docker Run Configuration

docker run -i --rm \
  -e FRED_API_KEY="your_api_key" \
  -e LOG_LEVEL="info" \
  -e MAX_RETRIES="3" \
  -e TIMEOUT_MS="30000" \
  stefanoamorelli/fred-mcp-server:latest

Docker Compose Configuration

version: '3.8'

services:
  fred-mcp:
    image: stefanoamorelli/fred-mcp-server:latest
    environment:
      - FRED_API_KEY=${FRED_API_KEY}
      - LOG_LEVEL=info
      - MAX_RETRIES=3
      - TIMEOUT_MS=30000
    stdin_open: true
    tty: false

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: fred-mcp-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: fred-mcp
  template:
    metadata:
      labels:
        app: fred-mcp
    spec:
      containers:
      - name: fred-mcp
        image: stefanoamorelli/fred-mcp-server:latest
        env:
        - name: FRED_API_KEY
          valueFrom:
            secretKeyRef:
              name: fred-secrets
              key: api-key
        - name: LOG_LEVEL
          value: "info"

Security Best Practices

API Key Management

Never expose your FRED API key in public repositories, logs, or client-side code.

Environment Files
Secret Managers
CI/CD Secrets

Use .env files with proper gitignore:

# .env
FRED_API_KEY=your_secure_key_here

# .gitignore
.env
.env.local
.env.*.local

Load in your application:

require('dotenv').config();
const apiKey = process.env.FRED_API_KEY;

Use platform-specific secret managers:AWS Secrets Manager:

const AWS = require('aws-sdk');
const client = new AWS.SecretsManager();

const secret = await client.getSecretValue({
  SecretId: "fred-api-key"
}).promise();

Azure Key Vault:

const { SecretClient } = require("@azure/keyvault-secrets");
const client = new SecretClient(vaultUrl, credential);
const secret = await client.getSecret("fred-api-key");

Configure in your CI/CD pipeline:GitHub Actions:

steps:
  - name: Run FRED MCP
    env:
      FRED_API_KEY: ${{ secrets.FRED_API_KEY }}
    run: |
      fred-mcp-server

GitLab CI:

variables:
  FRED_API_KEY: $FRED_API_KEY  # Set in GitLab settings

Network Security

Firewall Configuration

If running as a service, restrict network access:

# iptables example
iptables -A INPUT -p tcp --dport 3000 -s 127.0.0.1 -j ACCEPT
iptables -A INPUT -p tcp --dport 3000 -j DROP

TLS/SSL Configuration

For production deployments with HTTP transport:

// Use with reverse proxy (recommended)
// nginx.conf
server {
  listen 443 ssl;
  ssl_certificate /path/to/cert.pem;
  ssl_certificate_key /path/to/key.pem;

  location /fred-mcp {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
  }
}

Performance Optimization

Rate Limiting

FRED API has rate limits that you must respect:

Default FRED API limits:

120 requests per minute
40 requests per minute for series observations

RATE_LIMIT_REQUESTS

number

default:"100"

Maximum requests per minute

RATE_LIMIT_BACKOFF

boolean

default:"true"

Enable exponential backoff on rate limit errors

Logging Configuration

Log Formats

JSON Logging
Text Logging

export LOG_FORMAT="json"
export LOG_LEVEL="info"

# Output:
# {"timestamp":"2025-01-20T10:30:45Z","level":"info","message":"Server started"}

export LOG_FORMAT="text"
export LOG_LEVEL="debug"

# Output:
# 2025-01-20 10:30:45 [INFO] Server started
# 2025-01-20 10:30:46 [DEBUG] Processing request...

Log Destinations

File Logging

# Redirect to file
fred-mcp-server > /var/log/fred-mcp.log 2>&1

# With rotation
fred-mcp-server | rotatelogs /var/log/fred-mcp-%Y%m%d.log 86400

Syslog Integration

# Send to syslog
fred-mcp-server | logger -t fred-mcp -p local0.info

Development Configuration

Local Development

Create Development Config

// .claude/dev-config.json
{
  "mcpServers": {
    "fred-dev": {
      "command": "node",
      "args": ["./build/index.js"],
      "cwd": "/path/to/fred-mcp-server",
      "env": {
        "FRED_API_KEY": "dev_key",
        "LOG_LEVEL": "debug",
        "NODE_ENV": "development"
      }
    }
  }
}

Set Development Variables

# .env.development
FRED_API_KEY=your_dev_key
LOG_LEVEL=debug
NODE_ENV=development

Run Development Server

# Load dev environment and run
source .env.development
npm run start

Testing Configuration

// jest.config.js
module.exports = {
  testEnvironment: 'node',
  setupFiles: ['./test/setup.js'],
  env: {
    FRED_API_KEY: 'test_key',
    FRED_BASE_URL: 'http://localhost:3001/mock-fred',
    LOG_LEVEL: 'error'
  }
};

# Start mock FRED server for testing
docker run -d -p 3001:3001 \
  -e MOCK_MODE=true \
  fred-mock-server

// test/setup.ts
process.env.FRED_API_KEY = 'test_key';
process.env.LOG_LEVEL = 'error';
process.env.NODE_ENV = 'test';

Monitoring & Alerts

Health Checks

Configure health monitoring:

HEALTH_CHECK_ENABLED

boolean

default:"false"

Enable health check endpoint

HEALTH_CHECK_INTERVAL

number

default:"60000"

Health check interval in milliseconds

Metrics Collection

Prometheus Metrics

// Enable metrics collection
export METRICS_ENABLED=true
export METRICS_PORT=9090

// Prometheus config
scrape_configs:
  - job_name: 'fred-mcp'
    static_configs:
      - targets: ['localhost:9090']

Custom Metrics

// Track custom metrics
export TRACK_USAGE=true
export USAGE_REPORT_INTERVAL=3600000  // 1 hour

Troubleshooting Configuration

Debug Mode

Enable comprehensive debugging:

# Maximum debugging
export LOG_LEVEL=debug
export DEBUG=fred:*
export NODE_DEBUG=mcp
export TRACE_REQUESTS=true

fred-mcp-server

Common Issues

Configuration not loading

Symptoms: Default values used instead of configured valuesSolutions:

Check JSON syntax in config file
Verify environment variable names (case-sensitive)
Ensure config file is saved
Restart client application

Permission errors

Symptoms: Cannot read/write configurationSolutions:

# Fix permissions
chmod 600 ~/.config/claude/claude_desktop_config.json
chown $USER:$USER ~/.config/claude/claude_desktop_config.json

Environment variables not set

Symptoms: API key not found errorsCheck variables:

# Linux/Mac
echo $FRED_API_KEY
env | grep FRED

# Windows
echo %FRED_API_KEY%
set | findstr FRED

Next Steps

API Reference

Explore available tools and parameters

Examples

See configuration in action

Troubleshooting

Solve common configuration issues

Security

Security best practices

​Configuration

​Environment Variables

​Required Variables

​Optional Variables

​Client Configurations

​Claude Desktop

​Docker Configuration

​Security Best Practices

​API Key Management

​Network Security

​Performance Optimization

​Rate Limiting

​Logging Configuration

​Log Formats

​Log Destinations

​Development Configuration

​Local Development

​Testing Configuration

​Monitoring & Alerts

​Health Checks

​Metrics Collection

​Troubleshooting Configuration

​Debug Mode

​Common Issues

​Next Steps

API Reference

Examples

Troubleshooting

Security

Configuration

Environment Variables

Required Variables

Optional Variables

Client Configurations

Claude Desktop

Docker Configuration

Security Best Practices

API Key Management

Network Security

Performance Optimization

Rate Limiting

Logging Configuration

Log Formats

Log Destinations

Development Configuration

Local Development

Testing Configuration

Monitoring & Alerts

Health Checks

Metrics Collection

Troubleshooting Configuration

Debug Mode

Common Issues

Next Steps