How to connect a WHOOP MCP with Codex (4 steps)

When you hand Codex a task to build a recovery-scoring feature or a sleep-trend dashboard, you usually describe the WHOOP data in the prompt.

That description is incomplete: it flattens the nested structure of a recovery record, omits the stage breakdown inside a sleep session, and underspecifies how strain accumulates across a physiological cycle.

Codex ends up generating code against assumed field names and imagined value ranges, so the readiness algorithm misreads HRV, the parser breaks on a sleep stage it didn't expect, or the training-load module sums strain in a way real records never produce.

To give Codex direct access to WHOOP as it works through your coding tasks, we'll show you how to connect WHOOP with Merge Agent Handler's WHOOP MCP server.

How it works

Merge Agent Handler connects Codex to the WHOOP API through the Merge CLI. You install the CLI, authenticate once, and run a single setup command from your project root.

That command writes a Merge CLI section to your project's AGENTS.md file, which tells Codex when to call merge search-tools and merge execute-tool to reach WHOOP.

Once connected, Merge handles OAuth token storage and refresh on your behalf, so you never embed WHOOP credentials in your repo or track per-user authorization state yourself.

Related: How to use the WHOOP MCP in Claude Code

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Codex access (available via the OpenAI platform)
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A WHOOP account with developer API access (register your application in the WHOOP developer dashboard)

If you want to connect Merge Agent Handler's WHOOP MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Run the following to install the Merge CLI with pipx: pipx install merge-api

Confirm the install: merge --version

2. Log in to Merge

Authenticate the CLI with your Merge Agent Handler account: merge login

This links the CLI to your Merge account and stores your session credentials locally.

3. Add Agent Handler to Codex

From the root of the project where you want Codex to reach WHOOP, run:

merge setup cursor

This writes a Merge CLI section to your project's AGENTS.md file so Codex knows to use the CLI when a task needs WHOOP data. The command is idempotent, safe to re-run if you need to reset the configuration.

Commit the updated AGENTS.md so the configuration travels with the repo.

Related: A guide to integrating the WHOOP MCP with Cursor

4. Authenticate WHOOP

Create a Codex task that requires live WHOOP data. This can be something like: "Read the last 60 days of recovery and sleep records for this user and generate a readiness-scoring module that weights HRV, resting heart rate, and REM duration."

The first time Codex invokes a WHOOP tool, a Magic Link will appear to complete connector authentication.

Once authenticated, Codex can reach your WHOOP account through Merge for every later task in this project.

{{this-blog-only-cta}}

WHOOP MCP FAQ

In case you have more questions on setting up and using the WHOOP MCP with Codex, we've addressed several more commonly-asked questions below.

What can you do once the WHOOP MCP is connected to Codex?

With WHOOP connected, Codex can:

• Read real recovery records before scaffolding a readiness-scoring feature: pull the actual HRV, resting heart rate, and SpO2 values so the scoring weights and thresholds it writes reflect how those metrics actually move, not placeholder constants

• Pull live sleep sessions before generating a stage parser: fetch real sleep records with their REM, slow-wave, and light-sleep fields so the parser it writes matches the actual nesting and naming rather than an assumed shape

• Read workout strain history before generating a training-load aggregation module: retrieve real strain scores across recent workouts so the windowing and summation logic it writes handles the distribution that shows up in practice

• Pull physiological cycle records before generating test cases for a multi-day analysis function: fetch real cycle data so the test fixtures it produces cover the day-to-day variability that synthetic data never captures

• Read body profile data before generating normalization logic: access baseline values like max heart rate so the relative-strain calculations it codes are anchored to a real physiology rather than a guessed default

Why use Merge Agent Handler vs. a self-hosted WHOOP MCP server?

You can stand up your own MCP server on top of WHOOP's API. For one developer working against a single account, it's manageable: register an app, run the OAuth flow once, and write tool schemas for the endpoints your tasks touch.

That path gets harder the moment you support multiple users or run Codex tasks in CI.

WHOOP issues short-lived access tokens with refresh tokens, and every connected user needs their own token pair, refresh cycle, and handling for revoked access. A silent refresh failure means a Codex task quietly runs against stale or missing data, with no central view of which connections are still live.

Hosting your own MCP server doesn't remove any of that. You still own the OAuth plumbing, and now you maintain the server too. WHOOP doesn't publish an official MCP server, so community builds carry no promise of endpoint coverage or upkeep.

Merge Agent Handler manages credential storage and token refresh across every connected user. You can scope exactly which WHOOP operations a Codex task can call, and every call is logged with the identity, timestamp, and inputs.

For an app where people trust an agent with biometric and health data, scoped access plus full audit logging is the right base to build on.

Why connect WHOOP to Codex?

WHOOP holds dense, structured physiological data per user: recovery scores with HRV and resting heart rate, sleep sessions with full stage breakdowns, strain-scored workouts, and daily cycles that tie it all together.

Codex tasks that generate readiness logic, training analytics, or coaching features need that data to write code that's actually correct.

The fallback is describing the data in the prompt, and those descriptions always come up short. They miss the real value ranges, the optional fields, and the nesting that only appears in live records, so Codex writes against the description and produces code that breaks on the first real payload.

Connecting WHOOP lets Codex pull the actual records when a task calls for them. The recovery history before a readiness module, the sleep stages before a parser, the strain records before a load calculation: Codex reads the source instead of a paraphrase, and the generated code reflects how WHOOP data is really shaped.

Can I use Merge Agent Handler's WHOOP MCP with my employees?

Yes, Agent Handler for Employees is built to help organizations provision, secure, and govern how employees connect AI tools like Codex to health and fitness platforms like WHOOP.

Common patterns include:

• Provisioning and access control via SCIM with identity providers like Okta and Microsoft Entra ID, so IT can manage which developers can reach which user accounts or data types by role or team

• DLP and policy enforcement on tool calls, so admins can block queries that would return sensitive biometric or health data before the results reach a Codex task's context

• User-level audit logging so security and IT teams can review which recovery, sleep, and workout records were accessed, by which employee identity, and when

In practice, employees can use the WHOOP MCP to generate readiness-scoring features, build training-load analytics from real strain data, and produce coaching logic grounded in actual physiological records, and more, while IT keeps centralized control over which data each developer's agent can reach.