Authenticated MCP route + read resources + llms.txt

[CuriouslyCory]

Parent

PRD #2

What to build

An MCP server, co-located as a route handler speaking Streamable HTTP, lets an authenticated agent read the architecture. The handler resolves a bearer token to an Actor (rejecting missing / revoked / expired tokens — no anonymous access) and exposes read resources that return the deterministic markdown for a project, a subtree, and a cheap index. A discovery llms.txt documents the endpoint, auth, and resource catalog.

Acceptance criteria

• An MCP route handler speaks Streamable HTTP and resolves a bearer token to an Actor
• Unauthenticated, revoked, or expired requests are rejected; there is no anonymous access
• An Actor can only read its owner's projects (no resource accepts a user id)
• Read resources return markdown for project, subtree, and index via the existing serializer
• An llms.txt is served describing the endpoint, auth, and resources
• Read authorization is tested; an MCP Inspector round-trip reads a project as markdown

Blocked by

• Deterministic markdown export + golden test #15 (slice 13: Deterministic markdown export)
• ApiToken + mint/revoke + "Connect an agent" page #17 (slice 15: ApiToken + mint/revoke + Connect an agent page)

[CuriouslyCory]

Realigned against #33 / docs/plans/flow-routed-connections.md.

Deltas:

• Resource catalog grows. Plan adds flow/:id and flow-route/:id MCP resources. These are owned by Slice 5 (Slice 5: Aggregated parent rendering + markdown export for Flows #38), not this issue — Slice 5: Aggregated parent rendering + markdown export for Flows #38's acceptance criteria explicitly registers them. This issue stays scoped to the initial project/subtree/index read surface; the Flow-shaped resources land additively when Slice 5: Aggregated parent rendering + markdown export for Flows #38 ships.
• llms.txt vocabulary. When this issue ships, llms.txt should describe the resources that exist at the time. After Slice 1: Flows on Components — schema, service, spec paste #34 lands (Flows on Components, MCP tools attach-flow-spec / add-flow / list-flows) and Slice 5: Aggregated parent rendering + markdown export for Flows #38 lands (Flow resources), llms.txt will need a follow-up touch to enumerate Flow / FlowSpec / FlowRoute / Polarity vocabulary and the new tool/resource names. Not in scope here — flag for whichever slice updates it.
• list-flows is a tool, not a list resource. The plan files it under MCP tools (lands in Slice 1, Slice 1: Flows on Components — schema, service, spec paste #34), not under MCP resources. No impact on this issue's scope, but worth nailing the terminology so future readers don't expect a flows/ collection resource here.

Sequence: this issue still leads the MCP surface (auth + read substrate). #34 layers Flow tools on top; #38 layers Flow resources + llms.txt refresh.

[CuriouslyCory]

Scope note (per docs/plans/flow-routed-connections.md):

The Flow-Routed Connections plan adds two MCP read resources — flow/:id and flow-route/:id — and extends the deterministic markdown with ### Flows and per-Connection flows: subsections. Those additions land in Slice 5 (#38), not here.

Keep this slice's resource catalog (project, subtree, index) exactly as listed, but build the handler, llms.txt generator, and resource registry so adding flow/:id / flow-route/:id later is purely additive — no rewrites of the auth or catalog plumbing.