HyperspaceDB MCP Server

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.

🛠️ 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