> ## 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.
# Security practices for Hevy MCP API keys and mutations
> Best practices for protecting your Hevy API key, configuring CORS for self-hosted Workers, and understanding how mutation tools affect your Hevy data.
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:
```text theme={null}
MCP_ALLOWED_ORIGINS=https://my-app.example.com,https://staging.example.com
```
* **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 ` requests continue to work unchanged alongside OAuth — the OAuth layer is purely additive.
Learn how the hosted Cloudflare Worker handles key validation and routing.
Full reference for all environment variables including CORS and timeout settings.