> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peacock.support/llms.txt
> Use this file to discover all available pages before exploring further.

# How Zoom MCP Server manages and refreshes your token

> The Zoom MCP Server monitors your OAuth access token and automatically refreshes it before it expires, keeping your connection to Zoom uninterrupted.

Zoom Server-to-Server OAuth tokens expire after one hour. The Zoom MCP Server handles this for you: it monitors your token continuously, displays its status in the terminal every 60 seconds, and automatically fetches a new token when expiration is approaching. Under normal conditions, you do not need to take any action.

<Note>
  Token management is fully automatic. The server monitors, refreshes, and reloads your token without any intervention required on your part.
</Note>

## Token status display

While the server is running, you will see a token status line in the terminal every 60 seconds (configurable). The status includes a visual indicator, the time remaining, and the exact expiration time.

```text theme={null}
🔑 Token Status: ✅ Expires in 57m 29s (at 1:51:23 PM)
```

The status icon changes based on how much time remains:

| Icon | Condition          | Time remaining                              |
| ---- | ------------------ | ------------------------------------------- |
| ✅    | Fresh token        | More than 15 minutes                        |
| 📊   | Expiring soon      | 5–15 minutes                                |
| ⚠️   | Expiring very soon | Less than 5 minutes — auto-refresh triggers |

## Automatic token refresh

When the token is within 5 minutes of expiring (configurable via `ZOOM_AUTO_REFRESH_THRESHOLD`), the server automatically runs a refresh sequence. You will see the following output in your terminal:

```text theme={null}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔑 Token Status: ⚠️ Expires in 2m 15s (at 2:58:31 PM)
⏳ Token expiring soon! Automatically refreshing...
📝 Running: get_zoom_token.sh
📋 Token fetched successfully
🔄 Loading new token from .env
✅ Token updated: eyJz...NTMz → eyJz...VjgT
⚙️  Running: update_claude_config.sh
🚀 Running: restart_claude_app.sh
✅ Token refresh complete! New token is now active.
🔑 Token Status: ✅ Expires in 59m 45s (at 3:58:05 PM)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

The refresh sequence runs the following steps:

<Steps>
  <Step title="Fetch a new token">
    Runs `get_zoom_token.sh` to request a fresh token from the Zoom API and write it to `.env`.
  </Step>

  <Step title="Load the new token into memory">
    Reloads the updated `.env` file and clears the cached token so the server uses the new one immediately.
  </Step>

  <Step title="Update Claude Desktop config">
    Runs `update_claude_config.sh` to inject the new `ZOOM_ACCESS_TOKEN` into the Claude Desktop configuration file.
  </Step>

  <Step title="Restart Claude Desktop">
    Runs `restart_claude_app.sh` to restart Claude so it picks up the updated configuration.
  </Step>

  <Step title="Display new token status">
    Shows the updated expiration time immediately — no need to wait for the next 60-second cycle.
  </Step>
</Steps>

## Anti-loop safeguards

The server includes protections to prevent a failing refresh from causing a restart loop:

* **30-second cooldown** between refresh attempts — if a refresh is triggered while another is still within its cooldown window, the server waits before retrying.
* **Auto-refresh disabled after 3 consecutive failures** — if the refresh fails three times in a row, the server stops attempting automatic refreshes to prevent repeated Claude restarts.

<Warning>
  If auto-refresh is disabled after 3 consecutive failures, you will see this message in the terminal:

  ```text theme={null}
  ❌ CRITICAL: Max refresh failures reached. Auto-refresh disabled.
  ```

  To recover, run the following command manually:

  ```bash theme={null}
  ./scripts/get_zoom_token.sh -f
  ```

  This forces a fresh token fetch, bypassing the validation check. After the token is updated, restart the server normally.
</Warning>

## Customizing token monitoring

You can adjust token monitoring behavior using environment variables set before launching the server.

| Variable                      | Default | Description                                                                                       |
| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `ZOOM_TOKEN_DISPLAY_INTERVAL` | `60`    | How often (in seconds) the token status line appears. Set to `0` to disable the periodic display. |
| `ZOOM_AUTO_REFRESH_THRESHOLD` | `300`   | Seconds before expiration at which auto-refresh triggers (default: 5 minutes).                    |
| `ZOOM_TOKEN_THRESHOLD`        | `60`    | Refresh threshold used by `check_zoom_token.sh` (default: 60 seconds).                            |

**Examples:**

```bash theme={null}
# Show token status every 30 seconds
ZOOM_TOKEN_DISPLAY_INTERVAL=30 ./run.sh

# Show token status every 2 minutes
ZOOM_TOKEN_DISPLAY_INTERVAL=120 ./run.sh

# Trigger auto-refresh 10 minutes before expiration
ZOOM_AUTO_REFRESH_THRESHOLD=600 ./run.sh

# Disable the periodic token status display entirely
ZOOM_TOKEN_DISPLAY_INTERVAL=0 ./run.sh
```