Claude Code wired to your repo as the single source of truth, seven MCP servers across two phases, and a credential runbook you can self-serve. This page is the working preview of the Phase 1 deliverable: it builds a valid .mcp.json for your exact stack, right here.
Seven MCP servers ship across Phase 1 and Phase 2; two more are staged for Phase 3. Each one is mapped to a real job in the annuity-search-engine workflow, not just installed for its own sake.
Direct, sandboxed read and write into your annuity-search-engine/platform clone, so Claude Code edits real files instead of working from pasted snippets. Access is fenced to the paths you list.
Branch, open PRs, review, and manage issues against annuity-search-engine/platform directly, keeping the repo as the single source of truth. GitHub's official remote server is the default; a local Docker build is the offline fallback.
Pull Dev-Mode specs, variables, and exact measurements from your design files so landing-page work is pixel-accurate. The official desktop server runs on loopback with no key.
Fetch and read live URLs for research and to verify competitor annuity data, rates, and citations before they land in the product. Anthropic's Python reference server, no key.
Generate on-brand hero and social imagery for landing pages from a prompt. Your brief names Ideogram (preferred) or Replicate; the recommendation panel explains why the provider choice matters for reliability.
Publish and update landing pages and CMS items directly to your Webflow site from Claude Code. The official remote server uses OAuth, so no token sits in the repo.
Post build updates and read team messages so the workflow reaches your Slack channel. The old reference server was archived; this uses the actively maintained community server.
Generate avatar and explainer videos via API for marketing. Deferred to Phase 3 in your brief, and worth a caveat before you commit to it.
Voiceover and text-to-speech for video automation. Deferred to Phase 3; the official ElevenLabs server is well maintained.
This is the working core of the handoff package. Pick the servers and options, and it generates the exact .mcp.json to commit to your repo root, the per-OS install commands, and the list of credentials to provision. It validates as you go and never touches the network.
{ "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/you/code/annuity-search-engine" ] }, "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}" } }, "figma": { "type": "http", "url": "http://127.0.0.1:3845/mcp" }, "fetch": { "command": "uvx", "args": [ "mcp-server-fetch" ] } } }
Your brief says Ideogram preferred, or Replicate. Straight answer: today Ideogram ships no official MCP server (only community packages under 5 stars), while Replicate ships an official, hosted one with OAuth and no key in your repo. So for a reliable Phase 2 I default to Replicate’s official server. If you specifically want Ideogram’s text rendering, I’d wrap the Ideogram v3 API in a small first-party MCP server I maintain, rather than depend on an unmaintained package. Toggle the provider above to see both configs side by side.
Expand any server for the real setup steps, the credential it needs and where to create it, the .mcp.json entry, and the one command that confirms it connected.
Direct, sandboxed read and write into your annuity-search-engine/platform clone, so Claude Code edits real files instead of working from pasted snippets. Access is fenced to the paths you list.
node --version); the server runs via npx, no global install./Users/you/code/annuity-search-engine). Add more paths as extra arguments to widen the sandbox..mcp.json at the repo root, then run claude and approve the project server when prompted.{ "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/you/code/annuity-search-engine" ] } }
This is how credentials are created, recorded, and handed to you, so you can rotate or revoke any of them without me in the loop. It maps directly to your OneTimeSecret and per-phase handoff requirements.
One key per service, scoped to the annuity-search-engine repo/site only. Never account-wide.
Every credential gets a row in the register: what, where created, scope, owner, rotation date.
The secret value moves through a one-time, self-destructing link. Nothing sensitive in chat or email.
The .mcp.json holds ${VAR} only. The value lives in a gitignored .env, so the repo stays clean.
| Credential | Scope | Rotation |
|---|---|---|
| GITHUB_PERSONAL_ACCESS_TOKEN GitHub fine-grained PAT | annuity-search-engine/platform only · Contents, PRs, Issues | 90 days |
| REPLICATE_API_TOKEN Replicate API token | Image generation · per-machine | on offboarding |
| WEBFLOW_TOKEN Webflow site token | Site-scoped · CMS + Pages | on offboarding |
You receive the full register for every credential created, plus an owner column, at the end of each phase.
# .env (gitignored, never committed) GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_xxx # fine-grained, repo-scoped REPLICATE_API_TOKEN=r8_xxx # Phase 2, image generation WEBFLOW_TOKEN=wf_xxx # Phase 2, if using local server # Claude Code expands ${VARS} from here into .mcp.json. # .gitignore already contains: .env and .env.local
.mcp.json is safe to commit because it contains only ${VAR} references. Remote OAuth servers (GitHub, Webflow, Figma remote) store no token at all.Claude Code works best when the repo is the source of truth and the structure is legible. Here is the target layout and the migration plan for annuity-search-engine/platform.
annuity-search-engine/ ├── .mcp.json # 7 MCP servers, project-scoped, committed ├── CLAUDE.md # standing brief Claude Code reads every session ├── .env # gitignored, secrets as ${VARS}, never committed ├── .gitignore ├── README.md ├── src/ # app code, migrated from your project folder │ ├── search/ # annuity search + ranking │ ├── data/ # providers, ingestion, normalization │ └── ui/ # landing pages, components ├── docs/ # the handoff packages, one per phase │ ├── phase-1-handoff.md │ └── credential-register.md ├── design/ # Figma exports, brand assets └── scripts/ # ops + automation
git mv so file history is preserved, not lost to a bulk copy.CLAUDE.md, .mcp.json, and .gitignore at the root; seed CLAUDE.md with the repo map and conventions.annuity-search-engine/platform and set it as the single source of truth; enable branch protection on main.You asked for documentation so you can self-serve basic ops. This is it: the everyday commands, how to add or change a server, and the five issues you are most likely to hit, each with a one-line fix.
claudestart Claude Code in the repoclaude mcp listsee every server + healthclaude mcp get githubinspect one server/mcpsign in to OAuth servers, in-sessionclaude doctordiagnose the installedit .mcp.jsonadd/remove a server, then re-approveclaude mcp add …add without hand-editingclaude mcp remove slackdrop a serverclaude mcp reset-project-choicesre-run project approval| If you see this | Do this |
|---|---|
| Server shows ⏸ Pending approval | Run claude in the repo and approve the project server (once). |
| Server shows ✗ failed | The referenced ${VAR} is not set. Export it in your .env and reload. |
| Figma won't connect | Open the desktop app, enter Dev Mode, and enable the local MCP server. |
| `uvx: command not found` | Install uv (see the generator's install tab), then reopen the shell. |
| Local GitHub server fails | Docker isn't running. Start Docker Desktop, or switch GitHub to remote. |
Each phase closes against a concrete acceptance list, not a vibe. This is the same checklist that goes in the handoff package. Tick through it to see the shape of the sign-off.
claude --version returns a version.mcp.json committed; claude mcp list shows all four Connected