MCP Build Status

This page is the current MCP checkpoint so the next session can start from repo state instead of chat history.

What Is Merged

The following MCP work is merged into main:

PR #70: initial Worker-hosted MCP endpoint
PR #71: standalone Node-based MCP integration harness
PR #72: connection_list
PR #73: workspace_list
PR #74: calendar_get_snapshot

Current MCP Surface

Endpoint:

POST /mcp

Tools:

auth_get_status
connection_list
workspace_list
calendar_get_snapshot

Resources:

agenda://platform-rules

Prompts:

setup-agenda-panda

Current Architecture

Remote MCP is served by the main Worker in src/mcp/server.ts.
/mcp is routed through the main Worker entrypoint in src/index.ts.
MCP transport validation is handled by the standalone Node harness in mcp-tests/mcp.integration.test.mjs.
Worker and MCP code reuse shared backend query logic instead of duplicating access rules:
- workspace access/listing is shared through src/routes/projects.ts
- post/calendar access/listing is shared through src/routes/posts.ts

Behavior That Exists Today

`auth_get_status`

returns authenticated vs unauthenticated status
returns user identity and plan
returns active_projects_count

`connection_list`

requires authentication
requires owner/admin access to at least one workspace
returns authorized: false if the user is authenticated but does not yet have connection-management access
returns connected social accounts for the user

`workspace_list`

requires authentication
does not require additional authorization beyond accessible workspace membership/ownership
returns a lean workspace list payload
intentionally excludes large markdown fields like soul_md and art_md

`calendar_get_snapshot`

requires authentication
supports:
- optional workspace_id
- optional date_from
- optional date_to
defaults to a window from now through the next 30 days if no window is provided
returns only scheduled posts inside the requested window
validates:
- ISO date parsing
- date_to > date_from
- workspace_id must be accessible if provided

Local Test Workflow

Primary local validation path:

bunx wrangler dev --port 8788

Then in another terminal:

npm run test:mcp

Current harness coverage:

MCP surface discovery
unauthenticated auth_get_status
authenticated auth_get_status
authenticated connection_list
authenticated workspace_list
authenticated calendar_get_snapshot

Manual ad hoc testing is also possible with inline node --input-type=module -e '...' scripts, but npm run test:mcp is the stable default.

Important Implementation Decisions Already Made

MCP transport tests do not run in the Workers Vitest pool.
MCP transport tests run in a separate Node-based harness that starts wrangler dev and uses the real MCP SDK over HTTP.
This split was chosen because the Workers Vitest path became unstable for the streamable HTTP MCP transport.
Read-only MCP list and snapshot tools are intentionally narrow and cheap in token terms.
Shared backend query helpers are preferred over duplicating SQL in MCP handlers.

Known Gaps

These are not built yet:

connection_health_check
calendar_preview_sync
calendar_apply_sync
post_schedule
post_publish_now
ap mcp stdio
host install flows for Claude and Codex
public SKILL.md MCP path

Known Issues And Cleanup

Local Sentry noise

Local wrangler dev MCP testing can currently emit errors into the real Sentry project because:

src/index.ts includes a hardcoded Sentry DSN fallback
local dev still reports through the same Sentry path

Observed symptom:

local MCP registration or runtime mistakes can show up as production noise in Sentry even when they are only from local development

Recommended cleanup:

remove the hardcoded production DSN fallback for local dev, or
gate Sentry by environment, or
tag local and preview environments distinctly so MCP iteration does not pollute production signal

Production-level MCP validation does not exist yet

Right now the MCP path is validated locally, not as a production-grade installed client integration.

Tomorrow’s Decisions

1. Next MCP slice

Choose one:

repair-oriented surface:
- likely connection_health_check
first write-preview surface:
- likely calendar_preview_sync

2. Public surface area

Decide whether MCP should now be referenced in public onboarding artifacts, especially:

frontend/public/SKILL.md
homepage onboarding copy and copied prompts

3. Production-level testing strategy

Decide how to validate MCP in a production-like setup, not just local wrangler dev.

Likely options:

deployed preview MCP smoke checks
a dedicated MCP smoke GitHub Action against preview or prod
manual install testing in a real Claude or Codex client against a stable deployed MCP endpoint

Recommended Starting Point For Tomorrow

Review this page.
Decide between connection_health_check and calendar_preview_sync.
Decide whether MCP is still internal-only or should start appearing in SKILL.md.
Decide what production-level MCP testing means for this repo:
- preview deploy only
- preview plus smoke workflow
- real host install tests