> ## 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.

# Connect OpenAI Codex to Hevy MCP

> Configure Hevy MCP in Codex CLI, the Codex desktop app, or IDE extension using either the hosted endpoint or a local npx server.

Codex CLI, the Codex desktop app, and the Codex IDE extension share the same MCP configuration store. You register the `hevy` server once and it is available across all three surfaces. Both the hosted Streamable HTTP endpoint and a local stdio server started via `npx` work with Codex — choose whichever fits your workflow.

## Hosted endpoint (recommended)

The hosted Cloudflare Worker at `https://hevy.chrisdoc.dev/mcp` requires no local Node.js installation and starts with zero process overhead. Codex stores the environment variable *name*, not the key itself, so your Hevy API key stays in your shell environment and out of Codex's configuration file.

<Steps>
  <Step title="Export your Hevy API key">
    Make the key available in the environment that launches Codex:

    ```bash theme={null}
    export HEVY_API_KEY=your-hevy-api-key
    ```

    Add this line to your shell profile (`.zshrc`, `.bashrc`, etc.) to make it
    permanent across sessions.
  </Step>

  <Step title="Register the hosted server">
    ```bash theme={null}
    codex mcp add hevy \
      --url https://hevy.chrisdoc.dev/mcp \
      --bearer-token-env-var HEVY_API_KEY
    ```

    Codex records `HEVY_API_KEY` as the environment variable to read at runtime.
    The key itself is never written to Codex's configuration.
  </Step>

  <Step title="Verify the entry">
    ```bash theme={null}
    codex mcp list
    ```

    Confirm that a `hevy` entry appears in the output before starting a session.
  </Step>

  <Step title="Start or restart a Codex session">
    Restart Codex or begin a new session. MCP servers are initialized at session
    start; existing sessions do not pick up new server registrations.
  </Step>
</Steps>

<Tip>
  Always run `codex mcp list` to confirm the `hevy` entry exists before
  starting a new session. If the entry is missing, Codex will not connect to
  hevy-mcp even if the `add` command appeared to succeed.
</Tip>

## Local stdio

If you prefer to keep everything on your own machine — or if your environment cannot reach the hosted endpoint — run `hevy-mcp` locally via `npx`. Codex starts and stops the process automatically.

<Steps>
  <Step title="Register the local server">
    ```bash theme={null}
    codex mcp add hevy \
      --env HEVY_API_KEY=your-hevy-api-key \
      -- npx -y hevy-mcp
    ```

    The `--env` flag injects `HEVY_API_KEY` directly into the child process
    launched by Codex. Replace `your-hevy-api-key` with your actual key.
  </Step>

  <Step title="Verify the entry">
    ```bash theme={null}
    codex mcp list
    ```

    Confirm that the `hevy` entry appears with the expected command.
  </Step>

  <Step title="Start or restart a Codex session">
    Restart Codex or begin a new session to activate the server.
  </Step>
</Steps>

<Note>
  The local stdio approach requires **Node.js 20 or newer**. Run
  `node --version` to confirm, or `npx -y hevy-mcp --version` to test the
  package directly.
</Note>

## Start a session

Once hevy-mcp is registered, start a new Codex session and try one of these prompts to confirm the connection:

* "Which Hevy account is connected?"
* "Give me a training summary for the last four weeks."
* "What routines do I have saved on Hevy?"

Codex will invoke the appropriate hevy-mcp tool and return real data from your Hevy account.

## Next steps

<CardGroup cols={2}>
  <Card title="Hosted Endpoint" icon="cloud" href="/hevy-mcp/clients/hosted-endpoint">
    Details on the Cloudflare Worker, bearer token auth, and the OAuth 2.1
    layer for clients that cannot send fixed headers.
  </Card>

  <Card title="Tools Overview" icon="wrench" href="/hevy-mcp/tools/overview">
    Browse all 25 tools hevy-mcp makes available once connected to Codex.
  </Card>

  <Card title="Guided Prompts" icon="message-square" href="/hevy-mcp/guides/prompts">
    Server-provided prompts that coordinate multi-step training analysis and
    workout logging workflows.
  </Card>

  <Card title="Troubleshooting" icon="circle-alert" href="/hevy-mcp/guides/troubleshooting">
    Fix missing server entries, authentication failures, and session
    initialization issues.
  </Card>
</CardGroup>