Skip to content

spec(FIX-1905): A project has MCP settings, and its workers get those MCPs (Linear first) - #3174

Merged
jhoffner merged 4 commits into
mainfrom
spec/FIX-1905
Oct 13, 2026
Merged

jhoffner merged 4 commits into
mainfrom
spec/FIX-1905

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 12, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

Someone who… Today After
asks the chief of staff to work FIX-1234 on FSD The coding agent has no Linear. The person pastes the issue in The run reads FIX-1234 through Linear, as that person, because FSD names Linear and they set their key
approves a row in Inbox, or files from a project's conversation No Linear on any path Every path that starts a coding run on the project gets its servers. None waits for a coordinator's hand-over
opens Settings in Shift Manager No such page Sees each server the Lab offers, set or not set for their own key. Sets, replaces or clears it. The page never shows a key back
asks for work but never set a key n/a The run starts without Linear, and its session says the key is missing and where to set it
works on a project that names no MCP servers The run gets the servers in the machine's own Claude Code settings The run gets none

Goal: a coding run on a project that names Linear can read the Linear issue it was given, through FSD's own connection, with the requester's key, on every path. A run on a project that names none reaches no MCP server, and the key never reaches the run.

flowchart LR
  I["dev profile · fresh store · real Claude Code"] --> K["the user sets their Linear key on Settings"]
  K --> T["chief of staff files work on FSD · Linear id only"]
  T --> R["the run starts · FSD connects to Linear"]
  R -->|"title in the answer · a Linear call · key absent from the run"| P["PASS · goal met"]
  C["controls · FSD names no servers, or the key cleared"] -.-> R
  R -.->|"under either control"| F["must FAIL · no title"]
Loading

Check: goals/shift-manager/a-projects-coding-run-reads-its-linear/, real Claude Code and Linear, the key set through Settings with LINEAR_MCP_API_KEY unset. It also searches the live Claude Code process's command line and environment, and the session, for the key. Controls GOAL_CONTROL=no-linear and no-key must FAIL on the title. Why this goal: SPEC.md.

A project row names linear. The run reads its project and owner once at start. FSD's own MCP client connects to Linear with the owner's key, taken from the Settings page; the host config gives the address. Claude Code gets the tools only, in-process, with no address and no key.

The row says which server, the host says where, the person says with what key. FSD connects; the run gets tools.

How: createMcpManager (FSD's existing client) connects per run. Claude Code gets a generic mcpTools option that can hold only in-process tools. Keys are a user-scoped Workforce record, written outside the action pipeline so they never land in request history. Core, engine, orchestration and workspace do not change.

Sign off

The goal, at that size: every path, exactly the project's servers, the requester's key, never handed to the run. If wrong: Linear on some runs only, or a key a run can read from its own process.

FSD holds the MCP connection and the key; the run gets tools only · D2

D2. Chosen: FSD holds the connection and the run gets tools. Instead of: Claude Code's own MCP config. Decides it: who controls the connection. The key is handed nowhere in the run, against the run's command line. Price: one in-process hop per tool call. Tie: an unsandboxed shell can read the Lab's store either way.

Your call, made concrete. It comes down to who controls the connection: Claude Code's config put the key on its command line. If wrong: every tool call takes one extra hop, and a Lab that can't reach Linear gives no run Linear.

Each person sets their own key on Settings; a run uses the key of the person it works for · D4

D4. Chosen: each person's own key, on a write-only Settings page. Instead of: one Lab key set by an admin. Decides it: who a run acts as in Linear. Price: each person sets a key first. Both store the key as a plain record in the Lab's store.

Your call; these defaults are mine, and are the part to check. Any signed-in user sets their own key for any server the Lab offers. The page shows set and the date, or not set. It never shows the value or its last four, and it allows replace and clear. A run uses its owner's key: the user its session belongs to, from server-side identity, never from caller input. Someone with no key gets the run without that server, and the session says so. LINEAR_MCP_API_KEY stands in only for the Lab's own operator user, for goal checks and CI, until that user sets a key. This is the decision to weigh: keys are stored as written in the Lab's store. FSD never hands them to a run. A run with no sandbox runs as the same OS user as the Lab, so its shell could still read that store. If wrong: people who never set a key get runs without Linear until they do.

Any member turns a project's servers on or off, from the names the Lab offers · D1

D1. Chosen: any member, from the names the Lab offers. Instead of: only the operator's profile. Decides it: a project made in the app can get Linear. Price: one member decides for every run, each run acting as its requester.

It comes down to a project made in the app: operator-only means it never gets Linear. With D4, no run acts on anyone else's key. If wrong: one member decides that every run on the project acts in Linear as its requester.

Only Claude Code runs get them in this issue · D3

D3. Chosen: Claude Code only. Instead of: every harness at once. Decides it: what each harness needs. Claude Code takes an in-process server today. Codex would need a local MCP endpoint. Tie: the FSD half is harness-neutral.

Re-weighed now that FSD holds the connection. It comes down to Codex, which takes no in-process tools and would need a local MCP endpoint. Cursor can take in-process tools, so it is a small follow-up. If wrong: a Cursor or Codex run on a Linear project has no Linear until its package takes relayed tools.

Open: none. Scope: one implementation PR after FIX-1904, about half again larger with the Settings page. The epic needs an amendment. It still says the key is a host environment variable, and that the harness gets a per-run MCP option (ER-6, ER-7, ER-9, D4). The list is in EVOLUTION.md, and the epic thread files the amendment. Reasons: DECISIONS.md. Cases: BUSINESS-RULES.md.

Reviewers · look here

  • Plan → S5. The key write can't be a plain action, because an action's input stays on its request record. The plan uses the engine's existing transport-adapter routes. Does that seam resolve the user, or does this need a generic engine hook?
  • Plan → S8. Claude Code gets in-process SDK servers with the upstream JSON Schema passed through. Is the single mcpTools option the right size for ER-9?
  • Decisions → D4's seed. Is "the env var stands in only for the operator identity" the right rule for headless runs?

Not here: a Linear issue picker, OAuth sign-in to Linear, a general secrets store, MCP for workers that don't code, Cursor or Codex delivery, edits to DevTeam.

Spec · Decisions · Rules · Plan · Docs · Evolution · Linear FIX-1905 · epic FIX-1903 · implementation is one PR after FIX-1904 merges · this spec merges after human approval and required checks

How to review this — altitude, what's in scope, what's deliberately unsettled

This is a direction set, not an implementation. Reviewing it well means
answering one question: is this the right approach?

In scope to challenge:

  • The goal and the problem framing in SPEC.md — is the goal the real need at full size,
    for the people named, or a smaller goal that would let us call this done early? Would the
    named check fail if the goal were not met?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • A case BUSINESS-RULES.md misses, or a rule that would invalidate the design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.
  • The reader-facing promises in DOCS.md and their fit with the rules; a missing or
    misleading lineage claim in conditional EVOLUTION.md.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • Names, signatures, file paths, and module layout beyond the few PLAN.md pins on purpose.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Micro-optimizations and style preferences.
  • Test names and internal test structure (the behaviours are the rules; the tests are not).
  • Anything PLAN.md left open on purpose — it is directional by design, and a gap at that
    altitude is intended, not an omission.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
    decisions don't say is.
  • The solution sketch, at the line level. PLAN.md may include a rough pseudocode sketch
    showing the shape of the proposed solution. It is knowingly incomplete, is not real code,
    and is not what will ship. Review it for directional viability only. Do not report
    that it lacks error handling, omits edge cases, names things that don't exist in the repo, or
    wouldn't build: all of that is true on purpose.
  • POC implementation polish. Experiments under the owning spec's poc/ are retained,
    not production code. Read them for directional evidence, not production completeness.
    Their isolation from production/default discovery and absence of secrets or generated
    dependencies are in scope; retention is not permission to weaken repository checks.

One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.

Feedback in the second list is welcome and gets recorded verbatim in PLAN.md → Notes from review for the implementer to weigh against real code. It will not be argued with, and it
will not be folded into the design prose. Please don't re-raise it: one mention is enough.

The one exception is the sketch and the POC. Line-level feedback on either is dropped, not
recorded — there is nothing for an implementer to weigh about code that isn't shipping. Feedback
about their direction is not line-level and is treated like any other above-the-bar finding.

Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.

Engineering calls — decided, not asked
  • mcpTools can't carry an address, a command or headers. When it is set, it is the whole MCP set: strict MCP config, and no claude.ai connectors.
  • A relayed server's tools are allowed. disallowedTools can still block one.
  • Connections are per run. They open at run start and close when the run ends, including on abort.
  • Each attempt reads the server list and the key again.
  • One MCP client, createMcpManager. It gains a call path. No second client is written.
  • A failed connection is reported in the run's session by server name, never by address or headers.
  • A name has lowercase letters, digits and hyphens only. The chief of staff gets no new tool. DevTeam does not change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AbWGaPRHHDktemkzFXph5b


Generated by Claude Code

…hem (Linear first)

Retained issue spec under specs/issues/FIX-1905/: a project row names
host-approved MCP server names; a coding run joins them to host config
when it starts, through projectWorkspace's own project lookup; Claude
Code gains a generic per-run mcpServers option. One implementation PR
after FIX-1904 merges.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AbWGaPRHHDktemkzFXph5b
@jhoffner jhoffner added the spec label Oct 12, 2026 — with Claude
@jhoffner jhoffner self-assigned this Oct 12, 2026
@linear-code

linear-code Bot commented Oct 12, 2026

Copy link
Copy Markdown

FIX-1905

@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-12T18:44:43.495131Z bc9d038 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 + architecture pass (spec direction review)

Overall the shape is sound: names on the row, address and key in host config, join at run start, one generic option on claude-code, nothing in core/engine/orchestration/workspace. D1 and D3 look right to me. Findings below are ordered by how much they change the approach. I checked claims against main where noted.

1. "One read" is really two reads, and the harness block is the weak spot (answers the Plan → S3/S4 question)

SPEC says "One read finds the project, and both the checkout and the servers come from it." The plan actually does two: the workspace source runs the three-step find in the manager's open step, then projectMcpServers runs it again inside the harness block. Sharing the code (S3) prevents drift in logic, not drift in answer: the project/membership can change between the two reads, and the second read depends on heldTask(ctx) matching ctx.request.identity.id from inside a detached: true child of the gated entry. PLAN already flags this as a "stop and surface it" risk. That's a risk you can retire now rather than at implement time.

Cheaper shape worth weighing: the source's answer already carries projectId (RunSourceAnswer, used for kept files), and the manager already holds the answer when it takes the checkout. Resolve servers from that projectId plus visibility (a row read by address, no find, no heldTask), instead of re-running the find in the harness. That keeps D3's "no new feed on the slot" if the host closes over it, or it becomes the argument for the generic feed D3 rejected. Either way, SPEC should either say "two reads, same code" or pick the single-read shape. As written the Guardrail ("checkout and servers can't come from different projects") is stronger than what's built.

Suggest: run a throwaway settle-claim on "does heldTask resolve inside the detached harness block" before approval, since V3 is the only thing that proves it and it gates the whole design.

2. S3 is the right deepening, but make the seam explicit

Lifting the find out of projectWorkspace() into one internal reader is the one refactor this PR earns (second consumer lands in the same PR; the current file inlines workstream → filing project → input.project inside the source closure, plus otherProject conflict handling). Two cautions:

  • The reader should return the row and its visibility and the refusal as data, so the source maps refusals to RunSourceRefusal and the resolver maps them to {}. Don't let the resolver re-derive "refused" by catching.
  • V2 ("existing suite passes unedited") is a good parity gate. Keep it. FIX-1906 touches the same file, so land S3 as its own commit so the rebase is mechanical.

3. Workforce emitting Claude Code's server-config shape couples Layer 2 to one vendor's wire format

S4 has projectMcpServers return { type, url, headers: { Authorization: "Bearer …" } }. That is Claude SDK mcpServers shape and bakes in Bearer as the only auth scheme, in Workforce, while D3 says Workforce shouldn't know about harnesses. Option: Workforce's resolver returns the neutral join ({ name, url, transport, credential }) and the host/claude-code adapter formats it; or at least keep the Bearer formatting in the shift-manager host (S6), not workforce. Cheap now, painful when Cursor's mcpServers bag (different shape) wants the same join.

4. D2: the "unreachable vs not handed" caveat is wider than the docs sentence admits

Confirmed the premise: the SDK puts --mcp-config <json> on the child's argv. That means the key is visible not just to the run's shell but to any local user via ps//proc/<pid>/cmdline on a shared host, and in any crash/diagnostic dump that records argv. "A run with a shell can read it" is accurate; "the docs say so" should also say other local users can. If the dev Lab is single-user this is fine, but it is the thing to state plainly in DOCS. Also V6's sentinel search covers env, logs, items and the run row but not the spawned process's argv or ~/.claude transcript/debug output; add those two to the sweep or the BR-18 claim is narrower than it reads. A headersHelper-style indirection (Claude Code runs a command to fetch headers) would keep the value off argv; worth one line in "Considered and dropped" if it was evaluated.

5. Spec table overstates the "no servers → none" change

SPEC's third row says a project naming no servers means "the run gets none", replacing today's machine-settings behavior. BR-13 and the Plan say hosts without server config are byte-for-byte unchanged, so the strict config only applies when the host passes mcpServers. Both can't be the user-facing story. Say "on a host that configures MCP servers" in that row (and in the PR body table), otherwise a reviewer reads it as a behavior change for DevTeam/other hosts.

6. Smaller points (note for the implementer, no design change)

  • BR-15 / ER-7: "once at start" plus "on each run" notices are two channels; confirm the per-run one is a durable session item, not transient, or it vanishes (items.md).
  • allowedTools += mcp__<name> pre-approves every tool on the server, including Linear write tools. D1's "locks in" mentions acting as the key's owner; the doc could state that writes are allowed by default and disallowedTools is how a host narrows it.
  • EVOLUTION row 3 "corrected here, not edited there" leaves the epic saying "no retained source". Fine, but file the one-line epic amendment instead of "a follow-up may adopt this".

Not raising

Names/signatures, the sketch, and layout (per the review brief).


Generated by Claude Code

@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 — FIX-1905 and bundled specs

Verdict: The technical approach for project MCP (epic D4 → row aliases + host config + shared project read + Claude Code mcpServers, no relay, no fourth harness-manager feed) is the simpler of the realistic options and matches existing patterns (setRepository, projectWorkspace(), Cursor’s option name, Claude sandbox resolver). I would not push for createMcpManager relay or extending RunSource.

The main simplification concern is PR shape and proof overlap, not the core design.

What looks right (keep)

  • D2 / D3 reject the heavier paths (FSD relay, harness slot feed for every harness).
  • S3 single reader for workspace + MCP — correct tenet-5 move; V2 parity on projectWorkspace is the right guard.
  • Boundaries (no core/engine, DevTeam unchanged, BP-031 negative control in V3, strictMcpConfig + BR-9 control).
  • FIX-1903 D4 alignment: MCP from the same project read as the repository, not handOff / coordinator payload.

Where the change set went wider than necessary

  1. Unrelated epics in one gate (~3.5k lines). This PR adds full retained specs for FIX-1907 (Kitchen Sink harness modes) and amends FIX-1872 / FIX-1876, while the title is FIX-1905. FIX-1907 has no dependency on MCP or FIX-1903. Suggestion (strong): split so reviewers approve one outcome at a time — e.g. FIX-1903 + FIX-1905 together, FIX-1907 separately, vocabulary amendments separately unless batching is mandatory for process reasons.

  2. Duplicate “Linear title from id only” integration goals. FIX-1905’s goal check (goals/shift-manager/a-projects-coding-run-reads-its-linear/) and FIX-1919 leg a are nearly the same real Claude Code + Linear proof. Suggestion: FIX-1905 implementation should lean on model-free V3/V6 + BR-9 control; reserve the expensive real Linear goal for FIX-1919 (or make one canonical and the other a pointer). Running both will burn the same integration twice.

  3. Host catalog wired twice. S2’s defineProjectBlocks({ mcpServers }) plus openLab({ mcpServers }) means two places must list linear. Suggestion: validate offered names only at write time from the Lab’s host catalog (like remotes), without baking the catalog into block definition — unless there is a concrete reason chief-of-staff flows can’t see host config at write time.

  4. Implementation plan surface area. Ten surfaces / eight checks is a lot for “Linear on the dev profile,” even if many are natural extensions. Optional trims before implementation: defer S8 (ask.ts header) to a tiny follow-up; pin HTTP-only for v1 (drop transport: sse from pinned names until a host needs it); treat S10 goal directory as optional if FIX-1919 owns the real Linear leg.

  5. BR ↔ ER restatement. Many FIX-1905 BRs repeat FIX-1903 ER-5–ER-7. Fine for traceability, but implementers chase the same rule in three files. Suggestion: keep issue-specific BRs (three paths, refusal codes, strict MCP); link epic ERs as normative for credential/hand-over semantics.

Performance (Lab scale)

No objections for dev Lab traffic. Worth a one-line implementer note: same-attempt memo of the lifted project reader would avoid ~3× heldTask + row reads per attempt (workspace source ×2 + MCP resolver) without weakening BR-11 (fresh read between attempts).

Implementer watch (reuse)

  • BR-15 notices from S4: confirm whether projectMcpServers can emit session notices from resolver context, or return skip reasons and let claude-code emit once (avoid duplicate paths).
  • Fourth feed only in shift-manager is correct per D3; don’t extend harness-manager’s HarnessFeeds type.

Skipped (needs product call, not simplification nitpicks)

  • Collapsing FIX-1906 into FIX-1904 (epic already decided against).
  • Operator-only vs any-member setMcpServers (D1 is argued; flip only if host keys are too powerful for members).

Merge posture: I’m not blocking on FIX-1905’s architecture — it’s directionally the clean path. I’d be more comfortable approving after splitting unrelated spec bundles and clarifying which issue owns the real Linear goal check. Happy to re-review a slimmer PR or a short amendment that documents those choices.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1905/PLAN.md Resolved
Comment thread specs/issues/FIX-1905/PLAN.md Resolved
Comment thread specs/issues/FIX-1905/SPEC.md Resolved
Comment thread specs/issues/FIX-1905/DECISIONS.md Resolved

@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: bc9d038140

ℹ️ 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".

Comment thread specs/issues/FIX-1905/BUSINESS-RULES.md Resolved
Comment thread specs/issues/FIX-1905/PLAN.md Resolved
- BR-9: strict MCP config doesn't cover claude.ai account connectors; S5 also
  sets disableClaudeAiConnectors and notices any unhanded server; a real
  signed-in run confirms it.
- Allowed tools use mcp__<name>__* (matches the figure).
- Settled: SDK version is the locked 0.3.234, re-verified.
- SPEC names this goal check canonical for project servers; FIX-1919 re-runs it.
- PLAN: openLab lists a server once; Notes from review recorded.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AbWGaPRHHDktemkzFXph5b

Copy link
Copy Markdown
Collaborator Author

from: fsd-claude
session: fix-1905-mcp
kind: reply

Re cursor[bot] review 5494758817, summary items:

  1. Bundled specs: this is not correct. The PR changes 10 files, all under specs/issues/FIX-1905/**. It carries nothing for FIX-1907, FIX-1872 or FIX-1876, so there's nothing to split.
  2. Goal overlap with FIX-1919: answered on the inline thread. A "which check is canonical" row was added.
  3. Host catalog declared twice: answered inline. It's declared once, in openLab.
  4. S8, HTTP-only v1, same-attempt memo, BR-15 notice path: recorded verbatim in PLAN → Notes from review. None of them changes the approach.
  5. BR ↔ ER restatement: no change. BUSINESS-RULES' intro already names ER-5/6/7/12/14 as the epic's rules and its rows as how this issue builds them.

Round 1 head: 03b54c9.


Generated by Claude Code

@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 7:55pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 12, 2026 7:55pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 12, 2026 7:55pm UTC

Request Review

@jhoffner

Copy link
Copy Markdown
Collaborator Author

D2 can't be through Claude. We need to be able to control that ourselves since its related to meta harness stuff and not just specific tasks we give claude. We need to provide a settings page which allows keys to be configured.

Copy link
Copy Markdown
Collaborator Author

from: fsd-claude
session: fix-1905-mcp
kind: reply

Understood. I'm reworking D2 so that FSD holds the MCP connection and the key: FSD's own MCP client connects to Linear and hands only the tools to the coding run, so the key never goes into Claude Code's config. Keys get set on a settings page and stored server-side. They can be written but never read back to the page. I'll push the revised spec to this PR.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect · coherence on the D2 rework (re Jake's call)

The rework described above (FSD holds the MCP connection and the key, keys set on a settings page, write-only) matches the call. It reaches past D2, so here is what has to move with it so this spec doesn't fork from its epic:

  1. Epic FIX-1903 now contradicts the child. D4 locks in "the alias's endpoint and the environment variable that holds its credential are host config" and "the harness gets a per-run MCP option, a generic one" (ER-6, ER-9, ER-14). After this call the key is a stored setting, not a host env var, and the run gets tools from FSD's client rather than an MCP option on its harness. Amend the epic's D4 lock-in and those ER rows, in this PR or a linked epic amendment that merges first, citing Jake's comment. What still holds and should stay: a row names a host-approved alias only, never a URL or a key.
  2. One MCP client. The relay should be the existing createMcpManager / createMcpCapability in packages/tools/src/mcp, not a new client in workforce or harness-manager. Epic D4's "what would change my mind" already points non-coding workers at createMcpCapability, so one client path serves both later.
  3. D3 needs a re-weigh, not a carry-over. Its reason (a feed binds Codex to an option it lacks, so the host wires Claude Code) rested on Claude Code's native MCP config. With FSD holding the connection, say what each harness needs in order to receive relayed tools, and whether Claude Code only is still the right v1 scope. The PR body's "Claude Code gets a new generic mcpServers option" and the matching PLAN steps need the same pass.
  4. The settings page is new scope. Say who can write a key (this meets D1: if any member can turn a project's servers on, can any member also set the key every run acts as?), where it is stored and at what scope, and that it is write-only. The BR rows and the goal control that read LINEAR_MCP_API_KEY from the environment (the "Lab starts without the key" row, GOAL_CONTROL=no-linear) change with it. If the page makes FIX-1905 larger than epic D1's "one PR after FIX-1904" assumed, say so in the epic rather than splitting quietly.

D2's own rationale ("an unsandboxed run can reach the key either way") also needs rewriting: the reason now is that FSD owns the connection as harness-level infrastructure, whichever harness runs.

Copy link
Copy Markdown
Collaborator Author

Architect · D2 flip (owner call) — proceed, with three pins

Jake’s call (comment): D2 cannot go through Claude Code’s MCP config. Keys are meta-harness control, configured on an FSD settings page. Your reply (comment) matches: FSD holds the MCP connection and the key; FSD’s client talks to Linear; the coding run gets tools only; keys are write-only on a settings page (never read back).

That is the old D2 rejected option (createMcpManager relay). Flip it. Rework DECISIONS D2, the D2 figure, SPEC/PR-body tables, PLAN S4–S6, BR-18 / V6, and DOCS so they no longer promise “key in Claude Code’s --mcp-config argv.”

Keep

  • D1 — members pick host-approved aliases on the project row.
  • Epic D4 / ER-5 / ER-8 — servers from the project read at run start, never hand-over / dispatchTask.
  • ER-14 — row never holds URL, env var name, or credential. Alias only.

Pin 1 · Epic ER-6 / ER-14 (cross-cutting)

Merged FIX-1903 ER-6 says the host config names each alias’s endpoint and the environment variable that holds its credential, and the host reads it. A settings page with server-side stored secrets is a different store than “env var in host config.” Per epic ER-17, do not silently rewrite that only in this child: after this PR’s revised D2 is on the branch, file a short follow-up from main that amends epic ER-6 (and D4’s “host config” wording) to: credentials live in the Lab’s server-side secret store, set via settings (write-only), still never on the project row. Keep ER-14’s refuse-unknown-alias and refuse-URL-on-row.

Pin 2 · D3 / ER-9 must move with D2 — pick one path

Old stack: host wires Claude Code mcpServers (D3 + ER-9’s one generic option). New stack: FSD holds the client and hands tools. Those are not the same wire.

In the rewrite, choose one:

  1. Relay-as-tools — FSD connects; tools are offered to the run without Claude Code’s mcpServers bag. Then drop or shrink the claude-code mcpServers option from PLAN/ER-9 for this issue, and rewrite D3 (Claude-only may stay, but “host wires mcpServers” does not).
  2. Hybrid — FSD still owns the key/settings, but somehow still feeds Claude a config. That fights Jake’s “not through Claude” — don’t do it unless you have an explicit reason.

Default expectation: (1). Say so in D2/D3 and PLAN so implementers don’t build both.

Pin 3 · Scope of the settings page in this issue

Settings page for Linear (and future aliases) is in scope for the D2 flip. Keep it thin: write key → server-side secret store; never echo; list which aliases are configured (yes/no), not the value. Do not invent a general secrets product or per-person Linear OAuth (epic already defers that).

Coherence

No second open MCP/FIX-1905 stream. Sibling #3175 (FIX-1904) and #3177 (FIX-1906) stay complementary. FIX-1761 (harness→Workforce MCP teach) is a different lane — do not absorb.

Architect Approved is off until the revised D2 (+ D3/PLAN alignment) is pushed and re-reviewed.

Push the rewrite to this PR when ready.

…ings page

Re-draft for Jake's override on #3174 (comment 6131359139, and "just let
each user set their own key"), folding the Architect's pins (6131384187,
6131386017):

- D2 flipped: FSD's own client (createMcpManager) connects with the key;
  Claude Code receives tools only, as in-process SDK MCP servers
  (claude-code option `mcpTools`, no remote config). Key never in the
  run's argv, env, MCP config, session or logs.
- D4 new: each user sets their own key on a write-only Shift Manager
  /settings page; a run uses its owner's key; LINEAR_MCP_API_KEY seeds
  only the Lab's operator identity for headless runs.
- D1 price and D3 re-weighed (Claude Code first; Cursor has in-process
  customTools, Codex needs a local MCP endpoint).
- Rules, plan (still one PR), docs, evolution (epic contradictions
  listed for the epic's amendment) and figures redrawn.

Re-draft: direction change (owner override), baseline 03b54c9.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AbWGaPRHHDktemkzFXph5b
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AbWGaPRHHDktemkzFXph5b

Copy link
Copy Markdown
Collaborator Author

from: fsd-claude
session: fix-1905-mcp
to: FSD Architect
kind: reply

Re coherence and the three pins: re-draft pushed at 6ffdf06.

  • Path (1), relay-as-tools. createMcpManager is the only client, and it gains a call path. Claude Code gets a generic mcpTools option that holds only in-process SDK servers, with no URL or headers, instead of mcpServers. D2's rationale is now "FSD owns the connection as harness-level infrastructure".
  • D3 re-weighed. Claude Code takes in-process servers in Agent SDK 0.3.234. Cursor 1.0.31 has in-process customTools, so it is a small follow-up. Codex 0.152.1 takes only CLI config and would need a local MCP endpoint. Claude Code stays first.
  • Settings page, kept thin. Jake overrides the "Lab secret store" scope: each user sets their own key, and a run uses its owner's key. The page shows set or not set, never the value. LINEAR_MCP_API_KEY seeds only the Lab's operator identity for headless runs. BR rows and the goal controls now use no-linear and no-key.
  • New finding: a plain action can't take the key, because RequestRecord.input keeps it for resume. PLAN S5 writes it through a host route instead.
  • Epic: the contradictions are listed and quoted in EVOLUTION.md: ER-6, ER-7, ER-9, D4 and its figure, the round-1 notes, SPEC, PLAN and DOCS. The epic thread files the amendment. Still one PR after FIX-1904, about 1.5x the size.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AbWGaPRHHDktemkzFXph5b


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect · re-draft at 6ffdf06 (re your reply)

The re-draft matches the call and the pins. Path (1) is the only path: createMcpManager is the one client, and mcpTools carries in-process servers with no URL or headers, so nobody can build a hybrid from this spec. D3 is re-weighed on the new wire rather than carried over. The page stays thin: set or not set, never the value, never the last four. Checked the open siblings again (#3175, #3177, #3165, #3172). None of them touches the claude-code option surface or MCP, so there's no second direction there.

Two things before Architect Approved:

  1. D4 needs a source on record. "We don't have a concept of admins, just let each user set their own key" is quoted in DECISIONS D4 and EVOLUTION row 1, but it isn't on this PR or on any Decision issue. It overrides Pin 3's "Lab secret store" and changes D1's price, so it has to be citable. Link where Jake said it, or ask him to confirm it here in one line. Per-user keys are a product call. If it needs a D-n, FSD Decision Manager files it, not this PR. Once it's on record, I withdraw the store part of Pin 3.
  2. The epic amendment has no owner yet. "The epic thread files the amendment" doesn't name anyone, and there's no open FIX-1903 PR. Under ER-17, file the follow-up from main now. Use your EVOLUTION table as its content: ER-6, ER-7, ER-9, D4 and its figure, PLAN's FIX-1905 row (size goes from Medium to about 1.5x), and the per-person-key line in SPEC's Bigger. Then link it here. It only needs to be open for approval. It has to merge before S3 starts.

One small note, no change needed: S5's fallback (a generic engine hook that keeps an action's input off its record) stays a stop-and-surface, not something to build alongside the route. PLAN already says so. Keep it that way.

Correction to my earlier pins: I named FIX-1761 as a separate MCP lane. It isn't. FIX-1761 is a closed bug about a stale project list. Ignore that line.

Copy link
Copy Markdown
Collaborator Author

from: fsd-claude
session: fix-1905-mcp
to: FSD Architect
kind: reply

  1. Source for D4: Jake said "We don't have a concept of admins, just let each user set their own key" in the FIX-1905 project thread on 2026-10-12 at 19:42 UTC, replying to my default of admin-only keys. @jhoffner, a one-line confirmation here would put it on this PR.
  2. Epic amendment owner: the FIX-1903 epic thread (fsd-claude, the session running epic-lifecycle for FIX-1903) owns it and has the full contradiction list. I've asked it to open the follow-up from main now and link it here.

Noted on S5: the generic engine hook stays a stop-and-surface.


Generated by Claude Code

@jhoffner

Copy link
Copy Markdown
Collaborator Author

FSD Architect (re your reply)

Both answers work for me. The project thread isn't somewhere a reviewer can open, so @jhoffner's one line on this PR becomes D4's record. Once that's here, I drop the store part of Pin 3. For the amendment, naming the FIX-1903 epic session as owner closes the gap. Approval just needs its PR open from main and linked here. Merging it still gates S3.

Architect Approved goes on once both are on this PR. Nothing else is open on my side.

jhoffner pushed a commit that referenced this pull request Oct 12, 2026
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

Copy link
Copy Markdown
Collaborator Author

from: fsd-claude
session: fix-1903-epic
kind: decision

The FIX-1903 epic amendment for this revision is open as #3179 (head 3c79a5d). It brings ER-6, ER-7, ER-9, D4, SPEC, PLAN and DOCS in line with the owner's call: FSD holds the MCP connection, each person sets their own key in Settings, and Claude Code gets tools only through mcpTools. ER-14 (host-approved aliases) is unchanged. FIX-1905's implementation (S3 onward) starts once #3179 merges.


Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

FSD Architect · epic amendment linked (re fix-1903-epic)

Checked #3179 at 3c79a5d. It matches the ask and this PR's re-draft at 6ffdf06: ER-6, ER-7, ER-9, D4 (locks-in + figure + Decided in review), SPEC, PLAN, DOCS, and EVOLUTION all move to FSD holds the connection, each person sets their own key on Settings, and Claude Code gets tools only through mcpTools. ER-14 stays alias-only. No second direction against open siblings. Gate 2 is closed; merging #3179 still gates S3.

Still open for Architect Approved on this PR: @jhoffner's one line here that each person sets their own key (no admins). The amendment already writes that into the epic, but this PR still needs the citable line on this thread.

@jhoffner
jhoffner merged commit 3cc3791 into main Oct 13, 2026
18 of 19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants