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.

The server is hosted on Railway and sleeps when idle, so the first call after a quiet period takes 20–60 s to warm up.

What's available

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

REST endpoints

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
`GET /api/teleology/{symbol}`	Synthesis-pass mechanistic history
`GET /api/mechanism_profile/{symbol}`	Controlled-vocab terms
`GET /api/uniprot/{symbol}`	UniProt prefetch slice
`GET /api/audit/{symbol}`	Deterministic R1–R10 audit flag (null if clean)
`GET /api/corpus/{symbol}`	Source papers (citation-ranked)
`GET /api/paper/{pmid}`	Paper lookup by PMID
`GET /api/search?q={term}`	Full-text search across narratives
`GET /api/neighborhood/{symbol}?hops=N`	Graph neighborhood (cytoscape JSON)

MCP tools

Ten read-only tools mirror the REST endpoints above. They accept typed arguments (gene symbol, PMID, hop count) and return structured JSON.

get_gene
get_mechanistic_narrative
get_discoveries
get_teleology
get_mechanism_profile
get_uniprot
get_audit_flag
get_corpus
get_paper
search_genes

Lookups are HGNC alias-aware: a previous or alias symbol resolves to its current record (e.g. ZNRD1 → POLR1H), 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.wi.mit.edu/api/mechanistic_narrative/HJURP

# Python
import requests
r = requests.get("https://affinage.wi.mit.edu/api/mechanistic_narrative/HJURP")
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.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" entry inside it). Save, then fully quit Claude Desktop (⌘Q on macOS — closing the window isn't enough) and reopen.

{
  "mcpServers": {
    "affinage": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://affinage.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 --transport http https://affinage.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": {
      "url": "https://affinage.wi.mit.edu/mcp"
    }
  }
}