# Assist With Family History — agent setup

Product: Assist With Family History is the user's durable private family-history research-to-story workspace. The assistant reasons, researches, compares, corrects, and drafts; the product owns identity, permissions, records, provenance, workflow state, and human review.
MCP endpoint: https://assistwithfamilyhistory.com/mcp
Transport: remote Streamable HTTP MCP with OAuth. Modern 2026-07-28 requests and stateless 2025-era fallback share one tool factory.
Setup page: https://assistwithfamilyhistory.com/ai
Support: https://assistwithlife.com/support is the one support desk for every Assist With site. No Assist With site has a support, feedback, or privacy email address, so never tell a person to email this product.

## Approval comes from the person, not from signing in
Signing in proves whose vault this is. It does not decide what your connection may do. The first call from a connection the person has not approved returns the machine error GRANT_REQUIRED. When you see it, stop and ask the person to approve the connection at https://assistwithfamilyhistory.com/app/settings/ai, choosing which permissions and which records it covers. Do not retry in a loop.
Other grant errors: GRANT_REVOKED (they turned it off — stop), GRANT_EXPIRED (ask them to renew), SCOPE_NOT_GRANTED (use only the tools tools/list returned for this connection), OUTSIDE_GRANT_BOUNDARY (that record is outside what they approved).
tools/list is filtered by what the person approved. Trust it; it is the exact surface this connection has.

## Required workflow
1. Call family_history_get_brief first.
2. Use family_history_search before creating records that may already exist.
3. Use family_history_get_context to hydrate stable IDs and updatedAt before corrections.
4. For a source that touches several people at once — a census page, a family group sheet — use family_history_save_records: one call, per-item results, and rows that fail come back named while the rest of the pass is still saved. Use family_history_save_complete_result when the pass must be all-or-nothing.
5. Preserve source/citation provenance, evidence-versus-conclusion status, conflicts, uncertainty, and blocked research honestly.
6. Queue context never grants domain-write authority. Use Queue tools only for work assigned to oauth-chosen-ai.

## Permissions a person can approve
- family_history:context:read — Read your research context. Read bounded briefs, search summaries, and the details of people, sources, events, stories, and research notes inside the boundary you choose. Limit: No files or images, no changes, no living-person private notes, and nothing outside the record boundary you choose.
- family_history:evidence:read — Open your reviewed evidence files. Receive the contents of source files, images, and person documents that you have already marked reviewed and allowed for AI use. Limit: Only reviewed, AI-allowed, unrestricted items inside your boundary. Delivered through this connection — the AI never receives a storage link it could share or scrape.
- family_history:evidence:write — Place new evidence in your private review queue. Upload an attributed image into private evidence storage and leave it unreviewed for you to inspect. Limit: Upload only. It cannot review rights, approve AI use, accept extracted dates or locations, change conclusions, share, or publish. Provider URLs are never returned.
- family_history:research:write — Save proposed research findings. Save people, relationships, events, sources, citations, candidate facts, and research tasks or findings as proposed work you can review. Limit: Proposals only. It cannot accept a conclusion for you, merge identities, publish, delete, or export anything.
- family_history:story:draft — Write private story drafts. Create and correct private story drafts and move a draft to your review queue. Limit: Draft and review only. It can never publish or edit a published story.
- family_history:queue:read — See the work you assigned. List and open the Queue directives you assigned to a chosen AI. Limit: Reading Queue work does not grant any permission over the records that work mentions.
- family_history:queue:work — Work the Queue items you assigned. Claim assigned Queue work, checkpoint progress, ask you a question, complete it, or report an honest failure. Limit: Only items you explicitly assigned to a chosen AI. Changing records still needs its own permission above.

## Tools
Canonical names are family_history_*. The pre-namespace names are kept as deprecated aliases on the same handlers and the same permission, so a client that connected earlier keeps working; prefer the canonical name.
- family_history_get_brief (family_history:context:read, read-only) [alias: get_family_history_brief] — Reads a short summary of your recent research.
- family_history_search (family_history:context:read, read-only) [alias: search_family_history] — Searches your research for matching people, sources, and notes.
- family_history_get_context (family_history:context:read, read-only) [alias: get_family_history_context] — Opens the full detail of one record you allowed.
- family_history_get_evidence (family_history:evidence:read, read-only) — Receives the contents of files you marked reviewed and AI-allowed.
- family_history_begin_evidence_upload (family_history:evidence:write, writes) — Starts a private, checksum-bound evidence upload for your review.
- family_history_finish_evidence_upload (family_history:evidence:write, writes) — Verifies an upload and places it in your private review queue.
- family_history_save_person (family_history:research:write, writes) [alias: save_person] — Adds or corrects one person.
- family_history_save_relationship (family_history:research:write, writes) [alias: save_relationship] — Adds or corrects one relationship between two people.
- family_history_save_event (family_history:research:write, writes) [alias: save_event] — Adds or corrects one event and who took part in it.
- family_history_save_source_evidence (family_history:research:write, writes) [alias: save_source_evidence] — Records a source, a citation, and the facts it supports.
- family_history_save_research_work (family_history:research:write, writes) [alias: save_research_work] — Records a research task or a finding, including dead ends.
- family_history_save_story_work (family_history:story:draft, writes) [alias: save_story_work] — Writes or corrects a private story draft.
- family_history_save_records (family_history:research:write, writes) — Saves a whole source's worth of proposed records at once, telling you exactly which rows worked.
- family_history_save_complete_result (family_history:research:write, writes) [alias: save_complete_result] — Saves one finished research pass, all of it or none of it.
- family_history_get_queue (family_history:queue:read, read-only) [alias: get_queue] — Reads the work you assigned to your AI.
- family_history_update_queue (family_history:queue:work, writes) [alias: update_queue] — Moves the work you assigned through its states.

## Never available through this connection
- Never exposed: Raw storage URLs or signed file links for private media
- Never exposed: Another vault owner's records, in any form, including their existence
- Never exposed: Living-person private notes in broad discovery
- Never exposed: Whole-vault export or bulk download
- Never exposed: Provider sessions, cookies, credentials, or access tokens
- Never exposed: Internal record tables, schema dumps, or raw database access
- Never permitted: Archiving or restoring records
- Never permitted: Exporting the vault
- Never permitted: Permanently deleting anything
- Never permitted: Publishing a story or any other public action
- Never permitted: Merging or splitting person identities
- Never permitted: Granting, changing, or removing sharing and access
- Never permitted: Acting on FamilySearch or any other outside provider
- Never permitted: Billing, account, or subscription changes

## Safety
- Do not put family_history:* permissions in the OAuth scope parameter of your authorization request. They are product permissions, not provider scopes: the sign-in provider does not issue them and will refuse the whole request with an invalid-scope error before the person ever sees a consent screen. Ask the provider only for its ordinary identity scopes. The person grants Family History permissions separately at https://assistwithfamilyhistory.com/app/settings/ai, and tools/list then shows you exactly what you have.
- Never provide or invent userId, ownerId, workspaceId, vaultOwnerId, or tenant IDs. The server derives the vault from verified OAuth.
- Never publish, delete, merge identities, change sharing, or perform external FamilySearch actions through this MCP surface.
- Never ask a person for a link to a private file, and never fetch one yourself. Use family_history_get_evidence; it returns reviewed, AI-allowed items as content blocks and tells you honestly what it could not deliver and why.
- Broad discovery withholds living-person notes. Person hydration includes only reviewed AI-allowed loose context and media.
- Evidence facts do not silently overwrite canonical person conclusions. Save candidates/conflicts and let the person review.
- Story writes are draft or review only. Published stories are human-gated and cannot be edited here.
- Reuse operationId for a safe retry of exactly the same write. Reuse createKey for the same durable record intent.

## Current / Partial / Later
Current in production: endpoint, OAuth challenge/metadata, bounded reads, server-derived owner, replay-safe writes, canonical UI-visible records, explicit PKCE consent, person-approved product grants, server-enforced scopes, record boundaries, immediate revocation on the very next request, batch record saves, protected evidence delivery, one disposable synthetic PKCE protocol-client research-to-story lifecycle, and exact synthetic cleanup. That protocol fixture was not a named AI-client compatibility proof.
Current in production: family_history_get_evidence returns real bytes for media the person uploaded into the vault — a scanned record reaches you as an image block, read straight from private storage with no link involved — and real text for person documents. Imported rows that hold only a file reference elsewhere still come back skipped with BYTES_NOT_AVAILABLE rather than a pretend delivery; the person can upload the file to that item to make it readable.
Current in production, awaiting joined client proof: family_history_begin_evidence_upload and family_history_finish_evidence_upload accept one checksum-bound JPEG, PNG, or WebP through a short-lived same-origin PUT capability and leave it Private, unreviewed, rights-unknown, and AI-use-off for the person. The isolated B2 storage boundary is provider-proved; no real chosen AI has yet completed upload, person review, later evidence read, and cleanup as one lifecycle.
Awaiting real-client proof: no AI client has yet completed a whole lifecycle here — discover, register, consent, list tools, read, write, fetch evidence, revoke, be denied. Deployed is not the same as proved by a client, and no client is named as working until it proves it. Broad client compatibility, fresh-device email verification, mobile setup, and refresh/reconnect sit here.
Partial: dynamic client registration is offered by the sign-in provider and is the supported onboarding path, but no client has been observed completing it here. Client ID Metadata Document discovery is deferred until the provider supports it; its validation is written and unused.
Later: publishing, deletion, identity merge, export, external provider actions, wider client matrix.

If tools look stale after a deploy: disconnect the MCP server, reconnect it, sign in again, and confirm the family_history_* names above appear before writing.