Skip to content

spec(FIX-1903): epic amendment, FSD holds MCP keys per user - #3179

Merged
jhoffner merged 1 commit into
mainfrom
claude/project-thread-k7msfx
Oct 12, 2026
Merged

jhoffner merged 1 commit into
mainfrom
claude/project-thread-k7msfx

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 12, 2026 •

Copy link
Copy Markdown
Collaborator

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 generic mcpTools option. 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_KEY only 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

Document Change
BUSINESS-RULES.md ER-6: endpoint in host config, key per person, FSD holds the connection, the variable is the operator seed. The text no longer says "never sees it". ER-7: a missing key is said aloud. The closure's leg a must FAIL when neither Settings nor the variable has a key. ER-9: mcpTools, plus a call path in tools
DECISIONS.md D4 Locks in and its figure (re-rendered, both themes). Decided in review records the owner's two calls
SPEC.md The teams row, the set row, Bigger (per-person keys in, OAuth out), the goal's Input, and the control
PLAN.md FIX-1905's row: about 1.5× larger, still one PR. The harness-options seam
DOCS.md The shared Linear sentences, and "Tools a project's coding work gets" without credentialEnv. The ownership table adds the Settings page
EVOLUTION.md A row for the superseded merged statements. LAB-138's row gets its retained source (its spec and #1437)

The 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

  • Does any epic statement still say the key comes from a host variable, or still name a per-run MCP config on the harness?
  • Does ER-7's control in the closure fail without a key in either source?

🤖 Generated with Claude Code

https://claude.ai/code/session_01MJsSFWmTXycBXJU4s96Pk1

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
@linear-code

linear-code Bot commented Oct 12, 2026

Copy link
Copy Markdown

FIX-1903

@vercel

vercel Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 12, 2026 8:01pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 12, 2026 8:01pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 12, 2026 8:01pm UTC

Request Review

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-12T20:05:50.147310Z 3c79a5d Manual request
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Copy link
Copy Markdown
Collaborator Author

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 specs/issues/FIX-1905 for stale statements. The reviewers' first question comes out clean. Nothing in the epic still says the key comes from a host variable or names a per-run MCP config on the harness. LINEAR_MCP_API_KEY appears only as the operator seed or the control. The closure question is covered too: the SPEC control and ER-7 both fail leg a when neither source has a key.

1. ER-6 weakens the old guarantee, and the epic doesn't price that.

  • The old rule kept the value out of the run's environment. The new rule keeps it out of the command line, environment and MCP config, but admits "an unsandboxed run can read the Lab's store". The key is now a file the coding agent can read, in a user-scoped record.
  • A run works Linear issue text, which is untrusted input. An injected instruction could read the store and send the key out.
  • This doesn't block merge, but the amendment should say what happens. Options, cheapest first: encrypt the record at rest with a host-held secret; keep the key records outside the run's worktree and filesystem scope; or state in D4 What would change my mind that unsandboxed runs are accepted for dev profiles only.
  • DOCS.md says the run "could read the server's store" but never says that the key sits in it. A person pasting a key deserves that sentence.

2. FIX-1905 grew past the "one PR" the epic still promises.

  • It now carries a write-only Settings page, a user-scoped key record, an identity-resolved key lookup, an operator seed, FSD's per-run MCP connection, mcpTools on the harness, and the missing-key notice. The PLAN row says "about 1.5×, still one PR".
  • That is a UI and storage slice and a harness slice. The two meet at one interface: the key lookup that feeds createMcpManager.
  • The repo already has a mechanism for this (issue-multi-pr, the spec's PR plan). I'd soften PLAN to "one PR, or two if FIX-1905's spec finds the seam", rather than commit the size now.
  • DECISIONS D1 and the Q-section also pin "FIX-1905 is one PR" as a review-round settlement. This amendment contradicts it quietly, so either amend that bullet or leave the door open.

3. ER-9: "tools gains only a call path on createMcpManager" is unclear.

  • createMcpManager in packages/tools/src/mcp/manager.ts already returns GeneratorTool[] with execute, so a call path exists.
  • Does this mean "a way to construct the manager with a per-run key", or "adapt those tools to createSdkMcpServer"? The first needs no new surface. The second belongs in claude-code, not tools.
  • Name which one, since ER-9 is the layer-boundary rule that FIX-1905's review will cite.
  • Today headers come from config.transport.headers at construction. A per-owner key means one manager per run. The spec should say the manager is closed with the run (close() exists).

4. Dangling link in EVOLUTION.md.

5. Smaller points

  • SPEC Input says the person's key is set "on Settings", and leg a runs "as the dev profile's owner". Say how the closure gets that key onto Settings without breaking the anti-game line "sets no variable a person wouldn't". Pasting via the page in the browser qualifies, and one clause would remove the doubt.
  • ER-7 says the Lab announces once at start "for the operator identity". If the operator has neither a stored key nor the variable, and no project names Linear, that notice is noise. Condition it on a project naming the alias.
  • The "Bigger, and not this epic's" row now calls OAuth out of scope while the key is a pasted Linear API key. The row is accurate. ER-6 also says "Signing in to Linear by OAuth is a later epic". If OAuth lands, per-person identity already exists here and only the credential source changes, so keep the key-record shape source-agnostic. That is worth one line in FIX-1905's seam.

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 claude-code or the harness-manager, each later harness reimplements it. Put it in one host-side function that returns the manager and give harnesses only mcpTools. The epic could state that as an ER-9 corollary now, while it is cheap.


Generated by Claude Code

@jhoffner jhoffner self-assigned this Oct 12, 2026
@jhoffner
jhoffner merged commit 24bd349 into main Oct 12, 2026
20 checks passed

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

  1. FIX-1905 retained spec is not in the tree while ER-6/7/9 and D4 are fully amended here. EVOLUTION.md links to specs/issues/FIX-1905/EVOLUTION.md, which doesn't exist on this branch — implementers only have epic-level prose for Settings UI, collections, and mcpTools wiring. 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.
  2. 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 MAP and --sources from 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 / dispatchTask fields.
  • 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/cursor not kitchen-sink matches ER-11 thinking.
  • Reuse of probeClaudeAccount across 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.

Open in Web View Automation 

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 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?).

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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 |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

jhoffner added a commit that referenced this pull request Oct 15, 2026
… 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants