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

# Authentication

> Setting up FRED API access and security

# Authentication

Access to the FRED API requires a free API key. This guide covers how to obtain and configure your API key securely.

## Getting an API Key

### Registration Process

<Steps>
  <Step title="Create Account">
    Visit [FRED API Registration](https://fredaccount.stlouisfed.org/apikeys) and create a free account
  </Step>

  <Step title="Request API Key">
    Click "Request API Key" and fill out the brief application form
  </Step>

  <Step title="Instant Approval">
    Your API key will be generated immediately and displayed on screen
  </Step>

  <Step title="Save Securely">
    Store your key securely - you'll need it for configuration
  </Step>
</Steps>

<Note>
  API keys are **completely free** with no usage fees. Rate limits apply but are generous for most use cases.
</Note>

### API Key Format

Keys are 32-character alphanumeric strings:

```
a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
```

## Configuration

### Environment Variables (Recommended)

The most secure method is using environment variables.

<Tabs>
  <Tab title="Claude Desktop (macOS)">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "fred": {
          "command": "npx",
          "args": ["-y", "fred-mcp-server"],
          "env": {
            "FRED_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop (Windows)">
    Edit `%APPDATA%\Claude\claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "fred": {
          "command": "npx",
          "args": ["-y", "fred-mcp-server"],
          "env": {
            "FRED_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="System Environment">
    Add to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):

    ```bash theme={null}
    export FRED_API_KEY="your-api-key-here"
    ```

    Then restart your terminal or run:

    ```bash theme={null}
    source ~/.bashrc  # or ~/.zshrc
    ```
  </Tab>

  <Tab title=".env File">
    Create `.env` file in your project directory:

    ```bash theme={null}
    FRED_API_KEY=your-api-key-here
    ```

    <Warning>
      Add `.env` to `.gitignore` to prevent committing secrets
    </Warning>
  </Tab>
</Tabs>

### Verification

Test your configuration:

```bash theme={null}
# Using the MCP server directly
FRED_API_KEY=your-key npx fred-mcp-server

# Or if set in environment
npx fred-mcp-server
```

The server should start without errors. If you see authentication errors, verify your key is correct.

## Security Best Practices

### Key Protection

<AccordionGroup>
  <Accordion title="Never Commit Keys">
    ❌ Don't:

    ```json theme={null}
    // config.json
    {
      "api_key": "a1b2c3d4e5f6g7h8..."
    }
    ```

    ✅ Do:

    ```json theme={null}
    // config.json (use environment variables)
    {
      "api_key": "${FRED_API_KEY}"
    }
    ```
  </Accordion>

  <Accordion title="Restrict File Permissions">
    Limit who can read configuration files:

    ```bash theme={null}
    chmod 600 ~/.claude/config.json
    chmod 600 .env
    ```
  </Accordion>

  <Accordion title="Use Separate Keys">
    Create different keys for:

    * Development environments
    * Production systems
    * Different applications

    This allows selective revocation if needed.
  </Accordion>

  <Accordion title="Regular Rotation">
    Periodically generate new keys and update your configuration
  </Accordion>
</AccordionGroup>

### Access Control

The FRED MCP Server never:

* Logs API keys
* Exposes keys in responses
* Stores keys persistently
* Transmits keys except to FRED API

Keys are only used for authenticated requests to `api.stlouisfed.org`.

## Rate Limits

FRED API implements rate limiting to ensure fair usage.

### Current Limits

| Limit Type          | Restriction | Notes                      |
| ------------------- | ----------- | -------------------------- |
| Requests per Minute | 120         | Across all endpoints       |
| Series Observations | 40/min      | Specific to data retrieval |
| Daily Requests      | Varies      | Based on account tier      |

### Handling Rate Limits

The MCP server implements automatic handling:

<CodeGroup>
  ```javascript Retry Logic theme={null}
  {
    maxRetries: 3,
    backoffMultiplier: 2,
    initialDelay: 1000 // ms
  }
  ```

  ```javascript Rate Limit Response theme={null}
  {
    "error": {
      "code": 429,
      "message": "Too Many Requests",
      "retryAfter": 60 // seconds
    }
  }
  ```
</CodeGroup>

### Best Practices

<Steps>
  <Step title="Batch Requests">
    Group related queries to minimize API calls
  </Step>

  <Step title="Use Date Ranges">
    Request only the time periods you need
  </Step>

  <Step title="Avoid Unnecessary Requests">
    Plan queries carefully to minimize redundant API calls
  </Step>

  <Step title="Off-Peak Usage">
    Schedule heavy queries during off-peak hours
  </Step>
</Steps>

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Authentication Failed (401)">
    **Symptoms:** "Bad Request. The value for variable api\_key is not registered."

    **Solutions:**

    * Verify API key is correct (check for typos)
    * Ensure environment variable is set
    * Restart the MCP server after changing config
    * Check key hasn't been revoked
  </Accordion>

  <Accordion title="Rate Limited (429)">
    **Symptoms:** "Too many requests"

    **Solutions:**

    * Wait 60 seconds before retrying
    * Reduce request frequency
    * Use date ranges to limit data size
    * Use fewer concurrent requests
  </Accordion>

  <Accordion title="Environment Variable Not Found">
    **Symptoms:** Server starts but requests fail

    **Solutions:**

    * Check variable name is exactly `FRED_API_KEY`
    * Verify it's set in the correct profile file
    * Restart terminal/application after setting
    * Use absolute paths in configuration
  </Accordion>

  <Accordion title="Invalid Response Format">
    **Symptoms:** JSON parsing errors

    **Solutions:**

    * Verify API key format (32 hex characters)
    * Check for special characters in key
    * Ensure no whitespace in environment variable
  </Accordion>
</AccordionGroup>

### Debug Mode

Enable detailed logging:

```bash theme={null}
DEBUG=fred:* npx fred-mcp-server
```

This shows:

* Request URLs (with key redacted)
* Response status codes
* Rate limit status
* Error details

## Key Management

### Regenerating Keys

If your key is compromised:

<Steps>
  <Step title="Login to FRED Account">
    Visit your [API Keys page](https://fredaccount.stlouisfed.org/apikeys)
  </Step>

  <Step title="Revoke Old Key">
    Click "Delete" next to the compromised key
  </Step>

  <Step title="Generate New Key">
    Click "Request API Key" to create a replacement
  </Step>

  <Step title="Update Configuration">
    Replace the old key in all your configurations
  </Step>

  <Step title="Restart Services">
    Restart MCP server and any dependent applications
  </Step>
</Steps>

### Multiple Keys

You can have multiple API keys:

```json theme={null}
{
  "mcpServers": {
    "fred-dev": {
      "command": "npx",
      "args": ["-y", "fred-mcp-server"],
      "env": {
        "FRED_API_KEY": "development-key"
      }
    },
    "fred-prod": {
      "command": "npx",
      "args": ["-y", "fred-mcp-server"],
      "env": {
        "FRED_API_KEY": "production-key"
      }
    }
  }
}
```

## Terms of Use

By using the FRED API, you agree to:

<CardGroup cols={2}>
  <Card title="Attribution" icon="quote-left">
    Credit Federal Reserve Bank of St. Louis and FRED
  </Card>

  <Card title="Non-Commercial" icon="hand-holding-dollar">
    Free for research, education, and personal use
  </Card>

  <Card title="No Resale" icon="ban">
    Don't redistribute raw data commercially
  </Card>

  <Card title="Respect Limits" icon="gauge-high">
    Adhere to rate limits and usage guidelines
  </Card>
</CardGroup>

<Info>
  For commercial use or higher limits, contact the [FRED team](mailto:stlsFRED@stls.frb.org) directly.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Start using the MCP server
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/overview">
    Explore available tools
  </Card>

  <Card title="Examples" icon="code" href="/examples/basic-usage">
    See usage examples
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/resources/troubleshooting">
    Get help with issues
  </Card>
</CardGroup>