API & MCP

Pick the surface you're working in. Each recipe is self-contained: one paragraph, one snippet. The data is the same — only the transport differs.

What's available

REST base URL: https://affinage-toxo.wi.mit.edu/api
MCP endpoint: https://affinage-toxo.wi.mit.edu/mcp
Interactive REST docs: /docs (Swagger UI)

REST endpoints

The site holds 10,904 gene cards, of which 994 carry a literature-derived annotation (at least one reading-pass discovery). The other 9,910 have no discoveries and no teleology; 9,909 of them return the placeholder narrative “No mechanistic discoveries found in literature.” — but a corpus may still be present: 1,737 of those cards have citation-ranked papers under /api/corpus, so check the corpus before concluding Affinage has nothing on a gene. The placeholder means Affinage found no mechanistic findings for the gene — it is not a finding that the gene is uncharacterised.

A further 0 annotated cards carry a refusal narrative that begins “Insufficient on-target evidence to synthesize a narrative.”: the reading pass found papers, but the synthesis pass judged none of them to be about the queried gene. Their discoveries are still served. Treat the exact placeholder, or a narrative beginning “Insufficient on-target evidence”, as a no-data result; a few annotated cards have narratives beginning “No mechanistic findings specific to…” that still carry discoveries, so check /api/discoveries before discarding a card.

A card groups the orthologous genes of the 4 sequenced T. gondii strains where they exist; 2,623 of 10,904 cards are single-strain. GET /api/gene/{symbol} and get_gene return the members as strains (strain, gene_id, name, product, UniProt accession); discoveries carry no strain column, so per-finding attribution lives in the narrative text. Live row counts: /healthz.

Endpoint	Returns
`GET /api/gene/{symbol}`	Full GeneRecord JSON
`GET /api/mechanistic_narrative/{symbol}`	Description paragraph
`GET /api/discoveries/{symbol}`	Reading-pass per-paper findings (annotated cards only — 994 of 10,904)
`GET /api/teleology/{symbol}`	Synthesis-pass mechanistic history (994 of 10,904 cards; 404 otherwise)
`GET /api/mechanism_profile/{symbol}`	Partners and complexes (the controlled-vocab term axes are empty in this build)
`GET /api/uniprot/{symbol}`	UniProt prefetch slice (no UniProt record for 2,279 of 10,904 cards — 404)
`GET /api/audit/{symbol}`	Deterministic R1–R11 audit flag (null if clean)
`GET /api/corpus/{symbol}`	Source papers (citation-ranked) (2,731 of 10,904 cards have a corpus, including 1,737 placeholder cards)
`GET /api/paper/{pmid}`	Paper lookup by PMID
`GET /api/search?q={term}`	Gene name / ToxoDB ID / alias search (exact, then a bare locus number, then prefix), then product-name matches — narrative text is not searched
`GET /api/list?round2=true`	Filtered gene listing (no round-2 genes in this build — returns `[]`)

MCP tools

Ten read-only tools mirror the REST endpoints above. They accept typed arguments (gene name or ID, PMID, row limit) and return structured JSON. The same coverage caveats apply.

get_gene
get_mechanistic_narrative
get_discoveries
get_teleology
get_mechanism_profile
get_uniprot
get_audit_flag
get_corpus
get_paper
search_genes

Lookups resolve a gene name, any strain's ToxoDB ID, or an alias to its gene card (e.g. GRA1 or TGME49_270250 → the card), and the response carries resolved_from so you can see the redirect.

Recipes

Click a surface to expand its recipe. Each one is a complete setup — no other steps needed unless noted.

Script (Python or curl) REST · no setup

Hit the REST API directly from any HTTP client. No authentication, no SDK, no MCP. Returns JSON.

# curl
curl https://affinage-toxo.wi.mit.edu/api/mechanistic_narrative/TG_205250

# Python
import requests
r = requests.get("https://affinage-toxo.wi.mit.edu/api/mechanistic_narrative/TG_205250")
print(r.json()["mechanistic_narrative"])

Claude.ai web MCP · custom connector

In a personal Claude.ai workspace, open Settings → Connectors → Add custom connector and paste the MCP endpoint. The Affinage tools appear in the conversation toolset.

https://affinage-toxo.wi.mit.edu/mcp

Many enterprise workspaces (Whitehead, most universities) disable custom connectors at the policy level — "Add custom connector" will be greyed out. Use the Claude Desktop recipe below instead; it routes around the policy.

Claude Desktop MCP · config file

In Claude Desktop, open Settings → Developer → Edit Config — this opens claude_desktop_config.json in your editor. Merge the snippet below into the file (if mcpServers already exists, just add the "affinage-toxo" entry inside it). Save, then fully quit Claude Desktop (⌘Q on macOS — closing the window isn't enough) and reopen.

{
  "mcpServers": {
    "affinage-toxo": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://affinage-toxo.wi.mit.edu/mcp"]
    }
  }
}

Requires Node.js — check with node --version in a terminal; install the LTS release from nodejs.org if missing. First launch is slower than usual while npx downloads mcp-remote. This recipe works through enterprise policies that block the web UI's custom-connector picker, because Desktop reads the local config file rather than going through workspace policy.

Claude Code (CLI) MCP · one-liner

If you use the Claude Code terminal CLI, register Affinage with a single command. The tools become available in your next session.

claude mcp add affinage-toxo --transport http https://affinage-toxo.wi.mit.edu/mcp

Cursor / other MCP clients MCP · streamable HTTP

Any client that speaks the streamable-HTTP MCP transport works the same way — point it at the endpoint. Cursor's MCP config lives at ~/.cursor/mcp.json; Continue, Windsurf, and other clients use their own locations, but the JSON shape is the same.

{
  "mcpServers": {
    "affinage-toxo": {
      "url": "https://affinage-toxo.wi.mit.edu/mcp"
    }
  }
}