fix(track,growth): product APIs reject the OAuth token issued by the FerrLabs authorization server

[BryanFRD]

Authorising ferrlabs-track and ferrlabs-growth over the standard OAuth flow succeeds, but every authenticated tool call then fails. The token is minted by api.ferrlabs.com (the authorization server named in each /.well-known/oauth-protected-resource), relayed by the MCP as x-api-token + Authorization: Bearer, and rejected by the product API.

Reproduction

Authorize the server, then call any authenticated tool:

• ferrlabs-track -> list_projects -> 401
• ferrlabs-growth -> list_sites -> 401

Both surface as the UnauthorizedError raised in packages/mcp-core/src/api-client.ts:50-56:

Stored token rejected by the FerrLabs API (likely revoked, expired, or issued
under an incompatible format). The token has been cleared - retry the call to
trigger a fresh OAuth login.

Retrying does not help: a fresh authorization yields another token of the same format, which is rejected the same way.

What is not the cause

• Not a client misconfiguration. The stored credential is a valid 61-character access token with a clientId, written by a completed authorization-code flow.
• Not an outage. api.ferrtrack.com/health and api.ferrgrowth.com/health both return 200.
• Not the MCP transport. ferrlabs against api.ferrlabs.com works on the same flow and returns real data, and ferrlabs-fleet gets past auth to a 404, so the bearer relay itself is correct.

Likely root cause

FerrTrack and FerrGrowth verify sessions with a shared HS256 secret rather than the format the FerrLabs authorization server issues. FerrVault is the EdDSA reference implementation. The authorization server and the product APIs therefore disagree on the token format, and the OAuth flow can never produce a token these APIs accept.

That makes the current sub-MCP OAuth path unusable for both products regardless of client configuration.

Scope

The fix is unlikely to land in this repo. It belongs to the session-verification code shared through Kit and to the product APIs. Filing here because this is where the failure surfaces and where the sub-MCPs are documented as working. Verify ferrlabs-vault too, it was not exercised.

Note

Each 401 also triggers #239, which clears the server-side persisted token even though the credential came from a per-request bearer. Reproducing this issue reproduces that one.

[BryanFRD]

Tested ferrlabs-vault, which the issue listed as unverified. It works, and that turns the suspected cause into a demonstrated one.

The discriminator

A rejected token returns 401 before routing; an accepted one reaches the router and returns 404 for a resource that does not exist. Calling get_vault with a deliberately nonexistent project and vault, on the same authorization and the same org:

get_vault(org_slug: "ferrlabs", project_slug: "probe-nonexistent", vault_id: "probe-nonexistent")
-> API error: HTTP 404

404, not 401. api.ferrvault.com accepted the bearer.

Why this settles it

All four sub-MCPs were authorized in the same session, against the same authorization server, and hold access tokens of the same format:

Sub-MCP	Verification	Result
ferrlabs-vault	EdDSA	404, token accepted
ferrlabs-fleet	-	404, token accepted (then #317)
ferrlabs-track	shared HS256 secret	401, token rejected
ferrlabs-growth	shared HS256 secret	401, token rejected

The split falls exactly along the verification method. One token format, accepted by the EdDSA reference implementation, rejected by both HS256 products. Nothing else distinguishes the four: same client, same flow, same credential shape, and all four product APIs return 200 on /health.

So this is not a token that is revoked, expired or malformed, as the client-side error text suggests. It is valid, and the two HS256 products cannot verify it.

Consequence for the fix

The error message in packages/mcp-core/src/api-client.ts:50-56 misdiagnoses this: it tells the user to retry to trigger a fresh login, which cannot help since a new token has the same format. Worth correcting once the root cause is addressed, and it is a second reason to fix #239, which fires on every one of these 401s.

The fix belongs to session verification in Kit and the two product APIs, aligning them on what the authorization server issues rather than on the shared secret.