Fellow Aiden brew.link MCP server

A remote MCP server on Cloudflare Workers that turns a Fellow Aiden brew profile into a shareable brew.link URL. It exposes one tool that validates a profile, creates it through Fellow's private API, generates a share link, and returns the URL — designed to be added to Claude.ai (and Claude Code) as a custom remote connector.

Built with Cloudflare's agents SDK (McpAgent, a Durable Object per session) over the Streamable HTTP transport at /mcp, plus @modelcontextprotocol/sdk and zod.

Tools

Tool	What it does
create_aiden_brew_link	Validates the profile, then login → get device → create profile → share against Fellow's API. Returns the brew.link URL (plain text), or a clear error.
validate_aiden_profile	Dry run — validates the profile against every Aiden constraint without calling Fellow's API. Returns { "valid": true, "profile": {…} } or { "valid": false, "errors": [...] }.

Profile input schema

All fields are required (except profileType, which defaults to 0). Validated before any API call:

Field	Type	Constraint
profileType	integer	use 0
title	string	1–50 chars, charset A-Z a-z 0-9 space ! @ # $ % & * - + ? / . , : ) (
ratio	number	one of 14, 14.5, 15, … 20 (0.5 steps)
bloomEnabled	boolean
bloomRatio	number	one of 1, 1.5, 2, 2.5, 3
bloomDuration	integer	1–120 (seconds)
bloomTemperature	number	one of 50, 50.5, … 99 (0.5 steps, °C)
ssPulsesEnabled	boolean
ssPulsesNumber	integer	1–10
ssPulsesInterval	integer	5–60 (seconds)
ssPulseTemperatures	number[]	each one of 50…99 by 0.5; length must equal ssPulsesNumber
batchPulsesEnabled	boolean
batchPulsesNumber	integer	1–10
batchPulsesInterval	integer	5–60 (seconds)
batchPulseTemperatures	number[]	each one of 50…99 by 0.5; length must equal batchPulsesNumber

Project layout

src/
  index.ts     MCP server (McpAgent), the two tools, CORS + auth gate + routing
  fellow.ts    Fellow API client: login → devices → create profile → share (401 re-login retry)
  profile.ts   zod schema + cross-field length validation
  env.d.ts     secret typings merged into the generated Env
wrangler.jsonc  Worker config (Durable Object binding MCP_OBJECT + migration)
test-tool.ps1   end-to-end handshake test (calls a tool and prints the result)

1. Install

npm install

2. Set the three secrets

The Worker reads three secrets from env — never hardcode them. Set each in your deployed Worker:

npx wrangler secret put FELLOW_EMAIL
npx wrangler secret put FELLOW_PASSWORD
npx wrangler secret put MCP_AUTH_TOKEN

• FELLOW_EMAIL / FELLOW_PASSWORD — your Fellow account login (the same one the Fellow app uses).
• MCP_AUTH_TOKEN — a long random string you choose. It gates the /mcp endpoint so only your connector can call it. Generate one with:

  [Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Max 256 }))
  

Windows / PowerShell gotcha: do not pipe a value into wrangler secret put (e.g. echo $x | wrangler secret put …) — PowerShell prepends a UTF‑8 BOM and the stored secret gets a hidden leading character, so logins/auth then fail mysteriously. Instead run the command with no pipe and paste the value at the interactive prompt, or pipe through cmd: cmd /c "type secret.txt" | npx wrangler secret put FELLOW_PASSWORD.

Local development

For npm run dev, put the same three values in a .dev.vars file (gitignored) — copy .dev.vars.example:

FELLOW_EMAIL=you@example.com
FELLOW_PASSWORD=your_fellow_password
MCP_AUTH_TOKEN=some-local-token

npm run dev   # http://127.0.0.1:8787  (MCP at /mcp, health at /health)

3. Deploy

npm run deploy

Wrangler prints the public URL. Your MCP endpoint is that URL + /mcp:

https://fellow-aiden-mcp.<your-workers-subdomain>.workers.dev/mcp

(If this is your first Worker, Cloudflare will prompt you to register a free *.workers.dev subdomain.)

4. Authentication model

The /mcp endpoint requires the MCP_AUTH_TOKEN shared secret, accepted two ways so every client works:

• Authorization: Bearer <MCP_AUTH_TOKEN> header — used by curl, Claude Code, and the Claude API MCP connector.
• ?token=<MCP_AUTH_TOKEN> query param on the URL — used by Claude.ai web, whose "Add custom connector" UI currently has no field for a bearer token or custom header (only OAuth client ID/secret). Putting the secret in the URL is the practical way to authenticate the web connector.

/health is open (no auth) for liveness checks. Requests with a missing/wrong token get HTTP 401.

5. Test end-to-end with curl (before wiring to Claude)

A full tool call is a 3‑message Streamable‑HTTP handshake (initialize → notifications/initialized → tools/call) that shares an Mcp-Session-Id. The included test-tool.ps1 does this for you:

# Dry-run validation only (no Fellow API call, no profile created):
./test-tool.ps1 -Url "https://fellow-aiden-mcp.<subdomain>.workers.dev/mcp" -Token "<MCP_AUTH_TOKEN>" -ValidateOnly

# Full end-to-end — creates a real profile and returns a real brew.link:
./test-tool.ps1 -Url "https://fellow-aiden-mcp.<subdomain>.workers.dev/mcp" -Token "<MCP_AUTH_TOKEN>"

A green https://brew.link/... line means success.

Raw curl

Health (no auth):

curl https://fellow-aiden-mcp.<subdomain>.workers.dev/health

Wrong/no token is rejected:

curl -i -X POST "https://fellow-aiden-mcp.<subdomain>.workers.dev/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
# -> HTTP/1.1 401 Unauthorized

initialize (note the Mcp-Session-Id in the response headers — reuse it on follow-up calls):

curl -i -X POST "https://fellow-aiden-mcp.<subdomain>.workers.dev/mcp?token=<MCP_AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

Then call the tool, reusing the session id (token shown here as a header instead of ?token= — either works):

SID="<value of Mcp-Session-Id from above>"
curl -X POST "https://fellow-aiden-mcp.<subdomain>.workers.dev/mcp" \
  -H "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SID" \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"create_aiden_brew_link","arguments":{"profileType":0,"title":"My Brew","ratio":16,"bloomEnabled":true,"bloomRatio":2,"bloomDuration":30,"bloomTemperature":96,"ssPulsesEnabled":true,"ssPulsesNumber":3,"ssPulsesInterval":20,"ssPulseTemperatures":[96,95,94],"batchPulsesEnabled":true,"batchPulsesNumber":2,"batchPulsesInterval":30,"batchPulseTemperatures":[96,95]}}}'

Windows curl tip: add --ssl-no-revoke if SChannel revocation checks fail (a local trust-store quirk, not a server issue).

6. Add it to Claude.ai (web) as a custom connector

1. Go to Settings → Connectors → Add custom connector.
2. Remote MCP server URL: paste your endpoint with the token in the URL:

   https://fellow-aiden-mcp.<subdomain>.workers.dev/mcp?token=<MCP_AUTH_TOKEN>
   

3. Leave Advanced settings (OAuth Client ID/Secret) blank — this server uses the URL token, not OAuth.
4. Save. Claude will connect and discover create_aiden_brew_link and validate_aiden_profile. In a chat, enable the connector and ask Claude to create a brew profile; it returns a brew.link.

Why the token is in the URL: Claude.ai's web connector UI has no bearer-token/header field (only OAuth). The query-param token is the supported way to authenticate. Treat the full URL (with token) as a secret. If you'd rather not put a secret in a URL, the alternative is to implement OAuth via Cloudflare's workers-oauth-provider — a larger change.

Claude Code / API connector

Use the header form instead — e.g. in Claude Code:

claude mcp add --transport http fellow-aiden \
  "https://fellow-aiden-mcp.<subdomain>.workers.dev/mcp" \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Scripts

npm run dev         wrangler dev (local, reads .dev.vars)
npm run deploy      wrangler deploy
npm run type-check  tsc --noEmit
npm run cf-typegen  regenerate worker-configuration.d.ts after wrangler.jsonc changes

Notes & limitations

• Single brewer assumed. The brewer id is read from GET /devices?dataType=real element [0]. Multi-brewer accounts would need a selector.
• 401 handling. Any Fellow call returning 401 triggers one re-login + retry, per Fellow's API behavior.
• No persistence. The server is stateless per call (the Durable Object only backs MCP session transport); nothing about your brews is stored.
• Unofficial API. Endpoints/headers are reverse-engineered from the open-source 9b/fellow-aiden package and may change without notice.