Use hosted MCP by default and harden deploy runtime paths

.codex/config.toml

@@ -1,9 +1,4 @@
 #:schema https://developers.openai.com/codex/config-schema.json
 
 [mcp_servers.fpf_memory]
-command = "bun"
-args = ["src/mastra/stdio.ts"]
-cwd = "."
-required = false
-startup_timeout_sec = 15
-tool_timeout_sec = 60
+url = "https://fpf-memory-remote-20260414.server.mastra.cloud/api/mcp/fpf_memory/mcp"

.gitignore

@@ -11,4 +11,5 @@ output.txt
 *.db-*
 .mastra-project.json
 package-lock.json
+src/mastra/public
 .DS_Store

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "fpf_memory": {
+      "type": "http",
+      "url": "https://fpf-memory-remote-20260414.server.mastra.cloud/api/mcp/fpf_memory/mcp"
+    }
+  }
+}

AGENTS.md

@@ -8,7 +8,7 @@ Public tools (deployed MCP surface):
 - `query_fpf_spec` for structured answer envelopes
 - `get_fpf_index_status` for runtime freshness checks
 
-Expert tools (local stdio only, via `bun run mcp`):
+Expert tools (local full-surface runtime only, via `FPF_MCP_SURFACE=full bun run mcp`):
 
 - `read_fpf_doc` for exact generated markdown pages
 - `trace_fpf_path` for retrieval evidence and provenance

README.md

@@ -104,13 +104,19 @@ bun run mcp
 
 ## Run And Test MCP
 
-Start the stdio MCP server:
+Hosted/public MCP endpoint used by Codex by default:
+
+```text
+https://fpf-memory-remote-20260414.server.mastra.cloud/api/mcp/fpf_memory/mcp
+```
+
+Optional local full-surface MCP server for development and expert tools:
 
 ```bash
-bun run mcp
+FPF_MCP_SURFACE=full bun run mcp
 ```
 
-Start the hosted Mastra runtime on the Hono engine:
+Start the hosted Mastra runtime locally on the Hono engine:
 
 ```bash
 bun run start
@@ -122,45 +128,36 @@ Decision record for this interface choice:
 
 - [DRR-0001: MCP As The First-Class Codex Interface](docs/drr/DRR-0001-mcp-first-class-interface.md)
 
-For Codex registration:
-
-- Command: `bun`
-- Arguments: `src/mastra/stdio.ts`
-- Working directory: your local `fpf-memory` repo root
+The DRR records the MCP-first boundary choice; the current Codex default is the hosted public MCP.
 
 Equivalent `~/.codex/config.toml` entry:
 
 ```toml
 [mcp_servers.fpf_memory]
-command = "bun"
-args = ["src/mastra/stdio.ts"]
-cwd = "/absolute/path/to/fpf-memory"
-required = false
-startup_timeout_sec = 15
-tool_timeout_sec = 60
+url = "https://fpf-memory-remote-20260414.server.mastra.cloud/api/mcp/fpf_memory/mcp"
 ```
 
-This repo now also ships the same project-scoped configuration at `.codex/config.toml`. Once the project is trusted, Codex can load the `fpf_memory` server directly from the repo without copying the snippet into your user config.
-
-Local development can keep using the Bun shortcut:
-
-```bash
-bun run mcp
-```
+This repo ships the same project-scoped configuration at `.codex/config.toml` and `.mcp.json`. Once the project is trusted, Codex can load the hosted `fpf_memory` server directly from the repo.
 
 Recommended Codex tasks:
 
 - answer a question: `Use only the fpf_memory MCP server. Call ask_fpf with question: "What is U.PromiseContent?"`
 - structured query: `Use only the fpf_memory MCP server. Call query_fpf_spec with question: "What is an FPF pattern?"`
 - check runtime freshness: `Use only the fpf_memory MCP server. Call get_fpf_index_status`
 
-Expert tasks (local stdio only):
+Expert tasks (local full-surface runtime only):
 
 - read a generated page: `Use only the fpf_memory MCP server. Call read_fpf_doc with selector: "A.1.1"`
 - inspect retrieval evidence: `Use only the fpf_memory MCP server. Call trace_fpf_path with question: "How do U.RoleAssignment and U.BoundedContext connect?"`
 - rebuild the local index: `Use only the fpf_memory MCP server. Call refresh_fpf_index`
 
-Smoke-test the same runtime surface locally before wiring it into Codex:
+Start the local full-surface runtime before using expert tools:
+
+```bash
+FPF_MCP_SURFACE=full bun run mcp
+```
+
+Smoke-test the local full-surface runtime before using expert tools or deploying changes:
 
 ```bash
 bun run cli -- status
@@ -178,13 +175,13 @@ Run the end-to-end verification script for the real CLI, MCP stdio, and hosted H
 ./scripts/verify-runtime.sh
 ```
 
-The verification script also checks the direct stdio launcher (same entry as `bun run mcp`):
+The verification script also checks the direct stdio launcher (same entry as `bun run mcp`; add `FPF_MCP_SURFACE=full` for expert-tool work):
 
 ```bash
-bun src/mastra/stdio.ts
+FPF_MCP_SURFACE=full bun src/mastra/stdio.ts
 ```
 
-This starts a long-running stdio server; for a manual smoke check, stop it with `Ctrl+C` after startup confirmation.
+This starts a long-running stdio server; for a manual smoke check, stop it with `Ctrl+C` after startup confirmation. Omit `FPF_MCP_SURFACE=full` if you only want the public 3-tool surface.
 
 If this repo is registered as a Codex MCP server, restart Codex after changes and then test with a forced tool-use prompt such as:
 
@@ -248,7 +245,9 @@ Call trace_fpf_path with:
 - `query_fpf_spec`: return the answer envelope with IDs, citations, constraints, and freshness metadata
 - `get_fpf_index_status`: inspect runtime freshness, artifact presence, and runtime configuration
 
-### Expert tools (local stdio only)
+### Expert tools (local full-surface runtime only)
+
+Set `FPF_MCP_SURFACE=full` on local stdio or local HTTP runtimes to expose these tools. The deployed server stays on the public 3-tool surface.
 
 - `refresh_fpf_index`: rebuild the local artifact set
 - `trace_fpf_path`: return deterministic retrieval evidence only
@@ -257,7 +256,7 @@ Call trace_fpf_path with:
 - `inspect_fpf_anchor`: expand one anchor into raw anchor text plus owning node context
 - `expand_fpf_citations`: expand multiple citations into raw anchor text plus owning node context
 
-Only `query_fpf_spec` and `ask_fpf` can use the optional synthesizer. All other MCP tools stay deterministic. Set `FPF_MCP_SURFACE=public` on the deployed server to restrict to public tools only.
+Only `query_fpf_spec` and `ask_fpf` can use the optional synthesizer. All other MCP tools stay deterministic. Set `FPF_MCP_SURFACE=public` on the deployed server to restrict it to public tools only.
 
 ## Runtime behavior
 

docs/drr/DRR-0001-mcp-first-class-interface.md

@@ -7,6 +7,8 @@ description: "Design-Rationale Record for the Codex-facing interface decision in
 
 Status: accepted for the bounded context `CodexAccess:LocalFPFSpecRuntime`
 
+Update 2026-04-13: the default Codex registration path now uses the hosted public MCP URL. The local stdio transport remains available as an optional full-surface expert/dev path.
+
 ## Problem frame
 
 `fpf_memory` needs a Codex-facing interface for grounded access to the local `FPF-spec.md` runtime. The repo already exposes a local MCP server, a Bun CLI, and a hosted Hono/Mastra runtime path, but the interface promise was implicit rather than recorded as an explicit decision.
@@ -28,9 +30,9 @@ The decision includes these commitments:
 
 1. The primary Codex integration surface is the `fpf_memory` MCP server.
 2. The CLI remains an operator/debug surface, not the primary semantic boundary for agent use.
-3. Hosted HTTP remains a transport/hosting option, not the first interface to optimize for in this repo slice.
-4. The Codex registration path is documented and packaged around the stdio entry point:
-   `bun src/mastra/stdio.ts`
+3. The current default Codex transport is the hosted public MCP URL.
+4. The repo also keeps a local stdio entry point for optional full-surface expert/dev work:
+   `FPF_MCP_SURFACE=full bun src/mastra/stdio.ts`
 5. This decision is recorded as a DRR outside the normative FPF core, consistent with `E.9`.
 
 ## Rationale
@@ -44,7 +46,7 @@ This choice keeps the FPF layers separate.
 Why MCP, rather than the alternatives:
 
 - **Against CLI-first:** the CLI is useful for operators and smoke tests, but it is not the native tool-selection boundary for Codex.
-- **Against custom HTTP-first:** Codex already supports MCP natively, so a bespoke API would add interface work without solving the current local integration problem.
+- **Against custom HTTP-first:** Codex already supports MCP natively, so a bespoke API would add interface work without improving the MCP boundary itself.
 - **For MCP-first:** the repo already ships an MCP server, Codex natively supports MCP configuration, and the server contract matches the bounded need for grounded retrieval over local spec artifacts.
 
 This also follows FPF boundary discipline:
@@ -63,14 +65,14 @@ Positive consequences:
 - Codex setup, packaging metadata, and verification can all align around a single published interface decision.
 - Future work can distinguish between:
   - boundary choice: MCP-first
-  - transport choice: stdio now, HTTP optional later
+  - transport choice: hosted/public by default, stdio optional for local expert work
   - surface-shape work: discovery, browse/search, tools/resources/prompts
 
 Trade-offs and follow-up consequences:
 
 - A tool-only MCP surface is still heavier than ideal for first-pass discovery, so later work should improve discovery without changing this decision.
 - Documentation now has one more artifact to keep current; that is acceptable because the DRR is the durable rationale carrier.
-- If the bounded context changes from local Codex use to a hosted multi-tenant product, a later DRR may designate HTTP as an additional first-class external boundary for that different scope.
+- If the bounded context changes again, a later DRR can further refine hosted/public vs local expert transport choices without overturning the MCP-first boundary.
 
 References:
 

docs/mcp-interface.md

@@ -1,17 +1,17 @@
 ---
 title: "MCP Interface"
-description: "Spec-oriented interface contract for the local FPF stdio MCP server."
+description: "Spec-oriented interface contract for the hosted and local FPF MCP surfaces."
 ---
 
 # MCP Interface
 
-This page documents the public MCP surface implemented by `fpf_memory`.
+This page documents the MCP surfaces implemented by `fpf_memory`.
 
 Decision record:
 
 - [DRR-0001: MCP As The First-Class Codex Interface](/drr/DRR-0001-mcp-first-class-interface/)
 
-The runtime itself is compiler-backed and local:
+The runtime itself is compiler-backed and local to `FPF-spec.md`:
 
 - authored source: `FPF-spec.md`
 - runtime artifacts: `.runtime/fpf-index/*`
@@ -20,38 +20,30 @@ The runtime itself is compiler-backed and local:
 
 ## Transport
 
-- stdio (local): `bun run mcp`
-- HTTP (local): `http://localhost:4111/api/mcp/fpf_memory/mcp` via `mastra dev`
+- hosted/public (default Codex path): `https://fpf-memory-remote-20260414.server.mastra.cloud/api/mcp/fpf_memory/mcp`
+- stdio (local expert/dev path): `FPF_MCP_SURFACE=full bun run mcp`
+- HTTP (local dev path): `http://localhost:4111/api/mcp/fpf_memory/mcp` via `mastra dev`
 - server name: `fpf_memory`
 - protocol version: `2024-11-05`
 
-Both stdio and HTTP default to the public tool surface (3 tools). Set `FPF_MCP_SURFACE=full` for all 9 tools.
+The hosted server exposes only the 3 public tools. Local stdio and local HTTP default to the same public surface; set `FPF_MCP_SURFACE=full` to expose all 9 tools for local expert work.
 
 ## Codex Setup
 
-Codex desktop app fields:
-
-- command: `bun`
-- arguments: `src/mastra/stdio.ts`
-- working directory: absolute path to the local repo root
-
-Equivalent `~/.codex/config.toml` entry:
+Default `~/.codex/config.toml` entry:
 
 ```toml
 [mcp_servers.fpf_memory]
-command = "bun"
-args = ["src/mastra/stdio.ts"]
-cwd = "/absolute/path/to/fpf-memory"
-required = false
-startup_timeout_sec = 15
-tool_timeout_sec = 60
+url = "https://fpf-memory-remote-20260414.server.mastra.cloud/api/mcp/fpf_memory/mcp"
 ```
 
-This repo also ships the same project-scoped configuration at `.codex/config.toml`. Codex will load that file after the project is trusted.
+This repo ships the same hosted configuration at `.codex/config.toml` and `.mcp.json`. Codex will load that file after the project is trusted.
+
+For temporary local expert work, point a client at `src/mastra/stdio.ts` and set `FPF_MCP_SURFACE=full`.
 
 ## Tool Catalog
 
-### Public tools (default surface)
+### Public tools (hosted default surface)
 
 #### `ask_fpf`
 
@@ -63,13 +55,13 @@ Answer a question with deterministic grounding, citations, constraints, and fres
 
 #### `get_fpf_index_status`
 
-Report whether the local index exists, whether it is fresh against the current source hash, and which artifacts are present.
+Report whether the current runtime index exists, whether it is fresh against the current source hash, and which artifacts are present.
 
-### Expert tools (FPF_MCP_SURFACE=full)
+### Expert tools (local full-surface runtime only)
 
 #### `refresh_fpf_index`
 
-Build or rebuild the local vectorless index from `FPF-spec.md` and persist the runtime artifact set under `.runtime/fpf-index/`.
+Build or rebuild the compiler-backed vectorless index from `FPF-spec.md` and persist the runtime artifact set under `.runtime/fpf-index/`.
 
 #### `trace_fpf_path`
 
@@ -103,12 +95,13 @@ Static routes mirror those pages under `/generated/**` with clean URLs and `.htm
 
 ## Verification
 
-Typical local checks:
+Typical checks:
 
 ```bash
 bun run check
 bun run test
-bun run docs:build
-bun run cli -- read-doc --selector "A.1.1"
-bun run mcp
+curl -X POST https://fpf-memory-remote-20260414.server.mastra.cloud/api/mcp/fpf_memory/tools/get_fpf_index_status/execute \
+  -H 'content-type: application/json' \
+  -d '{"data":{}}'
+FPF_MCP_SURFACE=full bun run mcp
 ```

manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "fpf_memory",
   "version": "1.0.0",
-  "description": "Local vectorless FPF-spec runtime with MCP tools for answers, structured queries, and status.",
+  "description": "Compiler-backed FPF-spec runtime with hosted public MCP tools plus an optional local full-surface expert runtime.",
   "tools": {
     "public": [
       "ask_fpf",
@@ -19,7 +19,7 @@
   },
   "transport": ["stdio", "http"],
   "runtime": {
-    "bun": "bun src/mastra/stdio.ts"
+    "bun": "FPF_MCP_SURFACE=full bun src/mastra/stdio.ts"
   },
   "http": {
     "path": "/api/mcp/fpf_memory/mcp"

package.json

@@ -1,7 +1,7 @@
 {
   "name": "fpf-memory",
   "version": "1.0.0",
-  "description": "Bun-first local vectorless FPF spec runtime exposed through Mastra MCP surfaces with a Hono server engine.",
+  "description": "Bun-first compiler-backed FPF spec runtime exposed through hosted and local Mastra MCP surfaces with a Hono server engine.",
   "private": false,
   "packageManager": "bun@1.3.5",
   "bin": "dist/stdio.js",
@@ -14,6 +14,8 @@
     "build": "bun build ./src/cli.ts ./src/server.ts --outdir dist --target bun",
     "build:mcp": "tsup src/mastra/stdio.ts --format esm,cjs --out-dir dist --no-splitting && node -e \"const fs=require('node:fs');const path='dist/stdio.js';const data=fs.readFileSync(path,'utf8');const shebang='#!/usr/bin/env node';if(!data.startsWith(shebang))fs.writeFileSync(path, shebang + '\\\\n' + data);\" && chmod +x dist/stdio.js",
     "start": "bun src/server.ts",
+    "predeploy": "bash scripts/prepare-deploy.sh",
+    "deploy": "bun run predeploy && npx mastra build && npx mastra server deploy",
     "lint": "rslint --type-check src tests scripts/generate-docs.ts *.config.ts",
     "check": "tsc --noEmit",
     "cli": "bun src/cli.ts",

scripts/prepare-deploy.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# Stage the two files the deployed runtime actually reads:
+#   1. FPF-spec.md        — source hash for freshness check
+#   2. snapshot.json       — compiled index (the only artifact loadSnapshot() reads)
+#
+# The other 6 artifact files (index-map, pattern-graph, …) are
+# write-only debugging output — never loaded back by the runtime.
+#
+# Usage:  bash scripts/prepare-deploy.sh
+#         bun run deploy
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PUBLIC="$ROOT/src/mastra/public"
+INDEX="$ROOT/.runtime/fpf-index"
+
+# 1. Rebuild snapshot so staged artifact matches current source
+echo "Refreshing index snapshot..."
+bun "$ROOT/src/cli.ts" refresh
+
+# 2. Stage only what the runtime reads
+mkdir -p "$PUBLIC/.runtime/fpf-index"
+cp "$ROOT/FPF-spec.md" "$PUBLIC/FPF-spec.md"
+cp "$INDEX/snapshot.json" "$PUBLIC/.runtime/fpf-index/snapshot.json"
+
+echo "Staged into src/mastra/public/:"
+du -sh "$PUBLIC/FPF-spec.md" "$PUBLIC/.runtime/fpf-index/snapshot.json"

server.json

@@ -1,13 +1,14 @@
 {
   "name": "fpf_memory",
   "version": "1.0.0",
-  "description": "Local vectorless FPF-spec runtime for MCP clients.",
+  "description": "Optional local full-surface FPF MCP runtime for expert clients.",
   "transport": "stdio",
   "command": "bun",
   "cwd": ".",
   "args": ["src/mastra/stdio.ts"],
   "env": {
     "FPF_SPEC_SOURCE_PATH": "FPF-spec.md",
-    "FPF_RUNTIME_ARTIFACT_DIR": ".runtime/fpf-index"
+    "FPF_RUNTIME_ARTIFACT_DIR": ".runtime/fpf-index",
+    "FPF_MCP_SURFACE": "full"
   }
 }