Connect Freddy from Claude Code

Claude Code is Anthropic's terminal-based coding agent. Once Freddy is wired in, you can ask Claude Code things like "summarize last week's sleep and HRV" or "show me the last five workouts" right alongside your code work.

This guide gives you two paths:

• Path A, system prompt (no shell recipe): drop a few lines into Claude Code's instructions and let the agent walk the sign-in itself. Easiest if you live in a project that already uses a CLAUDE.md or system prompt.
• Path B, paste an access token (one shell recipe, one paste): run a five-line script, get a sign-in token, configure Claude Code's MCP once. Most reliable.

Pick whichever fits. Both produce the same result.

Before you start

• A Freddy account. Sign up free at freddy.coach.
• Claude Code installed and logged in.
• At least one wearable connected and synced in your Freddy dashboard.

Path A: Tell Claude Code about the flow

Add the following to your Claude Code system prompt (e.g. in ~/.claude/CLAUDE.md for global use, or in your project's CLAUDE.md):

When the user wants to use Freddy and there is no Freddy MCP yet:

1. POST to https://freddy.coach/oauth/register with JSON
   {"client_name":"Claude Code","redirect_uris":["http://localhost"]}.
   Save the returned client_id.

2. POST to https://freddy.coach/oauth/device_authorization with form data
   client_id=<saved>
   scope=mcp account:read connections:write
   (form-encode the spaces in the scope value as %20 or +).
   Show the user verification_uri_complete and ask them to open it.

3. Poll POST https://freddy.coach/oauth/token with form data
   grant_type=urn:ietf:params:oauth:grant-type:device_code
   client_id=<saved>
   device_code=<from step 2>
   every 6 seconds. Save the access_token field from the JSON response
   when one comes back. If the response has error=authorization_pending
   keep polling; error=expired_token means restart from step 2.

4. Using the saved access token, run:
   claude mcp add --transport http freddy https://freddy.coach/mcp \
     --header "Authorization: Bearer <access_token>"

5. Tell the user Freddy is now configured. Ask them to restart Claude
   Code so the new MCP loads, then in a new session say something like
   "what's available in my Freddy data?".

Then in a Claude Code session, say something like "set up Freddy and tell me how I slept last week". Claude Code will ask permission to make those HTTP calls, walk the flow, and open the browser sign-in. After you approve in the browser, the agent finishes the setup and starts answering.

Path B: Run the script, paste the token

Run this once in a terminal. It prints a sign-in URL, you approve in a browser, and it prints an access token:

APP=https://freddy.coach
CLIENT=$(curl -sX POST $APP/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name":"Claude Code","redirect_uris":["http://localhost"]}' \
  | jq -r .client_id)

DA=$(curl -sX POST $APP/oauth/device_authorization \
  --data-urlencode "client_id=$CLIENT" \
  --data-urlencode "scope=mcp account:read connections:write")

DEVICE=$(echo "$DA" | jq -r .device_code)
URL=$(echo "$DA"   | jq -r .verification_uri_complete)
echo "Open: $URL"

while :; do
  R=$(curl -sX POST $APP/oauth/token \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:device_code" \
    --data-urlencode "client_id=$CLIENT" \
    --data-urlencode "device_code=$DEVICE")
  ERR=$(echo "$R" | jq -r .error)
  case "$ERR" in
    authorization_pending|slow_down) sleep 6 ;;
    null) echo "$R" | jq -r .access_token; break ;;
    *) echo "stop: $ERR"; break ;;
  esac
done

Copy the freddy_at_... value the script prints. Then:

claude mcp add --transport http freddy https://freddy.coach/mcp \
  --header "Authorization: Bearer freddy_at_..."

Verify:

claude mcp list

You should see freddy listed. Restart Claude Code, then try a question like "what's available in my Freddy data?". Claude Code will call Freddy's tools and answer.

Token refresh

Access tokens last 1 hour. The shell recipe also returns a 60-day refresh token (freddy_rt_...) you can use to mint new access tokens. If your session has been quiet for a while and you start seeing "Authentication required" errors from the Freddy tools, run the recipe again to get a fresh access token, then update the MCP config:

claude mcp remove freddy
claude mcp add --transport http freddy https://freddy.coach/mcp \
  --header "Authorization: Bearer <new freddy_at_...>"

For now the manual swap is the workaround.

Need help?

See agent troubleshooting for common errors. If something is still wrong, email support@freddy.coach or message us at freddy.coach/app/chat.