Connect your AI

Give the AI you already trust a seat at your research bench. Once connected, your assistant can read the records you show it, capture what they say as claims you review, keep your research log as it works, and suggest where to look next — and nothing it produces enters your tree until you approve it. Heartwood runs a local MCP server — stdio, and Streamable HTTP on 127.0.0.1 — so your evidence goes only to the model you personally chose, never through us.

Claude Desktop is the one client Heartwood can configure for you with a single click, from inside the app (Settings → Connect) — that's the only one-click path, and the only client we've verified end to end. Every other client below is a short manual setup using that client's own standard MCP configuration mechanism; we've written each one up from that vendor's own docs, but haven't tested it ourselves, so treat the vendor's docs link as the final word if anything looks off.

Claude Desktop

Open Heartwood and press Settings → Connect — it writes the config below for you, nothing to copy. To do it by hand instead: open Settings → Developer → Edit Config, which opens ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) at the top-level key mcpServers. Paste this in and restart Claude Desktop completely (quit, don't just close the window):

{
  "mcpServers": {
    "heartwood": {
      "command": "heartwood",
      "args": ["mcp"]
    }
  }
}

Claude Desktop's local MCP server docs.

Claude Code

Add Heartwood from the CLI. Project scope writes to .mcp.json; user scope writes to ~/.claude.json — both keep the server under the mcpServers key, and both stdio and HTTP transports are supported:

claude mcp add heartwood -- heartwood mcp

# or, to make it available in every project:
claude mcp add heartwood --scope user -- heartwood mcp

Claude Code's MCP quickstart.

ChatGPT & Codex

ChatGPT's desktop app and Codex share one configuration file — ~/.codex/config.toml (or a per-project .codex/config.toml) — in TOML, not JSON: each server is its own [mcp_servers.<name>] table with command, args, and env. The CLI writes it for you:

codex mcp add heartwood -- heartwood mcp

Which produces:

[mcp_servers.heartwood]
command = "heartwood"
args = ["mcp"]

This works against a server on localhost. ChatGPT's desktop app reads this same Codex config — ChatGPT on the web does not: the web app only uses remote, plugin-supplied MCP connectors, so it has no way to reach a server running on your machine.

ChatGPT & Codex MCP docs.

Gemini CLI

Add Heartwood from the CLI, or edit the JSON yourself at ~/.gemini/settings.json (user scope) or .gemini/settings.json (project scope), under the mcpServers key — use command for stdio or httpUrl for the HTTP transport:

gemini mcp add heartwood heartwood mcp

Which produces:

{
  "mcpServers": {
    "heartwood": {
      "command": "heartwood",
      "args": ["mcp"]
    }
  }
}

Gemini CLI's MCP server docs.

Claude Cowork

Straight answer: this doesn't work for a local server today. Cowork lets end users add remote HTTP/SSE connectors only — a local stdio server like Heartwood's isn't user-configurable there. If you want Heartwood connected to Claude, use Claude Desktop or Claude Code instead (both in this list) — Cowork isn't the right client for this yet.

Claude Cowork's extension docs.

Any other MCP client

Heartwood speaks standard MCP, so any MCP-capable client can connect — point it at the same config this page already carries. For stdio, that's the block above: command heartwood, args ["mcp"]. If your client prefers a network connection instead of a subprocess, Heartwood also speaks Streamable HTTP on 127.0.0.1 — see the connection section of the MCP reference for that config and the discovery-file details.

Three things to try first

Talk to your assistant the way you'd brief a research helper — plain language, real questions:

“Here's a photo of my great-grandmother's marriage record — read it and capture what it says so I can review the claims.”
“What do we actually know about Arthur Fernwood so far, and which parts are well-sourced?”
“I'm stuck on who Eliza's parents were. Look at what we have and suggest where to search next.”

Everything your assistant produces lands in a visibly separate pending lane, next to the source it came from, waiting for your review — it proposes, you decide. When you want more ideas, the prompt cookbook has a full set of starter prompts for real research sessions.

Optional: give your assistant a research discipline

Once connected, your assistant already knows how to call every Heartwood tool — that part needs nothing extra. If you want it to also follow a genealogist's research discipline (state a question, build a source plan, log every search, be explicit about what's still unconfirmed) rather than improvising, see the Heartwood Genealogical Proof Standard (GPS) skill: a short, plain-text guide that tells an AI assistant how to research the way a professional genealogist would, with wiring instructions for the assistant you use. It's entirely optional — Heartwood's connection works exactly the same without it — and you can edit or replace it with your own approach at any time.

Let your assistant read the docs itself

Your assistant can learn everything Heartwood offers without you explaining it. Give it this address: heartwood.family/llms.txt — a machine-readable index of these docs, built for AI assistants to navigate on their own. For the full catalogue of what it can call, point it at (or browse yourself) the MCP reference.