RFC 0025: reactive MCP subscriptions and SSE transport

[dligthart]

Summary

Implement RFC 0025 so WordClaw can push domain-scoped events into active MCP clients instead of forcing polling loops.

Why now

• Remote MCP is still stateless today (POST /mcp, GET /mcp = 405).
• The runtime already has audit and webhook event plumbing that can be reused.
• Reactive subscriptions are the biggest product-value step from safe agent CRUD toward a real agent control plane.

Scope

1. Add session-backed MCP HTTP streaming so GET /mcp can keep a live connection open.
2. Add a subscribe_events MCP tool for explicit topic registration.
3. Reuse the existing audit event bus and filter by actor scope and domain.
4. Ship one verified end-to-end path first: workflow and content approval or publish-related events.
5. Document the attach flow and add a verification script.

Acceptance criteria

• Agents can attach to a long-lived MCP HTTP stream.
• Agents can call subscribe_events with supported topics.
• Matching REST or runtime mutations produce events on the live MCP stream.
• Events are filtered to the authenticated actor's domain and scopes.
• There is an automated verification path covering attach, subscribe, and event delivery.

Suggested slices

• transport foundation
• subscription manager and filtering
• first event set (audit/content/workflow publish path)
• verification and docs

[dligthart]

Shipped the first RFC 0025 slice in b82c905.

What landed:

• session-backed remote MCP transport on /mcp
• GET /mcp standalone SSE stream with issued mcp-session-id
• subscribe_events MCP tool for reactive topic registration
• domain-aware audit-event delivery over notifications/wordclaw/event
• first supported reactive path: content_item publication and approval-related topics
• verify-mcp-streams.ts end-to-end verifier
• MCP guide updates documenting the session and reactive flow

Validation:

• npm run build
• npm test -- --run src/mcp/http-transport.test.ts src/integrations/vercel-publish-webhook.test.ts
• npm run docs:build
• WORDCLAW_BASE_URL=http://localhost:4100 WORDCLAW_API_KEY=remote-admin npx tsx verify-mcp-streams.ts

Next slice from here:

• expand topic coverage beyond the first audit/content workflow set
• tighten capability/deployment manifest docs around reactive MCP
• add a persistent demo agent that acts on pushed events instead of just verifying delivery

[dligthart]

Shipped the next RFC 0025 slice in commit af8243d. This adds reactive MCP discovery metadata to GET /api/capabilities and GET /api/deployment-status, and upgrades demos/mcp-demo-agent.ts with a persistent watch mode for remote /mcp sessions. The demo agent now subscribes to subscribe_events, waits for notifications/wordclaw/event, and reacts with a follow-up REST read for content_item events. Validated with: npm test -- --run src/services/capability-manifest.test.ts src/api/routes.contract.test.ts src/cli/lib/mcp-client.test.ts; npm run build; npm run docs:build; and a live end-to-end run using npx tsx demos/mcp-demo-agent.ts watch content_item.published --transport http --base-url http://localhost:4100 --api-key remote-admin --once, followed by a published content-item creation that delivered the event and triggered the demo agent reaction. Next slice is broadening topic coverage and adding richer subscription filtering.

[dligthart]

Shipped the next RFC 0025 slice in commit f6ad9b2. This adds filter-aware reactive subscriptions on top of the session-backed MCP stream. subscribe_events now accepts an optional filters object, the capability and deployment manifests advertise the supported filter fields, and reactive notifications now include matchedSubscriptions so an agent can tell exactly which topic-plus-filter subscription fired. The MCP demo agent watch mode now accepts --filters JSON for live testing. Validated with: npm test -- --run src/mcp/http-transport.test.ts src/services/capability-manifest.test.ts src/api/routes.contract.test.ts src/cli/lib/mcp-client.test.ts; npm run build; npm run docs:build; and a live end-to-end run where demos/mcp-demo-agent.ts watched content_item.published with --filters {"contentTypeId":683}, ignored an unrelated published item, and reacted only when the matching content type published. Next slice is broadening topic families beyond audit/content-review and adding more ergonomic subscription presets or recipes for common agent loops.

[dligthart]

Shipped the next RFC 0025 slice in commit a0ca1f2. Reactive MCP subscriptions now support broader audit-backed topic families beyond content publication: content_type., api_key., and webhook.* plus their create/update/delete exact topics. The authorization model stays conservative: content_type.* is content-scoped, while api_key.* and webhook.* remain admin-only. Validation includes npm test -- --run src/mcp/http-transport.test.ts; npm test -- --run src/services/capability-manifest.test.ts src/api/routes.contract.test.ts; npm run build; npm run docs:build; and a live demo-agent watch against http://localhost:4100/mcp where demos/mcp-demo-agent.ts subscribed to api_key.create and received the pushed event after a new key was created through REST. Next slice from here is adding higher-level subscription recipes or intent-oriented shortcuts so agents do not need to know the raw topic names up front.

[dligthart]

Shipped the next RFC 0025 slice in commit fce5527. subscribe_events now supports a recipeId argument so agents can subscribe through higher-level reactive recipes instead of memorizing raw topic names. The public capability manifest now advertises curated recipe definitions such as content-publication, review-decisions, schema-governance, and integration-admin, while deployment status reports the recipe count alongside the reactive transport details. The bundled MCP demo agent also supports watch --recipe for live testing. Validation included npm test -- --run src/mcp/http-transport.test.ts; npm test -- --run src/api/routes.contract.test.ts src/cli/lib/mcp-client.test.ts; npm test -- --run src/services/capability-manifest.test.ts; npm run build; npm run docs:build; and a live run where demos/mcp-demo-agent.ts watched --recipe integration-admin against http://localhost:4100/mcp and received an api_key.create notification after a key was created through REST. Next slice from here is adding actor-aware reactive guidance so guide_task can recommend the right recipe plus filters for a given workflow intent.

[dligthart]

Shipped the next RFC 0025 slice in 45a0815 (feat(mcp): add reactive task guidance).

What changed:

• guide_task now returns an explicit reactiveRecommendation block for author-content, review-workflow, manage-integrations, and verify-provenance
• the recommendation is actor-aware and includes available, reason, recipeId, resolvedTopics, blockedTopics, filters, and the exact subscribe_events arguments to send next
• provenance guidance now supports actorType as a first-class reactive filter so actor-centric audit subscriptions are representable without dropping fidelity
• MCP/docs/contracts were updated so the new recommendation shape and actorType filter are visible through the current guidance surface and manifest tests

Validated:

• npm test -- --run src/mcp/http-transport.test.ts
• npm test -- --run src/services/capability-manifest.test.ts
• npm test -- --run src/api/routes.contract.test.ts src/cli/lib/mcp-client.test.ts
• npm run build
• npm run docs:build

Next slice: push this guidance into the static agent guidance/recipe surfaces as examples so remote agents can discover reactive follow-ups without already knowing which guide_task to call first.

[dligthart]

Shipped the next RFC 0025 slice in 60d4adb (feat(mcp): add reactive follow-up discovery).

What changed:

• the static capability manifest now exposes taskRecipes[*].reactiveFollowUp so agents can discover likely subscribe_events follow-ups before calling guide_task
• the new follow-up examples cover author-content, review-workflow, manage-integrations, and verify-provenance
• task-guidance now includes the same reactive follow-up block in prompt form, including an example subscribe_events payload
• the public capability contract and MCP/API docs were updated so this static discovery layer is visible over REST, MCP resources, and prompt-based guidance

Validated:

• npm test -- --run src/services/capability-manifest.test.ts
• npm test -- --run src/mcp/http-transport.test.ts
• npm test -- --run src/api/routes.contract.test.ts src/cli/lib/mcp-client.test.ts
• npm run build
• npm run docs:build

Next slice: add an unsubscribe/replace guidance loop and a long-running demo workflow that reacts to multiple events over time instead of one-shot watch mode.

[dligthart]

Status update: the core RFC 0025 transport and subscription contract is now live on main.

Implemented:

• remote Streamable HTTP MCP sessions on /mcp
• GET /mcp SSE delivery plus explicit session lifecycle
• subscribe_events with topic, recipe, and filter support
• actor/domain-scoped notifications/wordclaw/event delivery
• capability/deployment manifest exposure of the reactive contract
• guide_task reactive recommendations plus static reactive follow-up discovery
• verification paths such as npm run verify:mcp:streams and the demo watch flows
• current attach/subscribe/reactive follow-up docs

Keeping this open only for the remaining umbrella work around reactive hardening and polish. The initial SSE transport and subscription contract are no longer the missing piece.