Hosted MCP server

FPF Reference MCP

Connect chat clients, editors, and coding CLIs to bounded FPF lookup by stable ID — not agent memory, not a web page. Register the server as fpf_reference (not fpf_memory).

This is the MCP setup home. The human-readable FPF specification reference stays on https://fpf.sh.

Streamable HTTP endpoint https://mcp.fpf.sh/api/mcp/fpf_reference/mcp Legacy https://mcp.fpf.sh/api/mcp/fpf_memory/mcp is blocked during the May 2026 mitigation; use the endpoint above. Browser GET returns 405 Method Not Allowed; MCP clients should use POST Streamable HTTP JSON-RPC requests.

1. Check health

Call get_fpf_index_status and confirm the compiled index is fresh.

2. Query context

Ask for a compact project kickoff answer and expect stable FPF IDs in ids.

3. Read exact docs

Use read_fpf_doc only when exact pattern or generated-doc wording matters.

Client Setup

ChatGPT

Create a custom app or connector and use the hosted MCP endpoint as the connector URL.

Open Settings > Apps & Connectors.
Enable developer mode under Advanced settings when your plan or workspace requires it.
Create a custom app or connector, set the Connector URL to the hosted endpoint, then confirm the advertised tools.
Open a new chat and add FPF Reference from the composer tools menu.

Reference docs

Claude

Add a custom connector from Claude settings and point it at the public MCP endpoint.

Open Customize > Connectors.
Click the + button next to Connectors and choose Add custom connector.
Use FPF Reference as the name and the hosted endpoint as the URL.
Connect it, then ask Claude to use fpf_reference for bounded FPF retrieval.

Reference docs

VS Code

Use MCP: Add Server or commit a workspace .vscode/mcp.json file.

Open Command Palette > MCP: Add Server for the guided flow, or add this workspace file.
Start or restart the server from the MCP code lens and confirm trust when VS Code asks.

{
  "servers": {
    "fpf_reference": {
      "type": "http",
      "url": "https://mcp.fpf.sh/api/mcp/fpf_reference/mcp"
    }
  }
}

Reference docs

Zed

Add FPF Reference as a custom remote context server in Agent Panel settings.

Open Agent Panel settings with agent: open settings.
Add a custom server using the url-only remote server shape.
Check the indicator next to FPF Reference; green means the server is active.

{
  "context_servers": {
    "fpf_reference": {
      "url": "https://mcp.fpf.sh/api/mcp/fpf_reference/mcp"
    }
  }
}

Reference docs

Codex CLI

Run the command, then ask Codex to call get_fpf_index_status before route work.

codex mcp add fpf_reference --url https://mcp.fpf.sh/api/mcp/fpf_reference/mcp

[mcp_servers.fpf_reference]
url = "https://mcp.fpf.sh/api/mcp/fpf_reference/mcp"

Reference docs

Claude Code

Use the HTTP MCP transport and verify status with /mcp inside Claude Code.

Run the command, then use /mcp inside Claude Code to check connection status.

claude mcp add --transport http fpf_reference https://mcp.fpf.sh/api/mcp/fpf_reference/mcp

Reference docs

Pi

Install an MCP extension, then configure FPF Reference as a streamable HTTP server.

Install pi-mcp-extension or another Pi MCP extension.
Add the server to ~/.pi/agent/mcp.json for global use or .pi/mcp.json for one project.
Start Pi and use /mcp to check status.

pi install npm:pi-mcp-extension

{
  "mcpServers": {
    "fpf_reference": {
      "transport": "streamable-http",
      "url": "https://mcp.fpf.sh/api/mcp/fpf_reference/mcp",
      "lifecycle": "eager"
    }
  }
}

Reference docs

Package And Self-Hosting

Use the hosted endpoint above when your client allows remote HTTP MCP servers. If your policy requires local or self-hosted tooling, run the same FPF Reference MCP runtime from source.

git clone https://github.com/venikman/fpf-memory.git
cd fpf-memory
bun install
bun run mcp

Use the full local surface only for contributor or operator work that needs expert inspection tools.

FPF_MCP_SURFACE=full bun run mcp

For clients that require an HTTP URL instead of a stdio command, start the local HTTP server and register its MCP route.

bun run start

http://localhost:4111/api/mcp/fpf_reference/mcp

Recipes

Find the right doorway

Use search or structured query before opening exact generated docs.

Use only the fpf_reference MCP server. Search or query FPF for the best route for this work: <describe work>. Return 3-8 exact IDs, why they matter, and what not to load yet.

Build a compact work packet

Ask for enough grounded context to start work without pasting the full FPF specification.

Use only the fpf_reference MCP server. Build an FPF work packet for <task>. Include goal, relevant route or IDs, operating questions, constraints, acceptance checks, risks, and one next move. Do not paste the whole FPF.

Review a PR

Combine bounded FPF retrieval with the actual diff, files, and CI evidence.

Use only the fpf_reference MCP server plus the PR diff, local files, and CI evidence. Review this PR through the PR or code review packet. Return Findings | FPF IDs | Evidence | Tests | Residual risk | Verdict. Lead with behavioral issues and cite exact files; do not paste the full FPF.

Dogfood a product role

Rotate adopter, reviewer, integrator, maintainer, and project-lead perspectives.

Use only bounded FPF retrieval plus direct product evidence. Act as <persona> trying to complete <job> with FPF Reference. Return Context | Persona/job | Surface | FPF IDs used | Evidence | Friction | Proposed improvement | Severity | Validation path.

Public Tools

browse_fpf_catalog
search_fpf
ask_fpf
query_fpf_spec
read_fpf_doc
get_fpf_index_status

Operator Packaging

The hosted MCP runtime and the reference wiki are separate Vercel projects. The MCP project serves the Streamable HTTP endpoint, this setup page, and the freshness status JSON. The wiki project serves the static FPF reference.

bun run vercel:mcp:build
bun run vercel:mcp:deploy:prod

bun run vercel:website:build
bun run vercel:website:deploy:prod

bun run deploy:prod

Vercel MCP at https://mcp.vercel.com is Vercel's operator-side control-plane MCP server. It is useful for deployment evidence and logs, but it is not the public fpf_reference FPF lookup endpoint.

codex mcp add vercel --url https://mcp.vercel.com

https://mcp.vercel.com/venikmans-projects/fpf-reference-mcp
https://mcp.vercel.com/venikmans-projects/fpf-sh

Legacy Compatibility

The canonical server name is fpf_reference. The legacy name fpf_memory is compatibility-only and should not appear in new client setup.

The old endpoint remains explicitly routed so stale clients fail cheaply with a migration signal instead of falling through to the hosted runtime.

https://mcp.fpf.sh/api/mcp/fpf_memory/mcp

Interface Contract

Entity

Hosted MCP interface named fpf_reference.

Purpose

Deterministic lookup, routing, citation, and exact-doc access over a compiled FPF snapshot.

Governing FPF

A.1.1 Bound the local meaning of FPF Reference, MCP, runtime, and upstream FPF.
A.2.3 Treat public setup text as promise/access/acceptance content, not performed work.
A.6.B Separate laws, admissibility gates, commitments, and evidence claims.
A.6.C Unpack contract wording so the interface does not become agent memory or policy.
A.10 Tie reliance-bearing claims to source, snapshot, status, and citation evidence.
B.3 Keep assurance scoped to the typed claim actually evidenced by the runtime.
A.15.1 Keep docs/status/test evidence separate from actual performed work.

Admissible use

discover relevant FPF IDs, routes, and catalog entries
ask compact grounded FPF questions
retrieve exact generated docs when wording matters
check runtime/source/snapshot status before reliance-bearing use

Non-admissible use

agent memory or job-local state
workflow engine or project-policy authority
upstream FPF authoring or semantic editing surface
availability, support, SLA, compliance, or readiness proof
proof that upstream FPF is latest beyond the reported source/snapshot evidence

Reliance gate

Call get_fpf_index_status before trust-sensitive use.
Proceed only when snapshotExists is true, fresh is true, and currentSourceHash matches sourceHash.
Use read_fpf_doc for exact FPF wording; use ask_fpf or query_fpf_spec for bounded context.

Freshness

status ok or fresh means the deployed runtime artifacts are internally consistent with the configured source.
fresh describes the snapshot the runtime is serving, which stays in memory once loaded; the artifacts map separately reports on-disk artifact presence for packaging checks.
Internal consistency is not global upstream currentness.
upstreamCurrentness = unknown means do not claim latest upstream FPF unless an external monitor proves it.

Output expectation

Answers expose stable FPF IDs, citations or grounding, constraints or gaps, and snapshot metadata.
Catalog/search responses expose bounded result sets with source snapshot metadata.
Exact wording comes from read_fpf_doc rather than regenerated prose.

Acceptance tests

Public tool list equals the six-tool public surface.
Legacy fpf_memory endpoint remains migration-only or blocked for new clients.
Standalone browser GET remains non-MCP and returns 405 Method Not Allowed.
Status endpoint reports source, snapshot, freshness, and upstream-currentness fields.
Compact query returns stable FPF IDs and bounded next steps.
Exact wording use goes through read_fpf_doc.

Public tool schemas

Tool	Purpose	Input	Output	Acceptance cue
`browse_fpf_catalog`	Browse compiled patterns, routes, lexemes, and preface entries by part, status, and kind, one page at a time.	`browseFpfCatalogInputSchema` part?, status?, kind?, limit?, offset?, forceRefresh?	`browseFpfCatalogResultSchema` entries, total, offset, nextOffset?, filters, didYouMean?, snapshot	Use for discovery before reading or querying exact nodes.
`search_fpf`	Run ranked full-text search across compiled FPF nodes.	`searchFpfInputSchema` query, kind?, limit?, forceRefresh?	`searchFpfResultSchema` query, hits, total, snapshot	Use when the caller has words or concepts but not an exact ID.
`ask_fpf`	Return markdown-first FPF answers with grounding metadata.	`askFpfInputSchema` question, mode?, forceRefresh?, sessionId?	`askFpfResultSchema` markdown, ids, citations, constraints, gaps, confidence, status, snapshot	Use for chat answers; keep them compact and citation-backed.
`query_fpf_spec`	Return structured answer envelopes for FPF lookup and route selection.	`queryFpfSpecInputSchema` question, mode?, forceRefresh?, sessionId?	`queryResultSchema` answer, ids, relations, constraints, citations, gaps, confidence, status, snapshot	Use for deterministic planning context or machine-readable routing.
`read_fpf_doc`	Resolve one selector to canonical generated markdown and page metadata.	`readFpfDocInputSchema` selector, kind?, mode?, maxChars?, forceRefresh?	`readDocResultSchema` selector, resolvedAs, status, nodeId?, title?, docRef?, markdown?, headings?, preview?, snapshot	Use for exact FPF wording and cite the generated page path.
`get_fpf_index_status`	Inspect whether the runtime index exists and is fresh against the configured source.	`getFpfIndexStatusInputSchema` no parameters (bounded legacy placeholder ignored; other keys rejected)	`runtimeStatusSchema` sourcePath, sourceHash?, builtAt?, snapshotExists, currentSourceHash, fresh, compilerMode, artifacts, sessionCache	Use as the first reliance gate before trust-sensitive FPF lookup.

Section link: https://mcp.fpf.sh/#interface-contract.

First Successful Call

Use only fpf_reference. Call query_fpf_spec with question: "Project kickoff: align a project information system with roles and adoption next steps" and mode "compact". Return the most relevant FPF IDs, acceptance check, and next move.

Expect compact FPF IDs in ids. Check freshness at https://mcp.fpf.sh/api/fpf/status.

Good First Prompt

Use only fpf_reference. First call get_fpf_index_status. If the index is available, find the smallest useful FPF context for this work: <describe work>. Return Context | FPF IDs | Friction avoided | Acceptance check | Next move.

Keep answers compact. Read exact generated docs only when wording matters, and do not paste the full FPF into the chat.