Skip to main content
The hosted Hevy MCP endpoint runs at https://hevy.chrisdoc.dev/mcp as a Cloudflare Worker. It requires no local installation, keeps nothing running on your machine, and exposes the same 25 tools as the npm package and Docker image. Send your Hevy API key as a bearer token on every request and you’re connected.

​
Connection details

Production URL

https://hevy.chrisdoc.dev/mcp

Protocol

Streamable HTTP (stateless POST)

Auth

Bearer token — your Hevy API key
The Worker handles each request independently: it creates a fresh MCP server and Hevy client, validates the supplied key with Hevy, serves the response, then discards all state. There is no shared session and no persistent storage of your key.

​
Generic client configuration

Clients that accept a remote MCP URL and fixed request headers use this shape:
The bearer value is your Hevy API key directly — not an OAuth token. Exact configuration keys vary by client; refer to the client-specific pages below for tested configurations.
Treat the bearer value like a password. Never embed your Hevy API key in source code, commit it to version control, or include it in a URL where it might appear in server logs or browser history.

​
OAuth for Claude.ai

Claude.ai custom connectors — and other remote MCP clients that cannot attach a fixed Authorization header — use an OAuth 2.1 layer built into the Worker. When the OAUTH_KV KV namespace binding is present on the deployed Worker, the following additional endpoints are active:
1

Add the connector in Claude.ai

Open Claude.ai → Settings → Integrations → Add custom connector. Enter https://hevy.chrisdoc.dev/mcp as the server URL. Claude.ai discovers the OAuth metadata automatically via /.well-known/.
2

Dynamic client registration

Claude.ai registers itself with the Worker at /register and receives a client_id. No manual registration is required.
3

Authorize with PKCE

Claude.ai redirects your browser to /authorize with a PKCE S256 code challenge. The authorization page prompts you to paste your Hevy API key. The Worker validates it with Hevy, stores it encrypted inside the OAuth grant, and issues an authorization code.
4

Token exchange

Claude.ai exchanges the code at /token for an access token. Subsequent MCP requests carry this token; the Worker decrypts the stored Hevy API key from the grant and forwards it to Hevy as the required api-key header.
The OAuth layer is purely additive. Direct Authorization: Bearer <hevy-api-key> requests continue to work unchanged. Clients that require OAuth discovery, dynamic registration, or token refresh are supported through the OAuth flow; clients that support fixed headers do not need it.
Key rotation: Rotating your Hevy API key in the Hevy app invalidates every OAuth grant created with the old key. You will need to re-authorize in Claude.ai (or whichever OAuth client you used) after rotating.

​
Security notes

The Cloudflare Worker is designed so your Hevy API key is never stored in plain text or logged:
  • Per-request validation: The Worker calls the Hevy API to validate your key on every incoming MCP request. A revoked or expired key is rejected immediately.
  • No key storage (direct mode): When you send the key as a bearer token in the Authorization header, it exists only in memory for the duration of that request.
  • Encrypted grant storage (OAuth mode): In the OAuth flow, the key is stored encrypted inside the OAuth grant in the OAUTH_KV KV namespace. It is decrypted per-request and never written to logs.
  • Upstream forwarding only: The Worker forwards your key to Hevy exclusively as the required api-key header. It is never echoed back in responses or included in any log output.
Never pass HEVY_API_KEY as a URL query parameter. Query strings appear in server access logs, browser history, and referrer headers. Use the Authorization: Bearer header exclusively.

​
Client-specific setup

Claude Desktop

Configure hevy-mcp in Claude Desktop on macOS or Windows using npx or the hosted endpoint.

Codex

Add the hosted endpoint or a local stdio server to Codex CLI, desktop app, or IDE extension.

Docker

Pull the official image and run hevy-mcp as a local stdio server with any MCP client.

Security guide

Best practices for keeping your Hevy API key safe across all clients.