Lacuna Research MCP

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

Agent plugin for Cursor

This repository also packages the hosted MCP connection and the two research skills as an Agent Plugin. Cursor supports this format.

To test it locally, copy this repository to ~/.cursor/plugins/local/lacuna-research-mcp, reload Cursor, and open Customize to check the two skills and the MCP connection. The plugin connects to https://lacuna.tiptreesystems.com/api/mcp; no local Python installation or Lacuna account is required. Enable either this connection or a manually configured Lacuna server to avoid duplicate tools.

Cursor and VS Code

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

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.

Manual configuration if the install link doesn't open

In Cursor, merge this entry into mcpServers in .cursor/mcp.json:

{

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

In VS Code, merge this entry into servers in .vscode/mcp.json:

{

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

Keep any existing server entries. Open your editor's MCP settings to verify the connection and enable Lacuna's tools for the conversation.

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-mcp

lacuna-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.git

cd lacuna-research-mcp uv sync --extra dev uv run lacuna-research-mcp

With pip:

cd <path-to-lacuna-research-mcp>

python3 -m venv .venv . .venv/bin/activate python -m pip install -U pip python -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