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

# Troubleshoot Hevy MCP connection and authentication issues

> Fix common Hevy MCP problems: server not appearing, npx failures, authentication errors, and enabling debug diagnostics.

Most Hevy MCP issues fall into three categories — client configuration, authentication, and environment. Work through the relevant accordion below to identify and fix the problem. If none of these resolve your issue, see [Getting help](#getting-help) at the bottom of this page.

***

## Common problems

<Accordion title="The server does not appear in my MCP client">
  After adding or changing a Hevy MCP entry in your client's configuration file, the client must be restarted or reconnected before the change takes effect.

  **Steps:**

  1. Save your client configuration file.
  2. Fully quit and reopen the client application, or use the client's "reconnect" / "reload MCP servers" option if one is available.
  3. Verify the server is listed in the client's MCP server panel or tool list.

  For Codex specifically, run the following command after restarting to confirm the entry is registered:

  ```bash theme={null}
  codex mcp list
  ```

  The output should include an entry named `hevy`. If it does not appear, check that you ran the `codex mcp add` command correctly and that the configuration was saved.
</Accordion>

<Accordion title="npx hevy-mcp fails to start">
  The `npx` runner requires **Node.js 20 or newer**. If the command fails immediately or prints a version error, update Node.js first.

  To verify that `hevy-mcp` can be downloaded and run:

  ```bash theme={null}
  npx -y hevy-mcp --version
  ```

  Run this in a plain terminal (not inside the MCP client). If this command succeeds, the package is healthy and the issue is likely in the client configuration or the `HEVY_API_KEY` environment variable.

  If `npx` is not available at all, confirm that Node.js is installed and that the `npm`/`npx` binaries are on your `PATH`.
</Accordion>

<Accordion title="Codex cannot see the Hevy server">
  Codex stores its MCP configuration separately from Claude Desktop and Cursor. Use the Codex CLI to inspect the current state:

  ```bash theme={null}
  codex mcp list
  ```

  If a `hevy` entry does not appear, add it:

  ```bash theme={null}
  # Hosted endpoint (recommended)
  codex mcp add hevy \
    --url https://hevy.chrisdoc.dev/mcp \
    --bearer-token-env-var HEVY_API_KEY

  # Local stdio
  codex mcp add hevy \
    --env HEVY_API_KEY=your-hevy-api-key \
    -- npx -y hevy-mcp
  ```

  After the entry appears in `codex mcp list`, **start a new Codex session**. Existing sessions do not pick up MCP configuration changes automatically.
</Accordion>

<Accordion title="Hosted authentication fails">
  If the hosted endpoint returns a 401 or authentication error, check the following:

  1. **The API key is active.** Open the Hevy app, go to **Settings → Developer**, and confirm the key is listed and has not been revoked.

  2. **The account has Hevy PRO.** The Hevy API requires an active PRO subscription. A key from a non-PRO account will be rejected.

  3. **The key is sent in the correct header.** The hosted Worker expects the key as a bearer token:

     ```http theme={null}
     Authorization: Bearer your-hevy-api-key
     ```

     Do not include the word "Bearer" inside the key value itself, and do not send the key as a query parameter or in any other header.

  4. **No extra whitespace.** Copy the key directly from the Hevy app and avoid trailing spaces or newlines.
</Accordion>

<Accordion title="Local authentication fails">
  For local stdio setups (Claude Desktop, Cursor, Docker, or any stdio client), the API key must be available to the MCP child process via the `HEVY_API_KEY` environment variable.

  Common causes of local authentication failures:

  * The `env` block in your MCP client config is missing or the key name is misspelled (`HEVY_API_KEY` is case-sensitive).
  * The key was set in your shell session but not in the client config — the child process does not inherit your interactive shell environment automatically in most clients.
  * The key has been rotated in the Hevy app but the config still contains the old value.

  Verify the key is reachable by running:

  ```bash theme={null}
  HEVY_API_KEY=your-hevy-api-key npx -y hevy-mcp --version
  ```

  If that succeeds, the key itself is valid. Update the `env` block in your client config with the same value and restart the client.
</Accordion>

<Accordion title="How to enable debug diagnostics">
  Set the `HEVY_MCP_DEBUG` environment variable to exactly `1` to enable diagnostic output:

  ```bash theme={null}
  HEVY_MCP_DEBUG=1 npx -y hevy-mcp
  ```

  Or in your MCP client config `env` block:

  ```json theme={null}
  {
    "mcpServers": {
      "hevy": {
        "command": "npx",
        "args": ["-y", "hevy-mcp"],
        "env": {
          "HEVY_API_KEY": "your-hevy-api-key",
          "HEVY_MCP_DEBUG": "1"
        }
      }
    }
  }
  ```

  Diagnostic output is written to **stderr**. It does not interfere with MCP JSON-RPC messages, which are written to stdout. Most MCP clients display stderr output in a separate log panel or surface it in the developer console.
</Accordion>

<Accordion title="API timeout errors">
  If tool calls fail with timeout errors, the default 30-second limit may be too short for large paginated responses (for example, fetching a very large exercise template catalog).

  Adjust the timeout using the `HEVY_MCP_API_TIMEOUT` environment variable (value in milliseconds):

  ```json theme={null}
  {
    "mcpServers": {
      "hevy": {
        "command": "npx",
        "args": ["-y", "hevy-mcp"],
        "env": {
          "HEVY_API_KEY": "your-hevy-api-key",
          "HEVY_MCP_API_TIMEOUT": "60000"
        }
      }
    }
  }
  ```

  If the value supplied is not a positive integer, the server falls back to the default of **30,000 ms** (30 seconds).
</Accordion>

***

## Getting help

If you have worked through the steps above and the issue persists, open an issue on GitHub:

[https://github.com/chrisdoc/hevy-mcp/issues](https://github.com/chrisdoc/hevy-mcp/issues)

Include the following in your report:

* Your MCP client name and version
* How you are running Hevy MCP (hosted endpoint, `npx`, Docker, etc.)
* The error message or unexpected behavior you observed
* The output of `HEVY_MCP_DEBUG=1` if applicable

<Note>
  `HEVY_MCP_DEBUG=1` enables privacy-bounded diagnostics — it does not log the API key value but does emit request and response metadata (tool names, argument shapes, HTTP status codes, and timing) to stderr. This output is safe to include in a GitHub issue.
</Note>

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/hevy-mcp/configuration">
    Full reference for HEVY\_API\_KEY, timeout, debug, and CORS settings.
  </Card>

  <Card title="Security" icon="shield" href="/hevy-mcp/guides/security">
    Best practices for API key handling and mutation safety.
  </Card>
</CardGroup>