docs(mcp.md): refresh stale tool catalog + URL/auth references

[stackbilt-admin]

Summary

docs/mcp.md (296 lines) describes deprecated infrastructure as canonical. Caught during a docs-site audit on 2026-05-02 when Stackbilt-dev/docs was re-sourcing pages post-consolidation; fixed by writing a fresh canonical platform-side reference at Stackbilt-dev/stackbilt-web/docs/mcp.md and charting the gateway from there. This issue tracks the gateway-repo-side refresh, which is the gateway team's call.

Stale references in docs/mcp.md

• Production endpoint — https://stackbilt.dev/mcp (line 5). The stackbilt.dev domain now 301-redirects to stackbilder.com; stackbilder.com/mcp/info returns 404. Current endpoint is https://mcp.stackbilt.dev/mcp (per README, wrangler.toml zone routing, and the official MCP registry listing).
• Auth methods — "Compass JWT" row (line 17) and the entire "Unified Auth (Cross-Compass)" section (lines 19-31). Compass was removed as a standalone product per upstream stackbilt-web/CLAUDE.md; the stackbilt.dev/api/auth/token exchange URL is dead.
• Tool catalog — "All 22 Tools" section (line 109) lists flow_* (runFullFlowAsync, getArtifact, getFlowScaffold, etc.) as canonical. The repo README explicitly marks flow_* as DEPRECATED, migrating to scaffold_* (TarotScript-backed, deterministic). The doc and README contradict each other.
• qualityWeighting / CSA sub-config (lines 262-271) — Compass Service Adapter no longer exists; csa: 0.6 weighting is meaningless.
• StackBilt branding (line 3) — predates the Stackbilder rename.
• Client config snippets (lines 56-92, 187-200) — embed dead stackbilt.dev/mcp URLs in JSON examples and Node.js code.

Suggested approach

A surgical edit pass leaves the doc internally inconsistent (the deprecated flow_* deep-dive would still describe a 22-tool catalog that's being torn down). Two cleaner options:

1. Replace with a thin doc that points to the README for the live catalog — README is current; tools/list is the source of truth for "what's bound right now"; freezing a snapshot in a doc is what got us here.
2. Full rewrite under the new architecture — multi-product gateway with OAuth + service bindings to tarotscript-worker / img-forge-mcp / stackbilt-engine / stackbilt-deployer / edge-auth. More work; more useful long-term.

What's already done

• Stackbilt-dev/stackbilt-web/docs/mcp.md — canonical platform-side reference, rendered at docs.stackbilt.dev/mcp. Describes the gateway from the platform's perspective (architecture, service-binding map, auth, transports). Defers tool catalog to the gateway repo. Includes pointer to this repo + README.
• Stackbilt-dev/docs/docs-manifest.json v3 — re-sources mcp.md from stackbilt-web (was sourcing from Stackbilt-dev/edgestack_v2/docs/mcp.md, now deprecated).
• AEGIS wiki mcp-gateway-architecture — canonical architecture map for the gateway, including upstream/downstream associations and the deprecation history.

Not blocking

The platform-side reference at docs.stackbilt.dev/mcp is current. Readers landing there get accurate info. This issue is about the gateway repo's own internal doc consistency.

🤖 Generated with Claude Code

[stackbilt-admin]

Update — paused pending docs-architecture migration

Filed AEGIS wiki decision page wiki-as-docs-sot-migration (2026-05-02). Short version: the docs site at docs.stackbilt.dev is migrating from a "pull from N product repos via gh API" model to "read from AEGIS wiki at build time." Repos that want public-facing showcase pages emit content to wiki via CI on PR-merge; the docs site has a single SoT.

Implications for this issue:

Under the new model, this repo's docs/mcp.md may not need to exist as a docs-site source at all. The canonical platform-side reference is already at Stackbilt-dev/stackbilt-web/docs/mcp.md (which docs.stackbilt.dev/mcp currently renders). Once the migration moves mcp-gateway-architecture (the AEGIS wiki page authored 2026-05-02) into the rendered docs slug mcp.md, the docs site stops caring about any docs/mcp.md in this repo.

What that leaves for this repo:

• docs/mcp.md becomes purely an internal reference for repo contributors — no public-doc-site dependency. Refresh is then optional, scoped to whatever this repo's contributors want from it.
• Or just delete docs/mcp.md and point internally to the canonical AEGIS wiki page.

Suggested course:

Hold this issue until the migration's Phase 3 lands (mcp-gateway-architecture becomes the docs-site source for mcp.md). At that point, the gateway team can decide: refresh docs/mcp.md for internal consumption, or close + delete with a pointer to the wiki page.

Migration plan: AEGIS wiki slug wiki-as-docs-sot-migration. Phase status tracked there.

🤖 Generated with Claude Code