Skip to main content
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. 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.
1

Export your Hevy API key

Make the key available in the environment that launches Codex:
Add this line to your shell profile (.zshrc, .bashrc, etc.) to make it permanent across sessions.
2

Register the hosted server

Codex records HEVY_API_KEY as the environment variable to read at runtime. The key itself is never written to Codex’s configuration.
3

Verify the entry

Confirm that a hevy entry appears in the output before starting a session.
4

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

​
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.
1

Register the local server

The --env flag injects HEVY_API_KEY directly into the child process launched by Codex. Replace your-hevy-api-key with your actual key.
2

Verify the entry

Confirm that the hevy entry appears with the expected command.
3

Start or restart a Codex session

Restart Codex or begin a new session to activate the server.
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.

​
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

Hosted Endpoint

Details on the Cloudflare Worker, bearer token auth, and the OAuth 2.1 layer for clients that cannot send fixed headers.

Tools Overview

Browse all 25 tools hevy-mcp makes available once connected to Codex.

Guided Prompts

Server-provided prompts that coordinate multi-step training analysis and workout logging workflows.

Troubleshooting

Fix missing server entries, authentication failures, and session initialization issues.