Skip to content

spec(FIX-2615): epic spec — MCP connectors and what a project is - #5010

Open
jhoffner wants to merge 5 commits into
mainfrom
epic/mcp-connectors-and-projects
Open

jhoffner wants to merge 5 commits into
mainfrom
epic/mcp-connectors-and-projects

Conversation

@jhoffner

@jhoffner jhoffner commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

A team that… Today After this epic
runs a host with no projects (Teammates lab) No worker or run can reach Linear The host installs Linear once and enables it outside projects
works in projects Claude Code runs get the project's servers. Codex and Cursor runs get nothing Runs on all three harnesses get the project's connectors
keeps its own key The error report keeps a short key in clear text (FIX-2012) One rule removes a key everywhere, and a check proves it
builds the next workforce feature "Project" and "MCP server" are defined only in code One contributor reference defines both

Goal: a host installs a connector once, and a worker or a coding run reaches it with its own user's key, with or without a project. No key reaches a run, a prompt or a response.

flowchart LR
  H["a host · Linear installed as a connector · a canary key"] --> L1["leg a · Teammates · no project"]
  H --> L2["leg b · Shift Manager · a project enables it"]
  L1 -->|"a worker and a coding run read an issue"| S["scan everything that left the server"]
  L2 -->|"runs on all three harnesses read it"| S
  S -->|"the canary is found nowhere"| P["PASS · the epic's goal is met"]
  C["controls · today's main · a project that does not enable it"] -.-> L1
  L1 -.->|"under the control"| F["must FAIL · no tool to call"]
Loading

The closure issue FIX-2646 runs this check. Today's main must fail leg a and the scan. A planted canary must make the scan fail. Why this goal.''``

What's in the box: connectors installed at the host, enabled by a project or by the host with no project, one resolution for workers and all three harnesses, one redaction rule. Fence: a run gets tools, never a key. Not built: FSD as an MCP server, OAuth, servers beyond Linear, core or engine changes

The box is the one model every host gets. The fence is the key rule.

Why now. The Teammates lab needs a tracker and has no projects. MCP shipped only through a project, so each new app must choose a side of that gap. FIX-2331 also waits for these definitions.

The set: two features, one bug and a closure. FIX-2645 adds connectors, with or without a project. FIX-1986 adds Codex and Cursor runs. FIX-2012 makes one redaction rule. FIX-2646 is the closure. As of 2026-11-10, all 4 are in Backlog. Live table.

Who owns what: six rules by four issues and the coordinator, each rule with exactly one owner

Each rule has one owner. FIX-2645 owns the model and the key path.

Sign off

The goal, at that size: with or without a project, on every harness, with a key scan on every route. If wrong: Codex and Cursor runs still get nothing, or a key leaks on a route that nobody checked.

The set's debt: about flat. The set removes a gate, a relay gap and a rule. It adds one host option, one renamed field and Codex's endpoint. If wrong: the next app copies Kitchen Sink's second MCP route.

These three calls are yours. Each one is my recommendation.

A project is a body of work, and a project with no repository is first-class · D1

D1 trade-off figure: a body of work, recommended, beside a repository and a settings bag.

The deciding row is work without code. A project that must have a repository refuses that work, and you chose to keep it on 2026-10-04. If wrong: the next epic must redraw stored data.

MCP goes to workers' models and to coding runs on every harness, with no project needed · D2

D2 trade-off figure: both, on every harness, recommended, beside coding runs only and workers only.

The deciding row is work that names an issue. With one side only, someone must paste the issue across. If wrong: we build a Codex endpoint that nobody uses.

With no project, the host enables a set of connectors itself · D3

D3: the host enables a set, recommended, beside all installed on and a hidden default project. Decides it: a host that already has projects

The deciding row is a host that already has projects. If all connectors are on, every Shift Manager conversation outside a project gets Linear, and nobody asked for that. If wrong: one host option to widen later.

What would change my mind: no app we plan has work without code (D1). Nobody runs Codex on project work (D2). A host needs a connector for only some users outside projects (D3). DECISIONS.md.

Analysis: right approach. The pass moved allow onto the connector so both routes obey it. I ran it in my own context, because this dispatch had no sub-agent. Analysis.

Reviewers · look here

  • FIX-2331 is separate. It is the other direction: FSD as an MCP server. The seam is in DECISIONS → Coordination seams. Should the two epics be one?
  • ER-3, the key path. If a harness cannot take relayed tools, it gets no connector. It never gets the key.
  • Is it three children or two? The collapse trigger: if Cursor needs only one line, Cursor goes into FIX-2645.

Not here: the approach of a single issue. The spec-set PR covers each one.

Spec · Decisions · Linear FIX-2615 · Project: MCP · merges after human approval and required checks

How to review this — an epic-spec, not an implementation plan

This is an epic-spec: the shared objective and cross-cutting decisions for a set of
issues, in a retained document set. It is not any one issue's implementation design, and it
is not a schedule.

In scope to challenge:

  • The objective and the goal in SPEC.md — is this body of work worth doing, and is the
    goal the real need at full size, or a smaller one the set could meet while the need stays
    unmet? Would the closure issue's check fail if the goal were not met?
  • Whether the set overbuilds. Each issue can earn its place while the whole is too much.
    That question can only be asked here.
  • The set's debt in SPEC.md — something the set overlaps and doesn't name, or adds and
    doesn't list.
  • Builds on / Adds in that same section — an Adds item that does not name the existing
    piece it considered, or that is a second mechanism for something we already have
    (orchestration.md).
  • A cross-cutting decision in DECISIONS.md — shared surface, naming, sequencing, contracts.
  • A rule in DECISIONS.md → Who owns what with no owner, or two.
  • A missing issue the objective implies, or one in the set that doesn't serve it.

Out of scope — owned by the individual issue specs:

  • Any single issue's approach, architecture, file layout, or test plan.
  • Anything that touches exactly one issue. It belongs on that issue's spec PR.
  • The figures, at the pixel level, and routine status movement since the dated snapshot.
  • POC production polish. End-state experiments under the owning spec's poc/
    show shape and scoping, not shippable implementation. Directional evidence, experimental
    isolation and absence of secrets/generated dependencies remain in scope.

Feedback in the second list is routed to the issue it concerns as an implementer note, not
folded in here.

Required repository checks, approvals and review-thread policy still govern merge.
Optional comments are triaged, not a reason to grind to zero or restart the design review.

https://claude.ai/code/session_01NczDiGthqcWLSoHxXN7UFG


Generated by Claude Code

The epic set for FIX-2615: a host installs MCP servers once as named
connectors, a project enables some from that set, a run with no project
gets the host's own set, and a key reaches no run, prompt or response.
Two features (FIX-2645, FIX-1986), one bug (FIX-2012) and the closure
(FIX-2646). FIX-2331 stays a separate epic, with the seam named.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGthqcWLSoHxXN7UFG
@vercel

vercel Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
flow-state-dev-build-site Ready Ready Preview Nov 19, 2026 7:22pm UTC
flow-state-dev-docs Ready Ready Preview Nov 19, 2026 7:22pm UTC
1 Skipped Deployment
Project Deployment Actions Updated
flow-state-dev-ui Ignored Ignored Preview Nov 19, 2026 7:22pm UTC

Request Review

@linear-code

linear-code Bot commented Nov 10, 2026

Copy link
Copy Markdown

FIX-2615

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-10T21:17:35.842841Z 91df63e New commits
ℹ️ 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 (read-only review of the epic spec)

I checked the spec's code claims against packages/workforce/src. They hold: allow sits on projectMcpCapability options and not on projectMcpTools, planProjectMcp returns early when runProjectOf finds no project, and redact.ts has MIN_SECRET = 8, so a 7-character canary does slip through. The approach is sound: it extends two shipped mechanisms instead of adding a third. Findings below are in priority order; none blocks the direction.

1. The leg-a check can pass for the rejected smaller goal (should fold)

Leg a's signal says the worker and run call the tool "with the operator's key". The spec rejects "Teammates gets Linear via an env key" because it hands every user the operator's key. But the control list has no case that tells the two apart. Add a control: a non-operator user with no stored key, outside a project, must get no connector, and the test server must record no call carrying the operator's key. Without it, the smaller goal passes leg a. The spec's own sentence ("its check reads which user's key the server received") needs this case to be true.

2. ER-3 fences the key but not the Codex relay endpoint (should fold into ER-3 or FIX-1986's brief)

Codex needs a local endpoint FSD serves. The key never reaches the run, but the endpoint hands key-backed tool calls to anything that can connect to it. ER-3 and the scan do not cover that. Recommend recording as a rule for FIX-1986 now: loopback only, a per-run bearer token, and a closure control that a call without the run's token must fail. This is cheap to write now and expensive to find at the closure.

3. The mcpServers → connectors rename touches more than the stored row (implementer note, maybe a sequencing call)

project-writes.ts has mcpServers in a model-callable write schema (lines ~84, 123), the defineProjectBlocks({ mcpServers }) host option (~150), and the stored row. The spec's BP-030 note covers the dual-read of stored rows. It does not say what the write-side tool input does with the old key. BP-030 asks for the old shape to be tolerated or rejected loudly. Pick one for the tool input, and say so in FIX-2645's spec. Also consider landing the rename as its own commit inside FIX-2645, so a revert of the no-project read does not drag the rename with it. The analysis rejected splitting it into a separate issue, and I agree. A separate commit costs nothing.

4. Three layers narrow a tool list (worth naming, no change)

After this epic a tool's reachability is decided by the host's set or the project's list, then the connector's allow, then the worker file's narrowing. The "narrow, never widen" rule is stated for the last two. State the order once in the reference doc so the next reader does not have to rebuild it from three files.

5. Leg a uses Claude Code, but the Teammates lab's default is Cursor (note)

The spec says that default is Cursor and that it only reaches the connector after FIX-1986. Leg a therefore proves the lab's non-default harness. That is fine for the closure since leg b covers all three, but the spec's table row 1 ("every worker and run can use it") reads wider than leg a checks. Either narrow the sentence or add a Cursor run in the Teammates lab to leg a once FIX-1986 lands.

Architecture opportunity

The one real refactor this epic earns is already in the spec: one planProjectMcp resolution that both the worker capability and the coding relay call. I would hold the line on that. The connectProjectMcp / projectMcpCapability split already keeps connection lifetime apart from planning, so nothing else needs deepening here. Kitchen Sink's env-keyed createMcpCapability is correctly left as named debt rather than pulled in.

Answers to the "look here" questions

  • FIX-2331 as one epic? No. The seam in DECISIONS is clean, and merging them would put a server-direction security model (caller sign-in) in the same set as a client-direction key model.
  • Three children or two? Keep three. The collapse trigger is well-bounded. Finding 2 is a reason Codex deserves its own spec review.

Generated by Claude Code

Comment thread specs/epics/FIX-2615/SPEC.md Resolved
…ring is a control

Fold review comment 4520231144: with one user, a lab-only createMcpCapability
with the operator's environment key passed leg a, so the check could not fail
for the rejected smaller goal (BP-003). Leg a now has a second Teammates user
whose calls must carry that user's stored key, and the lab-only wiring is a
control that must fail. Trims SPEC.md and DECISIONS.md prose; no direction change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGthqcWLSoHxXN7UFG
@jhoffner

Copy link
Copy Markdown
Collaborator Author

I want to see a list of which packages will be updated and what classes/functions we will provisionally build.

Answers the owner's ask on #5010 for the packages the set touches and the
symbols it provisionally builds, each grounded in main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGthqcWLSoHxXN7UFG

Copy link
Copy Markdown
Collaborator Author

Here's the list. Every existing symbol is on main today; a name after → is a working name the child specs settle.

Package What changes Provisional surface (existing symbol it extends) Owner
@flow-state-dev/workforce · projects/ The connector entry, the host's set for work with no project, one resolution ProjectMcpServers / ProjectMcpServerConfig ({ url, seedEnv }) → Connectors / ConnectorConfig, gaining allow · planProjectMcp → planConnectors: reads the project's list, or the host's set when runProjectOf finds no project · a new host option on both factories, e.g. outsideProject: string[] · projectMcpTools → connectorTools (its named stays) · projectMcpCapability → connectorCapability, its allow option narrowing only · checkProjectMcpServers → checkConnectors FIX-2645
@flow-state-dev/workforce · the project row mcpServers becomes connectors; old rows still read (BP-030) projectResourceStateSchema.mcpServers → connectors · ProjectBlocksOptions.mcpServers → connectors · refusal unknown-mcp-server → unknown-connector · the error reporter's mcpTools?: ProjectMcpToolsResolver follows the rename FIX-2645
@flow-state-dev/workforce · error-reporter/ One redaction rule, any key length redact / secretsFromEnv (MIN_SECRET = 8) and tools' redactSecrets become one; which survives is the bug's call FIX-2012
@flow-state-dev/tools · /mcp Possibly the home of that one rule. Nothing else redactSecrets · createMcpManager unchanged, still the one client (ER-2) FIX-2012
@flow-state-dev/codex Takes relayed tools through a generic option (ER-5) CodexAgentOptions gains mcpTools, the shape ClaudeCodeAgentOptions.mcpTools takes, served to the CLI as a local endpoint through CodexClientOptions.config; no key in that config (ER-3) FIX-1986
@flow-state-dev/cursor The same option, onto the SDK's own slot CursorAgentOptions gains mcpTools, mapped to local.customTools FIX-1986
@flow-state-dev/mcp Maybe: Codex's endpoint, if FIX-1986's spec serves it with the existing transport createMcpTransportAdapter, reused, not changed FIX-1986
@flow-state-dev/shift-manager · teams/devteam The rename, and Codex and Cursor runs get the relay OpenLabOptions.mcpServers → connectors · FSD_MCP_SERVERS and the projects' mcpServers: ["linear"] follow · codexHarness / cursorHarness take mcpTools as claudeCodeHarness does · mcpCredentialsAdapter unchanged FIX-2645 · FIX-1986
Teammates lab · labs/teammates/host.mts The first consumer with no project Installs Linear, enables it outside a project, adds the capability to defineAgentWorkerFlow({ uses }), passes mcpTools to its claudeCodeAgent; serves a key route like Shift Manager's so each user stores their own FIX-2645
Teammates lab · same file Its Cursor (default) and Codex runs reach it cursorAgent / codexAgent there take mcpTools FIX-1986
Contributor docs The word and the model docs/contributing/glossary.mjs gains connector · docs/architecture/workforce-projects-and-connectors.md FIX-2645

Not touched, so the L1/L2 line holds: @flow-state-dev/core and @flow-state-dev/engine (the relay uses HarnessCallbackContext as it is) · @flow-state-dev/claude-code (its mcpTools is the shape the others copy) · @flow-state-dev/harness-manager (its HarnessFeeds carries no MCP; Shift Manager's extension does) · client, react · Kitchen Sink (keeps its createMcpCapability). The closure, FIX-2646, adds no package surface: its local MCP test server is test code.

In the spec at this commit: SPEC.md → Packages and provisional surface


Generated by Claude Code

…h MCP today

The Claude Code-style lab has no project or MCP wiring on main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGthqcWLSoHxXN7UFG
@gitar-bot

gitar-bot Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Code Review ✅ Approved 1 closed / 1 findings

🟢 Low risk · The new epic specifications and diagrams document proposed connector and key-handling work without changing executable behavior.

Spec for the MCP connectors epic (FIX-2615) defining that a host installs a connector once and runs reach it with the user's own key, with or without a project. Leg a's signal now uses two Teammates users with per-user keys, so the rejected smaller goal can no longer pass it. No open findings remain.

✅ 1 closed
✅ Quality: Leg a's signal uses the operator's key, so the rejected goal passes it

📄 specs/epics/FIX-2615/SPEC.md:18 📄 specs/epics/FIX-2615/SPEC.md:23 📄 specs/epics/FIX-2615/SPEC.md:38 📄 specs/epics/FIX-2615/SPEC.md:43 📄 specs/epics/FIX-2615/SPEC.md:46
The goal says each run reaches a connector "with its own user's key". The line under the flowchart says leg a is the leg the smaller goal would also pass, "so its check reads which user's key the server received". But the Signal row only asks that a worker and a Claude Code run in the Teammates lab call the tool "with the operator's key". The rejected smaller goal (a lab-only createMcpCapability with an environment key, which gives every user the operator's key) produces exactly that result. So leg a cannot fail for the shape the spec rejects. Under BP-003 the check has to be able to fail for the claim it backs.

Fix: add a second Teammates user with their own stored key to leg a. The run that user starts must reach the test server with that user's key and not the operator's. Add a matching control: a lab-only environment-key wiring must fail leg a.

Verification

Rules No rules evaluated

Functional validation Not enabled

Set up

For more verification details, comment gitar display:verbose.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing compact verification results.

Comment with these commands to change the behavior for this request:

Auto-apply Compact
gitar auto-apply:on         
gitar display:verbose         

Was this helpful? React with 👍 / 👎 | Gitar

@jhoffner

Copy link
Copy Markdown
Collaborator Author

Decision: the MCP key route is owned by FIX-2775 D3 (#5463), which moves it into @flow-state-dev/workforce as the one route. Please amend this epic:

  1. Drop "mcpCredentialsAdapter stays unchanged in teams/devteam"; it moves to workforce per spec(FIX-2775): Shift Manager's directory #5463 D3.
  2. Teammates (FIX-2645) imports the workforce route instead of serving its own key route "like Shift Manager's". One route, no copy, which also keeps ER-2 intact.
  3. The MCP-to-connectors rename applies to the moved workforce route; coordinate the names with spec(FIX-2775): Shift Manager's directory #5463 so it lands with connector names or right before.

Owner decision on #5010: the key route moves into @flow-state-dev/workforce under
FIX-2775 D3 (#5463). mcpCredentialsAdapter no longer stays in teams/devteam; the
Teammates lab imports the workforce route instead of serving a copy (ER-2). New
coordination seam with FIX-2775: its move lands first, in connector names.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGthqcWLSoHxXN7UFG

Copy link
Copy Markdown
Collaborator Author

Folded the key-route decision at 663f69a. I checked #5463 first: its D3 (at 2bd7467) moves the connector keys route into defineProjectBlocks in @flow-state-dev/workforce, already in connector names, and says FIX-2645's Teammates lab imports it.

SPEC.md

  • Shift Manager row: mcpCredentialsAdapter no longer stays in teams/devteam. It moves to workforce, and the host imports it.
  • New row: @flow-state-dev/workforce · projects/mcp-credentials.ts, owned by FIX-2775 D3, outside the set. The stored prefix mcp-credentials/ and its migration stay with FIX-2645.
  • Teammates lab row: it now imports workforce's one route, with no copy (ER-2), instead of serving one "like Shift Manager's".
  • What's already here: FIX-2775 D3 is cited as Builds on. The dependency graph gets a dashed FIX-2775 input, and its caption says the Teammates wiring lands after FIX-2775's workforce PR.
  • "key route" in the set table and the Adds table now reads "how its key is supplied". It meant key supply there, not the HTTP route.

DECISIONS.md

  • Decided in review: one key route, owned by FIX-2775. No D-card or ER rule moved.
  • New coordination seam, FIX-2645 ↔ FIX-2775. The connector names land in spec(FIX-2775): Shift Manager's directory #5463's move, and that PR lands first. FIX-2645 renames the rest of the vocabulary and wires the Teammates lab after it merges. Why: spec(FIX-2775): Shift Manager's directory #5463 already uses connector names. If FIX-2645 renamed the route right after the move, with no alias (BP-034), its importers would break twice.
  • The same seam notes that the Teammates lab has no projects flow. The route has to be reachable by a host without one, and FIX-2775 shapes that export.

Linear: FIX-2645's description now says the same thing, and FIX-2645 is linked to FIX-2775 as related.


Generated by Claude Code

Copy link
Copy Markdown
Collaborator Author

Architect: key-route fold matches the decision at 663f69a

All three asks are in: mcpCredentialsAdapter no longer stays in teams/devteam, the new workforce row is owned by FIX-2775 D3 (#5463), and the Teammates lab imports the one route instead of a copy (ER-2). Sequencing the connector names into #5463's move so FIX-2645 doesn't rename a fresh no-alias export (BP-034) is right.

One open seam, now on #5463: your new seam row says the Teammates lab has no projects flow, so FIX-2775 must shape an export a host without one can reach. #5463's D3 says the route lives inside defineProjectBlocks, not beside it, and rejects standalone exports. As written, the two specs don't meet: Teammates can't import the route without building the projects flow this seam says it won't. I've asked #5463 to settle it in D3. No change needed here unless D3 lands differently.

— FSD Architect

This branch was successfully deployed

1 active deployment
Preview – flow-state-dev-docs — 663f69a5 Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants