Lacuna Research MCP

[Lacuna Research MCP — Empower your coding agent for machine learning research]

[Python 3.11+] [MCP server] [MIT license]

Lacuna Research MCP

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.

Lacuna Research MCP gives AI researchers' coding agents:

• Generated research proposals. Explore research ideas generated with The Alien Space of 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.

For example, trace an implementation to its recorded paper relationships:

Find the paper behind Dao-AILab/flash-attention. Show the recorded connection to the repository and link the original paper.

This example follows repository → recorded paper relationship → paper and sources. Lacuna returns the official_code_for relationship to FlashAttention, with links to the repository and original paper. Inspect those sources to verify the connection. Run the example or work through the notebook.

Install · Research skills · First use · Tools · API reference · Configuration

Install

Cursor and VS Code

Use the hosted server with no local Python installation or Lacuna account:

[Add to Cursor] [Add to VS Code]

The buttons open your editor's MCP installation flow. Review the server URL and confirm installation. After connecting, ask the FlashAttention question above; your agent should use search_lacuna, get_resource, and get_paper.

{  "mcpServers": {    "lacuna-research": {"url": "https://lacuna.tiptreesystems.com/api/mcp"}  }}

{  "servers": {    "lacuna-research": {"type": "http", "url": "https://lacuna.tiptreesystems.com/api/mcp"}  }}

Hosted MCP server (Claude connector)

Use Lacuna's hosted MCP server with any client that supports Streamable HTTP. No local installation is required.

https://lacuna.tiptreesystems.com/api/mcp

In Claude, open Customize → Connectors → + Add → Add custom connector. Name it Lacuna Research, paste the URL above, and select No sign in if prompted for authentication. Finish adding it, then enable it from + → Connectors in your conversation.

For Team and Enterprise workspaces, the connector must first be added under Organization settings → Connectors. See Claude's custom connector setup for details.

Local installation

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.

Codex

Add the server with the Codex CLI:

codex mcp add lacuna-research -- uvx lacuna-research-mcp

Alternatively, add the following to ~/.codex/config.toml (or to .codex/config.toml in a trusted project for project-only setup):

[mcp_servers.lacuna-research]command = "uvx"args = ["lacuna-research-mcp"]

Run codex mcp list to verify the server is configured. The Codex app, CLI, and IDE extension share this configuration on the same machine.

Claude Code

Add the server for all of your projects with the Claude Code CLI:

claude mcp add --scope user lacuna-research -- uvx lacuna-research-mcp

Omit --scope user to add it only to the current project. Alternatively, add the following under the top-level mcpServers object in ~/.claude.json:

{  "mcpServers": {    "lacuna-research": {      "type": "stdio",      "command": "uvx",      "args": ["lacuna-research-mcp"]    }  }}

Run claude mcp get lacuna-research to verify the server is configured.

Claude Desktop

Open Settings → Developer → Edit Config, then add the server under mcpServers in claude_desktop_config.json:

{  "mcpServers": {    "lacuna-research": {      "command": "uvx",      "args": ["lacuna-research-mcp"]    }  }}

Restart Claude Desktop after saving the file.

Other MCP clients

For any client that supports local stdio MCP servers, use this standard configuration:

{  "mcpServers": {    "lacuna-research": {      "command": "uvx",      "args": ["lacuna-research-mcp"]    }  }}

Standalone command

Install the MCP server as a persistent command:

uv tool install lacuna-research-mcplacuna-research-mcp

Run it without installing a persistent command:

uvx lacuna-research-mcp

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.

Self-hosted HTTP server

To serve remote MCP clients over Streamable HTTP instead of stdio:

uvx lacuna-research-mcp --transport streamable-http --host 0.0.0.0 --port 8000

The endpoint is /mcp. The server is stateless and answers with JSON, so it can run behind a load balancer without session affinity. With the default --host 127.0.0.1, the server accepts only localhost Host headers, so bind a non-loopback address when a reverse proxy forwards a public hostname.

Latest development version

PyPI contains tagged releases. To try the latest code from the main branch instead:

uvx --from git+https://github.com/tiptreesystems/lacuna-research-mcp.git lacuna-research-mcp

Local development

With uv:

git clone https://github.com/tiptreesystems/lacuna-research-mcp.gitcd lacuna-research-mcpuv sync --extra devuv run lacuna-research-mcp

With pip:

cd <path-to-lacuna-research-mcp>python3 -m venv .venv. .venv/bin/activatepython -m pip install -U pippython -m pip install -e .

Research skills

The MCP server provides tools. These optional skills teach your agent how to use them for two research tasks:

Connect the MCP server first. Then, with Node.js 22.20+ installed, run the skills CLI from your project:

npx skills add tiptreesystems/lacuna-research-mcp

Choose the skills and agent you use. To install only the code-to-paper workflow:

npx skills add tiptreesystems/lacuna-research-mcp --skill lacuna-code-to-paper

Skills install to the current project by default. They don't install or configure the MCP server. Start a new agent session after installation if your client needs one to discover new skills.

First use

Ask one of the questions above in your connected agent, or try a reading-list question:

My list has FlashAttention and FlashAttention-2. What baselines or limitations should I read about for long-context attention?

For a reproducible example with no model API key, clone this repository and run:

uv run examples/code_to_paper.py

The notebook explains each step and compares the source trail with a single paper search. For direct tool use, the same flow is:

1. search_lacuna(query="FlashAttention", search_type="resource", resource_kind="codebase", limit=5)
2. Check the repository identity, then pass its returned ID to get_resource(resource_id_or_url=...).
3. Follow a returned publications[].paper_id with get_paper(artifact_id_or_url=..., view="context", figure_limit=0).

For literature search, use search_lacuna(query="methods for detecting prompt injection attacks", search_type="paper", limit=5). For generated proposals, use search_lacuna(query="LLM jailbreak defense", search_type="hypothesis", limit=5) and follow a returned ID with get_hypothesis. Generated proposals are ideas to investigate, not evidence of published findings.

About Lacuna

Lacuna's 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 The Alien Space of Science. The map spans more than 2.29 million papers, 215,000+ author profiles, 28,000+ research directions, 25,000+ research proposals, and 5,300+ venues — and it grows continuously as new arXiv and other AI papers are ingested.

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.

Wrapped APIs

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_CLIENT_TOKEN Optional token sent as X-Lacuna-Client-Token to identify a hosted MCP server to Lacuna for its own search rate limit.
• 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 — The Alien Space of Science

@inproceedings{artiles2026alien,  title     = {The Alien Space of Science: Sampling Coherent but Cognitively Unavailable Research Directions},  author    = {Artiles, Alejandro H. and Weiss, Martin and Brinkmann, Levin and Rahwan, Iyad and Sch{\"o}lkopf, Bernhard and Pal, Christopher and Larochelle, Hugo and Goyal, Anirudh and Rahaman, Nasim},  booktitle = {Advances in Neural Information Processing Systems},  year      = {2026},  eprint    = {2603.01092},  archivePrefix = {arXiv},  url       = {https://arxiv.org/abs/2603.01092}}

Research map — Lacuna

@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}}

License

MIT. See LICENSE.