Repository navigation
spec(FIX-1903): epic amendment, FSD holds MCP keys per user - #3179
Conversation
Jake rejected FIX-1905's first D2 on #3174: the MCP key can't go through Claude Code, and each user sets their own key on a settings page. This amends the merged epic set in place to match: - FSD holds the MCP connection (createMcpManager) with the run owner's key; Claude Code gets tools only through a generic `mcpTools` option. - Keys are per user, write-only, on Shift Manager's Settings page. LINEAR_MCP_API_KEY only seeds the operator identity for headless runs. - ER-6, ER-7, ER-9, D4's Locks in and figure, Decided in review, SPEC's Bigger / Input / control, PLAN's FIX-1905 row (about 1.5x), DOCS' shared paragraph and "Tools a project's coding work gets". - Closure leg a must FAIL when neither Settings nor the variable has a key. - EVOLUTION records the supersession and corrects LAB-138's source. ER-14 (aliases only on a row, endpoints in host config) is unchanged. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MJsSFWmTXycBXJU4s96Pk1
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
|
@codex review |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Second look: epic amendment (spec-only PR)The direction is the owner's call, so this review checks the amendment for coherence, not the direction. I read all 7 files and grepped the epic and 1. ER-6 weakens the old guarantee, and the epic doesn't price that.
2. FIX-1905 grew past the "one PR" the epic still promises.
3. ER-9: "
4. Dangling link in EVOLUTION.md.
5. Smaller points
Architecture note (improve-codebase-architecture lens). The shape is right: one connection owner (FSD), one tools-only seam into the harness. It is also the shape that lets Cursor and Codex follow without new options. The risk is where the key lookup lives. If FIX-1905 puts "resolve owner → key → manager" inside Generated by Claude Code |
There was a problem hiding this comment.
Simplify review (automation)
This PR is doing real work — especially the FIX-1903 amendment after #3174 — but the diff is four unrelated spec tracks (~3.4k lines). The title suggests only FIX-1903; reviewers have to hold FIX-1870 closure, FIX-1903 children, and FIX-1907 Cursor in one gate. I'd split or retitle before merge unless this branch is intentionally a batch landing.
Is the MCP pivot the right shape?
Yes, given the constraint. Passing LINEAR_MCP_API_KEY into Claude's environment was simpler on paper, but it breaks once (a) each person needs their own Linear identity and (b) FSD must own the connection for non–Claude harnesses later. The amended model — user-scoped keys in the Lab store (BP-031), createMcpManager in FSD, mcpTools as tools-only relay into Claude Code — matches existing @flow-state-dev/tools/mcp and kitchen-sink's Linear server template (apps/kitchen-sink/lib/mcp.ts). That's more moving parts than #3164, but it's the smaller total change than bolting per-harness env plumbing and revisiting it for Cursor/Codex.
Simpler alternatives considered (and why they're weaker here):
| Alternative | Trade-off |
|---|---|
| Keep env-var credential, document "paste your key in shell" | Fails the owner call on Settings; wrong security story for multi-user Lab |
createMcpCapability only in kitchen-sink-style apps, not Shift Manager runs |
Doesn't reach coding runs in workforce/harness-manager |
| Push full MCP server config into Claude SDK (URL + headers) | Keys and endpoints leak toward the harness; fights ER-9 / LAB-138 ask boundary |
| OAuth now | Correct long-term; correctly deferred — paste-key Settings is the honest v1 |
Optional implement-time simplifications (not spec blockers): document one sequence diagram for connect → getTools() → mcpTools; note whether MCP connections are per-run only or may be reused per owner session; call out relay latency only if goal checks show it matters.
Gaps before I'd approve
- FIX-1905 retained spec is not in the tree while ER-6/7/9 and D4 are fully amended here.
EVOLUTION.mdlinks tospecs/issues/FIX-1905/EVOLUTION.md, which doesn't exist on this branch — implementers only have epic-level prose for Settings UI, collections, andmcpToolswiring. Either add a minimal FIX-1905 amendment in this PR or land it in the same merge window with an explicit "authoritative spec" pointer in the epic SPEC. - FIX-1917 depends on FIX-1915's
replacePlanList(not in repo here). Approving 1917 without 1915's retained spec in git is directionally fine but increases "approved API that isn't canonical yet" risk — cross-link or batch.
Documentation / spec weight (recommended tidy, not direction changes)
- ER-6 is a full design in one table cell; split or add a short "key path" subsection so D4, PLAN, and DOCS don't each re-read the same paragraph.
- DECISIONS.md "Decided in review" largely repeats D1–D4; collapse to anchors + net-new items (#3174 Settings decision).
- FIX-1904 PLAN inlines a large FIX-1906 table (pinned to PR #3177 SHA) and retains long "Notes from review" — move to EVOLUTION or link FIX-1906 SPEC only.
- FIX-1887 rename-map: hardcoded
MAPand--sourcesfrom child PLAN tables — high drift risk; document a single sync procedure or generate one from the other. - FIX-1904 D1 / account-probe POC: signed-in Claude row still "not run"; narrow the claim or run it before spec merge.
What looks good
- D4 "read MCP at run start from task row's project" unchanged — still the clean seam vs
handOff/dispatchTaskfields. - FIX-1887 POCs earn their keep (rename-map caught real widening; sweep control is concrete).
- FIX-1917 sdk-wire POC is appropriately small; keeping translation in
@flow-state-dev/cursornot kitchen-sink matches ER-11 thinking. - Reuse of
probeClaudeAccountacross FIX-1904 and FIX-1915 is the right consolidation.
Verdict: COMMENT, not approve yet — the MCP amendment direction looks right, but scope bundling and missing FIX-1905 retained spec should be resolved (or explicitly accepted at the gate) before merge.
Sent by Cursor Automation: Review For Best Approach
| | ER-5 | A project may name MCP servers, by host-approved alias ([ER-14](#what-no-child-may-do)). A coding run gets its project's servers when it starts, read from the project its own task row names, never from a hand-over's payload. A run whose project has none gets none ([D4](DECISIONS.md#d4)) | FIX-1905 decides · FIX-1904 consumes | FIX-1905's goal check, on a run not handed over by a coordinator | | ||
| | ER-6 | No credential, endpoint or credential variable is stored on a project row. A row selects MCP servers by an alias the host approves; the host config gives each alias its endpoint and the environment variable that holds its credential, and the host reads it. The value reaches the MCP connection only: not the run's environment, a log, a session or the page. The dev profile's host config has one alias, `linear`, whose variable is `LINEAR_MCP_API_KEY`, the name the kitchen-sink's Linear capability reads (`apps/kitchen-sink/lib/mcp.ts`); each person signing in to Linear as themselves is a later epic | FIX-1905 | FIX-1905's tests · its spec review | | ||
| | ER-7 | A server whose credential variable is unset is said out loud, once when the server starts and on each run that misses it. The run still runs, and that is a degraded run, not a pass: with `LINEAR_MCP_API_KEY` unset, the closure's leg a must FAIL its title check ([ER-20](#the-closure)) | FIX-1905 | FIX-1905's tests · the closure, run with the variable unset | | ||
| | ER-6 | No credential, endpoint or credential variable is stored on a project row. A row selects MCP servers by an alias the host approves, and the host config gives each alias its endpoint. The key is each person's own: set on Shift Manager's Settings page, stored as a user-scoped record in the Lab's store, write-only, shown only as set or not set. A run uses its owner's key, resolved from the server-side identity the run records, never from a field a caller sends ([BP-031](../../../docs/contributing/best-practices.md)). FSD holds the MCP connection with that key (`createMcpManager`), and the run gets the servers' tools only: the key is not handed to its command line, environment, MCP config, a log, a session or the page. It is not unreachable: an unsandboxed run can read the Lab's store. The dev profile's host config has one alias, `linear`. `LINEAR_MCP_API_KEY`, the name the kitchen-sink's Linear capability reads (`apps/kitchen-sink/lib/mcp.ts`), seeds only the Lab's operator identity, for headless and CI runs, while it has no stored key. Signing in to Linear by OAuth is a later epic | FIX-1905 | FIX-1905's tests · its spec review | |
There was a problem hiding this comment.
ER-6 packs Settings UI, user-scoped store, createMcpManager, mcpTools, operator seed, unsandboxed caveat, and OAuth deferral into one table row. Consider splitting (credential storage vs connection boundary) or a 5-step "key path" subsection — implementers will otherwise infer FIX-1905 solely from this cell.
| | The Claude Code harness takes no MCP option, so a conductor-owned ask tool was refused as widening the framework; `packages/harness-manager/src/ask.ts` header, citing LAB-138's decision 3 (an incubation lab; no retained source) | **Amended** for MCP, retained for the ask | D4 adds a generic per-run MCP pass-through, which the Agent SDK already supports. It is not a conductor-owned tool, and the ask stays a file | ER-9; FIX-1905 owns; its spec rechecks the lab decision | Absent option means no servers, as today | | ||
| | The Claude Code harness takes no MCP option, so a conductor-owned ask tool was refused as widening the framework; `packages/harness-manager/src/ask.ts` header, citing LAB-138's decision 3 ([LAB-138's spec](https://linear.app/fixpoint-labs/document/lab-138-the-harness-manager-implementation-spec-8444a9f240f9), §6 item 3; [#1437](https://github.com/fixpoint-labs/flow-state-dev/pull/1437)) | **Amended** for MCP, retained for the ask | D4 adds one generic tools-only option, `mcpTools`, which the Agent SDK's in-process servers already support. It is not a conductor-owned tool, and the ask stays a file | ER-9; FIX-1905 owns; its spec rechecks the lab decision | Absent option means no servers, as today | | ||
| | A project's coding work was to get MCP servers from the coordinator that hands it over; FIX-1903's and FIX-1905's Linear descriptions | **Superseded** | A run started from Inbox or by the chief of staff passes through no coordinator; the run's own task row names its project on every path | D4, ER-5, ER-8 | Nothing built yet | | ||
| | This epic as merged in [#3164](https://github.com/fixpoint-labs/flow-state-dev/pull/3164): the key came from a host credential variable, and the harness got per-run MCP servers (D4's *Locks in*, ER-6, ER-7, ER-9) | **Superseded** by the owner on FIX-1905's spec review, [#3174](https://github.com/fixpoint-labs/flow-state-dev/pull/3174#issuecomment-6131359139): "D2 can't be through Claude … provide a settings page which allows keys to be configured" | FSD must control the connection and the key whichever harness runs; there is no admin, so each person sets their own key | D4, ER-6, ER-7, ER-9 as amended; [FIX-1905's evolution](../../issues/FIX-1905/EVOLUTION.md) lists each statement; FIX-1905 owns | Nothing built. `LINEAR_MCP_API_KEY` stays as the operator's headless seed. Row aliases and host-config endpoints (ER-14) unchanged | |
There was a problem hiding this comment.
This row points at specs/issues/FIX-1905/EVOLUTION.md, which isn't on this branch while the epic amendment is already detailed. Either include FIX-1905's retained spec in the same merge window or add an explicit pointer in epic SPEC to whichever PR is canonical (#3174?).
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3c79a5d14e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | ER-5 | A project may name MCP servers, by host-approved alias ([ER-14](#what-no-child-may-do)). A coding run gets its project's servers when it starts, read from the project its own task row names, never from a hand-over's payload. A run whose project has none gets none ([D4](DECISIONS.md#d4)) | FIX-1905 decides · FIX-1904 consumes | FIX-1905's goal check, on a run not handed over by a coordinator | | ||
| | ER-6 | No credential, endpoint or credential variable is stored on a project row. A row selects MCP servers by an alias the host approves; the host config gives each alias its endpoint and the environment variable that holds its credential, and the host reads it. The value reaches the MCP connection only: not the run's environment, a log, a session or the page. The dev profile's host config has one alias, `linear`, whose variable is `LINEAR_MCP_API_KEY`, the name the kitchen-sink's Linear capability reads (`apps/kitchen-sink/lib/mcp.ts`); each person signing in to Linear as themselves is a later epic | FIX-1905 | FIX-1905's tests · its spec review | | ||
| | ER-7 | A server whose credential variable is unset is said out loud, once when the server starts and on each run that misses it. The run still runs, and that is a degraded run, not a pass: with `LINEAR_MCP_API_KEY` unset, the closure's leg a must FAIL its title check ([ER-20](#the-closure)) | FIX-1905 | FIX-1905's tests · the closure, run with the variable unset | | ||
| | ER-6 | No credential, endpoint or credential variable is stored on a project row. A row selects MCP servers by an alias the host approves, and the host config gives each alias its endpoint. The key is each person's own: set on Shift Manager's Settings page, stored as a user-scoped record in the Lab's store, write-only, shown only as set or not set. A run uses its owner's key, resolved from the server-side identity the run records, never from a field a caller sends ([BP-031](../../../docs/contributing/best-practices.md)). FSD holds the MCP connection with that key (`createMcpManager`), and the run gets the servers' tools only: the key is not handed to its command line, environment, MCP config, a log, a session or the page. It is not unreachable: an unsandboxed run can read the Lab's store. The dev profile's host config has one alias, `linear`. `LINEAR_MCP_API_KEY`, the name the kitchen-sink's Linear capability reads (`apps/kitchen-sink/lib/mcp.ts`), seeds only the Lab's operator identity, for headless and CI runs, while it has no stored key. Signing in to Linear by OAuth is a later epic | FIX-1905 | FIX-1905's tests · its spec review | |
There was a problem hiding this comment.
Refresh the end-state figure for per-user keys
When readers use the retained end-state figure embedded by SPEC.md, its figures/end-state.svg aria-label still says the credential lives in host config, contradicting this amended rule that credentials are per-user records and only the endpoint is host-configured. This leaves screen-reader users with the superseded security model, so update the figure and its accessibility text alongside ER-6.
Useful? React with 👍 / 👎.
… with each person's key (#3448) * spec(FIX-1903): end-state figure shows FSD holding the MCP connection with each person's own key The figure still put the run's credential in host config. Amendment #3179 settled that FSD holds the MCP connection and each person sets their own key on the Settings page; the row names a host alias only. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PrPKdauAZJcDc2GUGxNKWS * spec(FIX-1903): end-state figure says no key on the row Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PrPKdauAZJcDc2GUGxNKWS --------- Co-authored-by: Claude <noreply@anthropic.com>


Requested by Jake · project thread
What this changes
This PR changes the merged FIX-1903 epic spec (#3164). It follows the owner's call on FIX-1905's spec review (#3174): "D2 can't be through Claude … provide a settings page which allows keys to be configured", and "let each user set their own key".
The new shape. FSD holds the MCP connection and the key for each run (
createMcpManager). Claude Code gets tools only, through one genericmcpToolsoption. The option takes in-process servers and no URL or headers. Each person sets their own key on Shift Manager's Settings page. The key is a user-scoped record, write-only, and the page shows it only as set or not set. A run uses its owner's key, from the server-side identity.LINEAR_MCP_API_KEYonly seeds the Lab's operator identity for headless and CI runs. Claude Code is first. Cursor and Codex come later.Unchanged. A row names a host-approved alias only, and endpoints are host config (ER-14). Servers are read at run start from the run's own project (D4's chosen option, ER-5, ER-8). OAuth sign-in stays out of scope.
Where
BUSINESS-RULES.mdmcpTools, plus a call path intoolsDECISIONS.mdSPEC.mdPLAN.mdDOCS.mdcredentialEnv. The ownership table adds the Settings pageEVOLUTION.mdThe amended D4 trade-off figure: D4 in
DECISIONS.md.Need your sign-off
Approve this change of direction for the epic? The direction is yours, from #3174. This PR only writes it into the epic. Merging it releases FIX-1905's implementation against the amended rules. Hold FIX-1905's implementation until this merges.
Reviewers · look here
🤖 Generated with Claude Code
https://claude.ai/code/session_01MJsSFWmTXycBXJU4s96Pk1