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

> Learn how to access the research vault via MCP server with this complete guide for jordan-gibbs/hyperresearch. Query, search, and inspect research vaults easily.

- Repository: [Jordan Gibbs/hyperresearch](https://github.com/jordan-gibbs/hyperresearch)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/cli/mcp_cmd.py). To start the server, run:

```bash

# 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:

```python
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:

```python
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:

```python

# 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:

```python

# 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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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.