Skip to main content
Hevy MCP accesses your Hevy account using your API key on every request. A leaked key gives full read and write access to your Hevy data, so it is important to keep it secure and to understand how mutation tools behave before using them.

​
API key security

Your Hevy API key is equivalent to a password for your Hevy account. Follow these practices:
  • Keep it out of source control. Never commit the key to a git repository, paste it in a public issue, or include it in screenshots or recordings.
  • Never pass it in a URL. Query-string parameters and path segments appear in server logs, browser history, and referrer headers.
  • Local clients: provide the key through the child process environment only (the env block in your MCP client config), never as a command-line argument.
  • Hosted clients: send the key exclusively in the Authorization: Bearer header on each request. The Worker validates the key with Hevy, does not store it, and forwards it upstream only as Hevy’s required api-key header — it never appears in the Worker’s own logs or storage.
Never embed your Hevy API key in configuration files committed to source control, even in private repositories. Use environment variables or a secrets manager instead, and add your config file to .gitignore if it contains the key.

​
CORS configuration (self-hosted Worker)

When you self-host the Cloudflare Worker, browser-based MCP clients must match an explicitly allowed origin before cross-origin requests are accepted.
  • Set the MCP_ALLOWED_ORIGINS environment variable to a comma-separated list of exact origins that should be permitted — for example:
  • Wildcards are intentionally unsupported. Every allowed origin must be listed explicitly.
  • Requests that arrive without an Origin header — such as those from desktop MCP clients, curl, or server-side code — are always accepted regardless of the MCP_ALLOWED_ORIGINS value.

​
Mutation safety

Hevy MCP tools fall into two categories: Read tools — safe for exploration. They only retrieve data from Hevy and make no changes to your account. You can call them freely without risk of data modification. Write tools — annotated with MCP mutation annotations. MCP clients that support these annotations (such as Codex and compatible IDE extensions) will display a confirmation prompt before executing the tool. Always review the proposed inputs before approving. Important behaviors to be aware of:
  • Create operations can produce duplicates when retried. If a create-workout, create-routine, or create-body-measurement call fails mid-flight and you retry it, a duplicate record may be created in Hevy. Check your Hevy account before retrying a failed create.
  • Update operations fully replace existing records. Calling update-workout or update-routine replaces the entire record with the new payload — any fields you omit are not preserved from the original.
There are no delete tools in Hevy MCP because the Hevy API does not expose delete endpoints for workouts, routines, routine folders, exercise templates, or body measurements. However, update operations fully replace existing records — review all inputs carefully before confirming a write operation.

​
OAuth token security

The hosted Worker optionally supports an OAuth 2.1 authorization layer for clients that cannot send a fixed Authorization header (such as Claude.ai custom connectors). When OAuth is enabled:
  • OAuth grants are tied to the Hevy API key used during authorization. The key is validated with Hevy at authorization time and stored encrypted inside the OAuth grant.
  • Rotating your Hevy API key automatically invalidates all OAuth grants created with it. After you generate a new API key in the Hevy app, any client that authenticated via OAuth must re-authorize using the new key.
  • Direct Authorization: Bearer <hevy-api-key> requests continue to work unchanged alongside OAuth — the OAuth layer is purely additive.

Hosted Endpoint

Learn how the hosted Cloudflare Worker handles key validation and routing.

Configuration

Full reference for all environment variables including CORS and timeout settings.