Skip to main content
Glama
HyperspaceDB MCP Server

HyperspaceDB MCP Server

Official
by YARlabs

HyperspaceDB MCP Server

MCP TypeScript HyperspaceDB License: MIT

The HyperspaceDB MCP Server (mcp-hyperspacedb) exposes the complete low-level data plane, cognitive geometry engine, graph navigation, and administration interface of HyperspaceDB to Large Language Models (LLMs) via the Model Context Protocol (MCP).

NOTE

Looking for drop-in conversational agent memory?
If you are setting up plug-and-play long-term memory for Claude Desktop, Cursor, Windsurf, or OpenWebUI, use mcp-hyperspace-memory instead (npx -y mcp-hyperspace-memory@latest).
mcp-hyperspacedb is the full-featured database and geometry server designed for developers, data pipelines, and advanced cognitive agents requiring fine-grained control over vector spaces, collections, graph topologies, and cache systems.


πŸš€ Key Architectural Capabilities

1. Geometric Diagnostics & Curvature Analysis

Diagnose latent data topology using Gromov $\delta$-hyperbolicity over Riemannian and pseudo-Riemannian manifolds:

  • hyperspace_analyze_geometry: Employs the 4-point Gromov condition to recommend the ideal manifold metric (lorentz, poincare, cosine, or l2).

2. Cognitive Agent Diagnostics (Chain-of-Thought Stability)

Evaluate the geometric stability of multi-step reasoning traces:

  • hyperspace_analyze_thought_stability: Calculates Lyapunov Convergence of a reasoning trajectory. Distinguishes whether the model's reasoning converges toward a stable attractor or diverges into chaotic hallucinations.

  • hyperspace_predict_momentum: Forecasts future thought trajectories via Koopman momentum extrapolation.

  • hyperspace_get_trust_score: Computes geodesic trust scores along thought sequences.

3. Hyperbolic Hierarchy & Graph Traversal

  • hyperspace_get_subsumption_tree: Traces taxonomic subsumption trees in hyperbolic space ($H^{33}$).

  • hyperspace_get_concept_parents: Identifies hypernym/parent concepts along the Lorentz cone.

  • hyperspace_graph_traverse: Multi-hop BFS/DFS path exploration in the HNSW knowledge graph.

  • hyperspace_explore_graph: Extracts interactive subgraphs (nodes and links) for 2D/3D visualization.

  • hyperspace_find_clusters: Detects emergent semantic clusters directly in the vector space.

4. Advanced Search & Vector Data Plane

  • hyperspace_search_text: Hybrid semantic + BM25 lexical search with adjustable fusion weight (hybrid_alpha).

  • hyperspace_search_wasserstein: Optimal Transport (Earth Mover's Distance) semantic distribution search.

  • hyperspace_insert_text / hyperspace_get_points / hyperspace_delete_points: Point-level CRUD operations.

5. Collection Lifecycle & Hardware Acceleration Maintenance

  • Full control over collection creation with quantization schemes (none, medium, medium_plus, turbo, extreme).

  • L0 Hot Tier cache administration (cache_stats, cache_clear, cache_config).

  • Server-side flow matching reconsolidation (trigger_reconsolidation), collection freezing, HNSW index rebuilding, and disk vacuuming.


Related MCP server: io.github.avaazquezz/mcp-qdrant

πŸ› οΈ Installation & MCP Host Configuration

Quick Start with npx

npx -y mcp-hyperspacedb@latest

Host Configurations

Add to your MCP host configuration (e.g. claude_desktop_config.json, ~/.codeium/windsurf/mcp_config.json, or Cursor Settings):

☁️ 1. YAR.INK Managed SaaS

{
  "mcpServers": {
    "hyperspacedb": {
      "command": "npx",
      "args": ["-y", "mcp-hyperspacedb@latest"],
      "env": {
        "HYPERSPACE_HOST": "the.yar.ink",
        "HYPERSPACE_API_KEY": "sk_YOUR_API_KEY"
      }
    }
  }
}

🏠 2. Local Self-Hosted Instance (Default Auth)

{
  "mcpServers": {
    "hyperspacedb": {
      "command": "npx",
      "args": ["-y", "mcp-hyperspacedb@latest"],
      "env": {
        "HYPERSPACE_HOST": "localhost:50051",
        "HYPERSPACE_API_KEY": "I_LOVE_HYPERSPACEDB"
      }
    }
  }
}

πŸ”’ 3. Local DB + Cloud v5 Embedding API Key (Two-Key Setup)

When running a secured local engine while leveraging continuous cloud embeddings:

{
  "mcpServers": {
    "hyperspacedb": {
      "command": "npx",
      "args": ["-y", "mcp-hyperspacedb@latest"],
      "env": {
        "HYPERSPACE_HOST": "localhost:50051",
        "HYPERSPACE_API_KEY": "my_local_secret",
        "YAR_API_KEY": "sk_YOUR_YAR_API_KEY"
      }
    }
  }
}
  • HYPERSPACE_API_KEY: Authenticates with local gRPC engine (localhost:50051).

  • YAR_API_KEY (or legacy CDE_API_KEY): Authenticates with cloud embeddings endpoint.


🧩 Complete Tool Inventory (31 Tools)

πŸ“Š Data Plane Tools

Tool

Required Parameters

Optional Parameters

Description & Return Value

hyperspace_search_text

collection, text

top_k, hybrid_alpha, bm25_options

Semantic + lexical hybrid search. Returns array of matching records with id, score, and payload.

hyperspace_search_wasserstein

collection, text

top_k

Optimal Transport (Wasserstein) search. Returns array of top matches ranked by Wasserstein distance.

hyperspace_insert_text

collection, id, text

metadata

Inserts text under numeric id with auto-vectorization. Returns status string or error.

hyperspace_get_points

collection, ids

β€”

Retrieves vector coordinates and metadata for a list of point IDs. Returns JSON array of points.

hyperspace_create_collection

collection

dimension, metric, quantization, encryption_key

Creates a new vector space with chosen geometry, quantization, and optional client-side Zero-Knowledge encryption. Returns { success } object.

hyperspace_delete_collection

collection

β€”

Permanently deletes a collection and its vectors. Returns { success } object.

hyperspace_list_collections

β€”

β€”

Lists all active collections. Returns array of { name, dimension, metric, count, encrypted }.

πŸ•ΈοΈ Graph & Hierarchical Navigation Tools

Tool

Required Parameters

Optional Parameters

Description & Return Value

hyperspace_link

collection, source_id, target_id

relation, weight

Explicitly creates a directed, labeled, weighted edge between two entities in the CSR vector-graph.

hyperspace_link_batch

collection, edges

β€”

Atomically bulk-inserts explicit directed edges in the CSR graph.

hyperspace_unlink

collection, source_id, target_id

relation

Deletes an explicit directed edge with zero-lag invalidation.

hyperspace_induce_edges

collection, rules

β€”

Declaratively induces graph edges from existing document metadata (path_hierarchy, foreign_key, exact_match).

hyperspace_graph_traverse

collection, start_id

max_depth, max_nodes

Multi-hop BFS graph traversal starting from start_id. Returns graph paths and visited nodes.

hyperspace_explore_graph

collection, start_id

max_depth, max_nodes

Traverses graph and outputs nodes and links formatted for visual renderers.

hyperspace_get_neighbors

collection, id

layer, limit

Returns local connectivity and neighboring nodes at a given HNSW graph layer.

hyperspace_get_subsumption_tree

collection, root_id

max_depth

Returns hierarchical Lorentz cone subsumption tree starting from root_id.

hyperspace_get_concept_parents

collection, id

layer, limit

Traverses upward along the Lorentz cone to retrieve parent concepts.

hyperspace_find_clusters

collection

min_cluster_size

Detects emergent semantic clusters in vector space. Returns cluster centroids and member IDs.

🧠 Geometry & Cognitive AI Tools

Tool

Required Parameters

Optional Parameters

Description & Return Value

hyperspace_analyze_geometry

vectors

samples

Computes Gromov $\delta$-hyperbolicity. Returns { delta, recommendation } (lorentz, poincare, cosine, l2).

hyperspace_analyze_thought_stability

trajectory

curvature

Computes Lyapunov exponent along a Chain-of-Thought path. Classifies as STABLE or CHAOTIC.

hyperspace_predict_momentum

collection, trajectory_ids

steps, curvature

Forecasts next cognitive steps using Koopman momentum extrapolation.

hyperspace_get_trust_score

collection, trajectory_ids

curvature

Evaluates geodesic path consistency and returns trust score (0.0–1.0).

hyperspace_trigger_reconsolidation

collection

learning_rate

AI Sleep Mode: Triggers Flow Matching server optimization for concepts in collection.

βš™οΈ System, Cache & Maintenance Tools

Tool

Required Parameters

Optional Parameters

Description & Return Value

hyperspace_get_stats

collection

β€”

Merges gRPC telemetry, collection stats, logical clock, and HTTP cache stats into a JSON object.

hyperspace_cache_stats

collection

β€”

Retrieves hit rate, miss rate, and memory usage for the L0 Hot Tier Cache.

hyperspace_cache_clear

collection

β€”

Flushes all entries from the L0 Cache for the target collection. Returns { success }.

hyperspace_cache_config

collection, policy

ann_threshold

Updates L0 Cache eviction policy (lru, lfu, ttl) and similarity threshold.

hyperspace_freeze_collection

collection

β€”

Locks collection into read-only mode to prevent new inserts.

hyperspace_unfreeze_collection

collection

β€”

Unlocks a frozen collection to permit modifications.

hyperspace_rebuild_index

collection

β€”

Triggers server-side HNSW index rebuild and optimization.

hyperspace_vacuum

β€”

β€”

Purges deleted tombstones and reclaims fragmented disk space.


πŸ’» Local Development

cd integrations/mcp-hyperspacedb
npm install
npm run build
npm run dev

πŸ“œ License

MIT Β© YARlabs

Available Tools

35 tools
clarify_and_split_intentB

Alias for hyperspace_query_planner. Evaluates intent clarity, asks clarifying questions if ambiguous, and splits multi-part questions into isolated search queries.

Inputs: raw_user_query (required), context, collections, max_sub_queries.

hyperspace_analyze_geometryA

Calculate Gromov Delta-hyperbolicity either for a named collection on the server or over supplied vectors (array of numeric arrays). Returns {delta, recommendation: 'lorentz'|'poincare'|'cosine'|'l2'}.

Inputs: samples, vectors, collection.

hyperspace_analyze_thought_stabilityA

Calculate Lyapunov Convergence of a trajectory (Chain of Thought). Returns a JSON object {lyapunov_exponent, classification: 'stable'|'chaotic'} - negative result means stable/converging, positive means chaotic/hallucinating.

Inputs: trajectory (required), curvature.

hyperspace_cache_clearB

Clear / purge all items in the L0 Cache for a specific collection. Returns ok/error status object.

Inputs: collection (required).

hyperspace_cache_configB

Update L0 Cache configuration (eviction policy, ANN threshold) for a specific collection. Returns updated config as JSON result.

Inputs: policy (required), collection (required), ann_threshold.

hyperspace_cache_statsB

Get cache statistics (hits, misses, policy, etc.) for a specific collection's L0 Hot Tier Cache. Returns stats object as JSON result.

Inputs: collection (required).

hyperspace_create_collectionC

Setup new memory spaces (collections) with specific vector dimension, metric geometry, and quantization level. Returns the created collection config as JSON result.

Inputs: collection (required), metric, dimension, quantization, +1 more.

hyperspace_delete_collectionB

Permanently delete a collection and all of its vectors. Returns a result object with ok status or error.

Inputs: collection (required).

hyperspace_delete_pointsC

Delete a single vector point from a collection by its ID. Returns a result object with ok status or error.

Inputs: id (required), collection (required).

hyperspace_explore_graphB

Traverse the graph and return nodes and links in a format ready for visualization. Requires collection and start_id of the starting node.

Inputs: start_id (required), collection (required), max_depth, max_nodes.

hyperspace_find_clustersA

Detect emergent structure/hierarchy in collection. Returns a JSON array of clusters, each {cluster_id, members: [...], centroid, size}, filtered by min_cluster_size.

Inputs: collection (required), min_cluster_size.

hyperspace_freeze_collectionB

Freeze a collection to make it read-only, preventing new inserts. Returns ok/error status object.

Inputs: collection (required).

hyperspace_get_concept_parentsB

Retrieve parent concepts in a hierarchical collection. Requires collection and the concept id. Returns a JSON list of parent nodes.

Inputs: id (required), collection (required), layer, limit.

hyperspace_get_neighborsB

Explore local connectivity of a concept in the vector index graph. Requires collection name and id of the node/concept. Returns a list of neighboring nodes as JSON result.

Inputs: id (required), collection (required), layer, limit.

hyperspace_get_pointsB

Retrieve vector coordinate and metadata for a list of point IDs. Requires collection name and ids array of point IDs.

Inputs: ids (required), collection (required).

hyperspace_get_statsB

Get detailed statistics for the named collection. Returns a JSON object with count, dimension, metric, logical_clock, and storage stats. Merges metadata, cache stats and WriteBuffer size.

Inputs: collection (required).

hyperspace_get_subsumption_treeB

Retrieve the Lorentz hierarchy subsumption tree starting from a given root_id; returns the tree as JSON in the given collection.

Inputs: root_id (required), collection (required), max_depth.

hyperspace_get_trust_scoreC

Evaluate stability and trust score for a given thought trajectory path. Requires collection and trajectory_ids array of trajectory node IDs.

Inputs: collection (required), trajectory_ids (required), curvature.

hyperspace_graph_traverseA

Deep graph exploration starting from node start_id inside collection. Finds logical paths between concept A and context B for complex reasoning/cross-referencing. Returns a JSON object {paths: [...], nodes: [...], edges: [...]} bounded by max_depth and max_nodes.

Inputs: start_id (required), collection (required), max_depth, max_nodes.

hyperspace_induce_edgesC

Declaratively induce explicit graph edges from existing document metadata attributes (path_hierarchy, foreign_key, exact_match). Parameters: collection, rules array.

Inputs: rules (required), collection (required).

hyperspace_insert_textB

Store a new factual claim or memory: insert text into collection under numeric id (auto-vectorized). Returns a JSON object {ok: true, id} on success or {ok: false, error} on failure.

Inputs: id (required), text (required), collection (required), metadata.

hyperspace_list_collectionsA

List all active collections. Returns a JSON array of objects, each with {name, dimension, metric, count} metadata fields.

Inputs: no named parameters.

hyperspace_pdk_extensionB

Invoke a native HyperspaceDB PDK Extension (e.g. 'git_ast' for AST codebase indexing & blast radius, 'embed' for structure-aware Markdown ingestion, 'shield', 'chem', 'bio', 'fin', 'sec', 'legal', 'onto').

Inputs: action (required), extension (required), payload.

hyperspace_predict_momentumB

Forecast future agent thought paths using Koopman momentum extrapolation. Requires collection and trajectory_ids array; steps sets prediction horizon. Returns predicted trajectory summary as JSON.

Inputs: collection (required), trajectory_ids (required), steps, curvature.

hyperspace_query_plannerA

Enterprise RAG Query Planner. Evaluates user intent before vector search: detects ambiguous/underspecified questions (requesting multiple-choice user clarification) and decomposes multi-part queries into parallel sub-queries.

Inputs: raw_user_query (required), context, collections, max_sub_queries.

hyperspace_rebuild_indexB

Rebuild and optimize the HNSW index on the server for a specific collection. Returns rebuild status/result as JSON.

Inputs: collection (required).

hyperspace_search_textB

Search a collection for entries semantically similar to text (natural language query). Returns a JSON array of up to top_k results, each with id, score, and stored payload.

Inputs: text (required), collection (required), top_k, bm25_options, +1 more.

hyperspace_search_wassersteinA

Advanced Optimal Transport (Wasserstein) search inside collection for text. Compares distributions/complex concept overlap. Returns a JSON array of top_k matches ranked by Wasserstein distance, each with id, score, payload.

Inputs: text (required), collection (required), top_k.

hyperspace_trigger_reconsolidationB

AI Sleep Mode: trigger Flow Matching on the server to optimize the geometric representation of concepts in collection based on usage/context. Returns a JSON object {ok, iterations, loss_before, loss_after}.

Inputs: collection (required), learning_rate.

hyperspace_unfreeze_collectionA

Unfreeze a previously frozen collection to allow inserts again. Returns ok/error status object.

Inputs: collection (required).

hyperspace_vacuumB

Perform vacuuming on the database to permanently purge deleted vectors and reclaim disk space. Returns vacuum status and reclaimed-space result.

Inputs: no named parameters.

hyperspace_verify_generationC

Tribunal Router (Mathematical Anti-Hallucination Guardrail): Verify whether an LLM generated answer stays within the geometric entailment cones and geodesic boundaries of retrieved context IDs.

Inputs: collection (required), llm_answer (required), context_ids (required), check_geodesic, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 35 tools

    Disambiguation3/5

    Most tools are distinct, but there is direct duplication between hyperspace_query_planner and clarify_and_split_intent, which is explicitly an alias. Graph exploration tools (explore_graph, graph_traverse, get_neighbors, find_clusters) also overlap enough to cause misselection, despite descriptions helping.

    Naming Consistency4/5

    Almost all tools follow a clear hyperspace_verb_noun snake_case pattern. The only notable deviation is clarify_and_split_intent, which lacks the server prefix and is an alias for another tool.

    Tool Count2/5

    35 tools is heavy for the apparent scope, with many niche analysis, cache, and PDK extension operations. Several advanced tools feel bolted on rather than essential to the core vector-graph/memory workflow.

    Completeness4/5

    Coverage is broad: collections, points, text search, explicit and induced graph edges, traversal, clustering, cache, maintenance, and verification. Minor gaps exist around updating existing point content and updating collection configuration, but most workflows have a path.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to interact with a Qdrant vector database by exposing collection, point, vector, payload, snapshot, search, recommendation, discovery, and observability operations as MCP tools.
      13
      168 PyPI
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to turn documents into vectors, perform approximate nearest neighbor search with HNSW, and filter by metadata via MCP tools for RAG workflows.
      MIT
    • F
      license
      B
      quality
      B
      maintenance
      Enables AI agents to query an air-gapped enterprise knowledge vault via seven MCP tools for deterministic and hybrid retrieval, entity graph traversal, context compression, archive inspection, onboarding scans, and node status.
      7
      -