MCP server

Give Claude Desktop, Cursor, Claude Code, Hermes or any MCP client the Lineage tools: search records about people who have died and get cited results.

All docs as plain text OpenAPI spec

There are two ways in. The remote server at https://api.lineage.rexstjohn.com/mcp speaks Streamable HTTP and takes your API key in the Authorization header; nothing to install. The stdio server, @lineage/mcp, runs on your machine for clients that start a local process. Both list the same tools and call the same endpoints, so the living-person gate, credits and rate limits are the same.

Cursor

Add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project), with your key in place of lin_sk_live_..., then reload. Cursor connects to the remote server directly.

{
  "mcpServers": {
    "lineage": {
      "url": "https://api.lineage.rexstjohn.com/mcp",
      "headers": {
        "Authorization": "Bearer lin_sk_live_..."
      }
    }
  }
}

Claude Desktop

Claude Desktop starts MCP servers as local processes. Build the stdio server once from a clone of the repo, then point Claude Desktop at it in claude_desktop_config.json (on macOS, ~/Library/Application Support/Claude/; on Windows, %APPDATA%\Claude\). Restart Claude Desktop and the Lineage tools appear in the tools menu.

git clone https://github.com/Verafyai/lineage-api.git
cd lineage-api
npm ci
npm run build:packages

{
  "mcpServers": {
    "lineage": {
      "command": "node",
      "args": [
        "/absolute/path/to/lineage-api/packages/mcp/dist/cli.js"
      ],
      "env": {
        "LINEAGE_API_KEY": "lin_sk_live_..."
      }
    }
  }
}

The packages are built and tested in the repo but not yet published to npm or PyPI. Until they are, run them from a clone of the repo, as shown below. The remote MCP server needs no install at all.

Claude Code

claude mcp add --transport http lineage https://api.lineage.rexstjohn.com/mcp --header "Authorization: Bearer $LINEAGE_API_KEY"

Hermes

Hermes reads MCP servers from mcp_servers in its config.yaml. Point it at the remote server:

mcp_servers:
  lineage:
    url: "https://api.lineage.rexstjohn.com/mcp"
    headers:
      Authorization: "Bearer lin_sk_live_..."

OpenClaw, Grok and OpenRouter models

OpenClaw uses the Lineage skill file instead of MCP; see the skills page. Grok, OpenRouter models and any OpenAI-compatible client take the same tools as function schemas from GET /v1/tools; see the tools page.

Tools

Every tool maps onto one endpoint in the API reference. Tools that start work (search_records, run_research) wait up to wait_seconds for the result, 60 by default, and otherwise return the id to read with get_search or get_run.

Tool	Endpoint	Charges credits
`search_records`	POST /v1/searches	Yes, see the description
`get_search`	GET /v1/searches/{id}	No
`get_record`	GET /v1/records/{id}	No
`resolve_subject`	POST /v1/subjects:resolve	Yes, see the description
`get_subject`	GET /v1/subjects/{id}	No
`select_candidate`	POST /v1/subjects/{id}:select	No
`check_vital_status`	POST /v1/subjects/{id}/vital-status	Yes, see the description
`run_research`	POST /v1/runs	Yes, see the description
`get_run`	GET /v1/runs/{id}	No
`export_gedcom`	GET /v1/searches/{id}/export	No
`list_sources`	GET /v1/sources	No
`get_source`	GET /v1/sources/{slug}	No
`list_models`	GET /v1/models	No
`draft_contact_request`	POST /v1/contact-requests	No
`list_archives`	GET /v1/archives	No
`get_key`	GET /v1/key	No

Try it

Ask: "Find records for Thomas Lincoln, 1778 to 1851, Kentucky and Illinois, and cite them." The agent calls search_records, waits for the quick search, and answers from records that each carry a citation URL. Ask for his children next and it follows a relative with from_record.

curl https://api.lineage.rexstjohn.com/mcp \
  -H "Authorization: Bearer $LINEAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Rules the tools follow

Searches about anyone who may be alive return living_person_blocked and cost 0 credits. Lineage researches someone only when a death date is on record, or a birth more than 110 years ago. A relative who may be alive comes back as { relation, living: true } with no name, dates or places.
Errors come back as tool errors with code, message, docs_url and fix, so the model can recover or explain.
When resolve_subject returns needs_input, the agent asks you the question. The tools never pick between close candidates.
The server is stateless: no sessions, no event stream on GET. Each POST carries the key.