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

# Connect to the hosted Hevy MCP Cloudflare Worker

> Use the production Hevy MCP server at hevy.chrisdoc.dev/mcp with Streamable HTTP — no install, no Node.js, no Docker required.

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

<CardGroup cols={3}>
  <Card title="Production URL" icon="link">
    `https://hevy.chrisdoc.dev/mcp`
  </Card>

  <Card title="Protocol" icon="arrow-right-arrow-left">
    Streamable HTTP (stateless POST)
  </Card>

  <Card title="Auth" icon="key">
    Bearer token — your Hevy API key
  </Card>
</CardGroup>

```text theme={null}
https://hevy.chrisdoc.dev/mcp
```

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:

```json theme={null}
{
  "mcpServers": {
    "hevy": {
      "url": "https://hevy.chrisdoc.dev/mcp",
      "headers": {
        "Authorization": "Bearer your-hevy-api-key"
      }
    }
  }
}
```

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.

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

## 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:

| Endpoint                                  | Purpose                                        |
| ----------------------------------------- | ---------------------------------------------- |
| `/.well-known/oauth-authorization-server` | RFC 8414 server metadata discovery             |
| `/.well-known/oauth-protected-resource`   | RFC 9728 protected resource metadata           |
| `/register`                               | Dynamic client registration                    |
| `/token`                                  | PKCE authorization code token exchange         |
| `/authorize`                              | Browser page where you paste your Hevy API key |

<Steps>
  <Step title="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/`.
  </Step>

  <Step title="Dynamic client registration">
    Claude.ai registers itself with the Worker at `/register` and receives a
    `client_id`. No manual registration is required.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

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

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

## Client-specific setup

<CardGroup cols={2}>
  <Card title="Claude Desktop" icon="message-circle" href="/hevy-mcp/clients/claude-desktop">
    Configure hevy-mcp in Claude Desktop on macOS or Windows using npx or the
    hosted endpoint.
  </Card>

  <Card title="Codex" icon="terminal" href="/hevy-mcp/clients/codex">
    Add the hosted endpoint or a local stdio server to Codex CLI, desktop app,
    or IDE extension.
  </Card>

  <Card title="Docker" icon="box" href="/hevy-mcp/clients/docker">
    Pull the official image and run hevy-mcp as a local stdio server with any
    MCP client.
  </Card>

  <Card title="Security guide" icon="shield" href="/hevy-mcp/guides/security">
    Best practices for keeping your Hevy API key safe across all clients.
  </Card>
</CardGroup>