Search Lacuna's ML research graph for papers, directions, authors, venues, and hypotheses.
The MCP server io.github.tiptreesystems/lacuna-research-mcp searches Lacuna’s machine learning research graph. It is intended to retrieve information about papers, research directions, authors, venues, and hypotheses from that graph.
🛠️ Key Features
Search Lacuna’s ML research graph
Query papers
Query research directions
Query authors
Query venues
Query hypotheses
🚀 Use Cases
Find relevant ML papers in Lacuna’s research graph
Explore connected research directions
Locate authors and venues associated with research items
Retrieve hypotheses tied to graph entities
⚡ Developer Benefits
Provides structured search over Lacuna’s ML research graph for agents and integrations
⚠️ Limitations
Only described as a search capability over papers, directions, authors, venues, and hypotheses; no other tools or behaviors are specified
🔬 Ground your coding agent in novel ideas, papers, and the ML landscape
Lacuna Research MCP gives AI researchers' coding agents:
Novel research proposals. Explore novel research ideas generated with Alien Science.
Research directions. Navigate concept clusters with linked papers, authors, and proposals.
Agent-ready literature. Search recent papers in markdown with source links.
Researcher intelligence. Trace authors, publications, directions, impact, and related researchers.
Landscape mapping. Compare venues, institutions, leading researchers, and publication activity.
Lacuna, built by Tiptree Systems, is a research map of machine learning: a heterogeneous knowledge graph linking papers, research directions, authors, venues, institutions, and generated research proposals, with a source trail from every derived object back to the exact paper and page that produced it. Its pipeline reconciles scholarly records from OpenAlex, OpenReview, DBLP, and arXiv; extracts concept elements from paper text and clusters them into research directions (Lacuna paper); and samples novel research proposals from those directions with Alien Science. The map spans more than 730,000 papers, 190,000+ author profiles, 38,000+ research directions, and 3,000+ research proposals built from over 15 million concept elements — and it grows continuously as new arXiv and other AI papers are ingested.
The easiest way to install Lacuna Research MCP is to ask your coding agent, such as Codex or Claude Code:
Install and configure the lacuna-research-mcp package from PyPI for this client.
For manual setup, the instructions below use uvx to run the latest tagged release from PyPI. Install uv first; Lacuna Research MCP requires Python 3.11 or newer.
If this exits with a prerelease error (for example, "Python 3.14.0rc2 is a prerelease..."),
your uv is using an early Python 3.14 prerelease that the MCP SDK does not support.
Update uv (uv self update), install a released Python (uv python install 3.14),
or run uvx --python 3.13 lacuna-research-mcp.
Latest development version
PyPI contains tagged releases. To try the latest code from the main branch instead:
search_lacuna(query="methods for detecting prompt injection attacks", search_type="paper", limit=10) (production lexical+semantic paper ranking by default)
get_paper(artifact_id_or_url="art_79c57fbfec094f26b79c422cf08fed34") (defaults to view="context")
get_direction(cluster_id_or_url=25108) (defaults to view="context")
search_lacuna(query="ImageNet", search_type="resource", resource_kind="dataset") (datasets linked to papers; follow up with get_resource)
Scope
The corpus covers machine learning and AI research: papers, research directions, authors' research output, venues, institutions, generated research hypotheses, and research resources (GitHub repositories, Hugging Face datasets and models, Zenodo records) linked to papers. It does not contain biographies, news, or non-research web content. Agents should answer questions outside that scope from other sources.
What it exposes
search_lacuna
Uses Lacuna's public /api/v1/search endpoint for directions, papers, authors, venues, institutions, hypotheses, and resources. Explicit paper searches (search_type="paper") use the server's production lexical+semantic ranker when the other ranking arguments remain at their defaults. Pass search_type="hypothesis" for hypothesis search. Pass search_type="resource" for code repositories, datasets, models, and demos linked to papers, optionally filtered with resource_kind (codebase, dataset, model, demo) and provider (github, huggingface, zenodo); for example, resource_kind="dataset" finds benchmark datasets. Resource search rejects date_from/date_to, venue, year sorts, and semantic ranking (resources carry no dates, venues, or embeddings).
get_hypothesis(hypothesis_id_or_url, view="context")
Hypothesis/proposal. view="context" (default) is a compact single-fetch proposal context (summary, abstract, linked directions); view="full" returns the server's version record with version history and signal counts. Proposal bodies are in versions[].markdown.
get_direction(cluster_id_or_url, view="context")
Research direction/cluster. view="context" (default) requests the compact agent-oriented summary; view="full" returns the raw cluster record.
get_direction_papers(cluster_id_or_url, page, limit, view="compact")
Paginated papers attached to a direction. view="compact" (default) returns citation-ready rows (id, url, title, year, venue, a few authors, abstract snippet); view="full" returns the raw upstream paper records.
get_paper(artifact_id_or_url, view="context", figure_limit=None, include_resources=True)
Paper lookup with available versions; use a version’s artifact ID to read it. Linked resources (code repositories, datasets, models, and demos) are included by default in context and full views; pass include_resources=False to omit them. Other views ignore this option. view="context" (default) requests the compact agent-oriented context; other views are "full", "preview", "blog", "figures", "concepts", or "neighbors". In context view, figure_limit caps the figure preview (server default 3; pass 0 to suppress previews while keeping a figures_truncated signal).
get_resource(resource_id_or_url)
Resource lookup by id (from resource search or get_paper's resources list) or Lacuna /resource/... URL: external URL, summary, facets (tasks, modalities, size, license), provider metrics, README/card excerpt, linked papers under publications (with paper_id and relationship such as dataset_for), related directions, and mentioned resources.
Author tools:
get_author_context(…, view="context"), get_author_papers, get_author_directions, and get_author_neighbors. Start with get_author_context, which defaults to the compact agent-oriented view (capped papers plus a readable impact_directions list instead of raw impact_clusters telemetry). Use the dedicated papers, directions, and neighbors tools to page through those collections without repeating the author context. view="full" returns the server-bounded full-shape context (collections remain capped at 100). Pass include_neighbors=true to explicitly include similar authors; this may add significant server latency.
Venue and institution tools:
get_venue_context(…, view="context"), get_institution_context(…, view="context"), get_institution_authors. Context tools default to compact (capped lists, duplicated blocks dropped; venue keeps a recent-activity slice that always includes the requested year). Use get_institution_authors to page through an institution's complete author list.
GET /api/v1/search (resource_kind and provider are sent as repeated kind and provider query params and require search_type="resource" or "all". author_id_or_url constrains search_type="paper" to one author, accepting a raw author ID or Lacuna author page URL. fields restricts/weights the text fields used for lexical ranking, e.g. title^4,abstract, and selects the experimental lexical ranker; for a default relevance-sorted paper search, this bypasses the production lexical+semantic ranker. Allowed fields are title, abstract, summary, concepts, name, top_names, venue, description, topics, provider_key, paper_titles, each valid only for the types that carry it — title: paper/cluster/venue/hypothesis/resource; description/topics/provider_key/paper_titles: resource; abstract/summary/concepts: paper; name: author/institution/venue; top_names: cluster/hypothesis; venue: paper/venue (search_type="all" spans all). Weights must satisfy 0 < weight <= 100. Unknown fields, out-of-range weights, type-incompatible fields, and fields combined with ranking_profile="semantic" are rejected, since the server would otherwise silently drop, cap, or ignore them.)
view="context" → GET /api/v1/context/author/{author_id}?view=compact; view="full" → GET /api/v1/context/author/{author_id} (include_neighbors=true explicitly requests similar authors)
For id-or-URL arguments, pass either the raw id returned by search_lacuna or the corresponding Lacuna page URL. The MCP normalizes Lacuna-relative url and *_url fields to absolute URLs, and it also absolutifies Lacuna links (including /resource/... pages) inside fields named summary_markdown, article_markdown, markdown, content, or description.
get_author_context is bounded server-side in both views. The default compact view returns a curated briefing; view="full" returns the larger complete shape with embedded collections capped at 100. Use get_author_papers and get_author_directions rather than trying to page embedded context collections.
Search requests are capped at 50 results per call, and direction-paper page
requests are capped at 100 results per call.
In search_lacuna, date_from and date_to are inclusive publication-date
bounds. Accepted formats are YYYY, YYYY-MM, and YYYY-MM-DD; for example,
date_from="2020", date_to="2022-03" includes papers from January 1, 2020
through March 31, 2022.
search_lacuna exposes these ranking profiles:
default / lexical
The default profile for all searches. With search_type="paper", sort="relevance", and fields unset, it uses the server's production lexical+semantic ranker with graceful fallback. The MCP's default search_type="all" uses the server's default lexical ranking instead.
semantic
Use for embedding-based paper retrieval. The semantic query omits the normal lexical ranking leg, but the server can still overlay exact-title lexical matches. Only supported for paper and all searches (only papers have semantic embeddings), and not with resource_kind/provider filters.
bm25_title_abstract / bm25
Use for lexical matching constrained to title and abstract. Rejected for author and institution searches (those records have no title or abstract fields).
All searches use the server default unless ranking_profile is provided. The MCP rejects unsupported profile/type combinations because the server would otherwise fall back to substring search and silently ignore the requested ranking profile.
sort accepts relevance (default), year_desc, and year_asc. Year sorts cannot be combined with ranking_profile="semantic" — the server would silently ignore the sort — so the MCP rejects that combination; for recent-and-relevant queries, keep semantic ranking and constrain recency with date_from/date_to instead.
Environment variables
LACUNA_SITE_URL
Defaults to https://lacuna.tiptreesystems.com
LACUNA_MCP_TIMEOUT
Defaults to 30
LACUNA_MCP_MAX_RETRIES
Defaults to 2; applies to timeouts, transport errors, and HTTP 429, 502, 503, and 504 responses.
LACUNA_MCP_USER_AGENT
Defaults to lacuna-research-mcp/{package_version}
LACUNA_MCP_BEARER_TOKEN
Optional bearer token sent as Authorization: Bearer ... for private Lacuna deployments.
LACUNA_MCP_LOG_LEVEL
Defaults to WARNING (one of DEBUG, INFO, WARNING, ERROR, CRITICAL). The default keeps normal operation quiet; lower it only for debugging, since INFO/DEBUG let the HTTP client log full request URLs — including the search query string — to stderr, which some MCP hosts retain.
Environment variables are read once when the MCP server is created, or on the first direct tool/API call if the module is imported without calling create_mcp().
Implementation layout
The server is a thin MCP adapter over Lacuna's HTTP API. The implementation is split by responsibility:
lacuna_research_mcp/server.py
MCPServer app creation, tool registration, lifespan cleanup, and the lacuna-research-mcp CLI entrypoint.
lacuna_research_mcp/tools.py
MCP tool functions. Each tool normalizes its inputs, calls the matching Lacuna API endpoint through the shared client helpers, and returns JSON-compatible data.
lacuna_research_mcp/client.py
Runtime HTTP access to Lacuna: the event-loop-bound httpx.AsyncClient, retry handling, error wrapping, JSON parsing, URL normalization on responses, and api_get/api_object/api_payload.
lacuna_research_mcp/config.py
Runtime constants, RuntimeConfig, package user-agent construction, and environment parsing.
lacuna_research_mcp/ids.py
Helpers that accept either raw ids or Lacuna page URLs and extract safe API path segments.
lacuna_research_mcp/normalize.py
Response post-processing for relative Lacuna URLs and markdown links.
lacuna_research_mcp/errors.py
User-facing exception type for Lacuna API access failures.
Notes
get_paper and get_direction default to view="context". These context views request Lacuna's compact agent-oriented payloads by default to keep MCP responses small. Paper context includes summary_markdown when available (otherwise abstract), authors, and figures; direction context includes summary_markdown, capped papers/authors/related directions, and truncation markers. Use view="full" when you need the raw metadata, and the other paper views (preview, blog, figures, concepts, neighbors) when you want one isolated sub-resource.
An explicit relevance-sorted paper search with no custom fields defaults to the server's production lexical+semantic ranker. Set ranking_profile="semantic" for embedding-based retrieval (with a possible exact-title overlay) or "bm25_title_abstract" for title-and-abstract lexical matching.
Most detail tools accept either the id returned by search or the corresponding Lacuna URL.
Relative Lacuna URLs in url/*_url response fields and fields named summary_markdown, article_markdown, markdown, content, or description are normalized to absolute URLs.
Venue and institution keys are opaque hashes (for example d7bf22905bd6), never human-readable names like icml. Find the key with search_lacuna(search_type="venue") first, or pass a /venue/... page URL.
Citation
If you find our work helpful, feel free to cite the papers behind Lacuna's research-proposal generation and research map.
Research-proposal generation — Alien Science
bibtex
@inproceedings{artiles2026alien,
title = {Alien Science: Sampling Coherent but Cognitively Unavailable Research Directions from Idea Atoms},
author = {Artiles, Alejandro H. and Weiss, Martin and Brinkmann, Levin and Goyal, Anirudh and Rahaman, Nasim},
booktitle = {ICLR 2026 Workshop on Post-AGI Science and Society},
year = {2026},
url = {https://openreview.net/forum?id=XZWkDET1ia}
}
Research map — Lacuna
bibtex
@misc{weiss2026lacunaresearchmapmachine,
title = {Lacuna: A Research Map for Machine Learning},
author = {Martin Weiss and Miles Q. Li and Alejandro H. Artiles and Yacine Mkhinini and Chris Pal and Hugo Larochelle and Nasim Rahaman},
year = {2026},
eprint = {2606.26246},
archivePrefix = {arXiv},
primaryClass = {cs.DL},
url = {https://arxiv.org/abs/2606.26246}
}
