How to Access the Research Vault via MCP Server: A Complete Guide

The Hyperresearch MCP server exposes eight read-only tools that enable agents to query, search, and inspect research vaults through a standardized Message Communication Protocol interface without requiring direct filesystem access.

To access the research vault via MCP server in the jordan-gibbs/hyperresearch repository, you launch a FastMCP instance that automatically discovers your vault by walking up the directory tree. This architecture allows AI agents and automation scripts to interact with your knowledge base through a secure, JSON-based API rather than manipulating files directly.

What Is the Hyperresearch MCP Server?

The MCP (Message Communication Protocol) server is a thin, tool-based API layer implemented in src/hyperresearch/mcp/server.py. When started, it creates a FastMCP instance that discovers the nearest vault by locating a .hyperresearch folder and registers eight read-only tools for vault inspection.

Unlike direct database or file access, this server abstracts the underlying SQLite schema and directory structure. It handles vault discovery via Vault.discover() in src/hyperresearch/core/vault.py and ensures data consistency by calling vault.auto_sync() before executing any query.

Available MCP Tools for Vault Access

The server registers the following tools, each mapping to specific vault operations:

Tool	Purpose	Primary Parameters
search_notes	Full-text search of notes	query, optional tag, status, parent, limit
read_note	Retrieve single note metadata and body	note_id
read_many	Batch-retrieve multiple notes	note_ids (comma-separated)
list_notes	List notes with filters (no bodies)	status, tag, parent, sort, limit
get_backlinks	Find notes linking to a specific note	note_id
get_hubs	Return most-linked-to hub notes	limit
vault_status	Summary of vault health and statistics	None
lint_vault	Run health checks for missing tags or broken links	rule (optional)

Each tool executes queries against the vault's SQLite schema and returns JSON-encoded results, making them ideal for programmatic consumption by MCP-compatible clients.

Starting the MCP Server

The CLI entry point lives in src/hyperresearch/cli/mcp_cmd.py. To start the server, run:

# From the root of a repository containing a hyperresearch vault

hyperresearch mcp

The command produces no output on success. The server initializes a stdio-based MCP transport and listens on stdin/stdout for JSON-RPC messages, ready for integration with Claude Desktop, Cursor, or custom MCP clients.

Querying the Research Vault

Once connected, agents can invoke tools to inspect vault contents. The following examples demonstrate common operations using the Python mcp client library.

Searching Notes

Use the search_notes tool to perform full-text searches with optional filtering:

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
import json

session = ClientSession(streamable_http_client("stdio://"))

result_json = session.call_tool(
    "search_notes",
    {"query": "machine learning", "tag": "ml", "limit": 5}
)

results = json.loads(result_json)
for note in results:
    print(f"- {note['title']} ({note['id']})")

Reading Individual Notes

Retrieve specific note content using read_note for single items or read_many for batch operations:

note_id = "transformer-architecture"
note_json = session.call_tool("read_note", {"note_id": note_id})
note = json.loads(note_json)

print("Title:", note["title"])
print("Summary:", note["summary"])
print("Body snippet:", note["body"][:200])

Analyzing Vault Structure

Discover relationships and hub notes within your knowledge graph:

# Find all notes linking to a specific note

backlinks = json.loads(session.call_tool("get_backlinks", {"note_id": "neural-networks"}))

# Identify central hub notes by link count

hubs = json.loads(session.call_tool("get_hubs", {"limit": 10}))

Health Checks and Maintenance

Monitor vault integrity and statistics:

# Get comprehensive vault statistics

status = json.loads(session.call_tool("vault_status", {}))
print(f"Total notes: {status['total_notes']}")
print(f"Unique tags: {status['unique_tags']}")
print(f"Broken links: {status['broken_links']}")

# Run linting rules

issues = json.loads(session.call_tool("lint_vault", {"rule": ""}))
print(f"Found {issues['total']} issues")

How the MCP Server Works Under the Hood

The server implementation in src/hyperresearch/mcp/server.py follows a consistent execution pattern for every tool invocation:

1. Vault Discovery: Each tool calls _get_vault(), which invokes Vault.discover() from src/hyperresearch/core/vault.py to locate the nearest .hyperresearch directory by traversing up the directory tree.

2. Synchronization: The server executes vault.auto_sync() to ensure the SQLite database reflects any external file changes before querying.

3. Query Execution: Tools perform operations against the vault's SQLite schema (such as search_fts or SELECT statements) and return structured JSON.

The @server.tool() decorator registers each function with the FastMCP instance, exposing them through the standardized MCP protocol while maintaining read-only access to preserve vault integrity.

Summary

• The MCP server in src/hyperresearch/mcp/server.py provides a tool-based API for vault inspection using the Message Communication Protocol.
• Launch the server with the hyperresearch mcp command from src/hyperresearch/cli/mcp_cmd.py to start a stdio-based transport.
• Eight read-only tools—including search_notes, read_note, and vault_status—enable full-text search, content retrieval, and health monitoring.
• The server automatically discovers vaults via Vault.discover() in src/hyperresearch/core/vault.py and maintains sync through auto_sync().
• All tools return JSON-encoded results suitable for AI agents and automated workflows.

Frequently Asked Questions

How does the MCP server locate the research vault?

The server calls Vault.discover() from src/hyperresearch/core/vault.py, which walks up the directory tree from the current working directory until it finds a folder named .hyperresearch. This discovery mechanism runs automatically when any tool is invoked, ensuring the correct vault is always targeted.

What is the difference between read_note and read_many?

The read_note tool retrieves a single note's complete metadata and body content using one note_id parameter, while read_many accepts a comma-separated list of note_ids for batch retrieval. Use read_many when you need to fetch multiple notes in a single round-trip to minimize transport overhead.

Can the MCP server modify vault contents?

No. The Hyperresearch MCP server exposes only read-only tools. The eight available operations—search_notes, read_note, read_many, list_notes, get_backlinks, get_hubs, vault_status, and lint_vault—all query the vault without altering files or database records, ensuring safe agent interaction.

How do I connect a custom client to the MCP server?

The server uses stdio-based transport by default. Import ClientSession from the mcp package (as demonstrated in src/hyperresearch/web/parallel_provider.py) and initialize it with a streamable HTTP client pointing to stdio://. Once connected, use session.call_tool() with the tool name and parameters dictionary to execute vault queries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}