MCP Connectors Reference¶

Aletheia's MCP connectors expose domain-specific knowledge graphs through the Model Context Protocol. Each connector is a self-describing server that advertises its graph schema — entity types, relationship types, property keys, and example queries — so the LLM can generate precise queries without trial and error.

This page covers the full tool surface, the Cypher analytics pipeline, cross-graph workflows, and the architecture that makes it work.

Graphiti MCP vs Aletheia MCP¶

Graphiti's core library supports advanced search with SearchConfig objects, entity/edge type filtering, center node anchoring, BFS traversal, community detection, and temporal filtering. Its built-in MCP server exposes only basic vector search — stripping out all graph-aware capabilities. Aletheia's connectors close that gap and add analytical tools on top.

Graphiti's Built-in MCP (5 tools)¶

Tool descriptions are generic with no schema information. The LLM has no way to know what entity types, relationship types, or property keys exist in the graph.

Aletheia's MCP (16 tools across 6 groups)¶

Semantic Discovery (enhanced from Graphiti)

• search — Unified search across nodes, edges, and communities. Supports entity/edge type filtering, five reranker strategies, center node proximity, BFS traversal, temporal filtering.
• explore_node — All connections, facts, and community memberships for a specific entity. Configurable traversal depth (1-4 hops).

Schema & Ontology Awareness (new)

• get_schema — Structural schema: node labels with property keys, relationship types with source/target patterns, counts. Cached with dirty-flag invalidation.
• get_ontology_structure — Full ontology class hierarchy in a single call. Returns entity classes with inheritance chains, alternative labels, and descriptions; relationship classes with source/target type constraints. Consumed programmatically by the reasoning engine during startup discovery.
• search_ontology — Semantic search over the companion ontology graph for schema definitions and entity types.
• explore_ontology — Deep-dive on a specific ontology class: properties, relationships, parent classes.

Graph Profiling (new)

• profile_graph — Server-side property sampling, relationship validation, and language detection. Returns property coverage percentages, sample values, detected languages, relationship degree statistics, and sample traversal paths. Runs all profiling queries server-side in a single call.

Cypher Analytics (new)

• run_cypher — Read-only Cypher queries with a four-stage validation pipeline. Typed JSON responses (scalar/tabular/graph/path) with metadata. Enforced via GRAPH.RO_QUERY.

Community Intelligence (enhanced)

• build_communities — Cluster entities using graph algorithms. Required before community search mode.

Data Management (inherited)

• add_memory, get_episodes, get_episode_context, delete_entity_edge, delete_episode, clear_graph, get_status (7 tools)

Capability Matrix¶

Self-Describing Connectors¶

Each connector advertises its domain schema in the tool metadata. The LLM knows that STEMS_FROM connects SafetyRecommendation to Occurrence, that SUPERSEDES connects one AirworthinessDirective to another, and that INVOLVED_AIRCRAFT connects Occurrence to Aircraft. With ontology structure discovery, the planner also knows inheritance chains (e.g., Aircraft inherits from Vehicle), alternative labels, and formal source/target constraints on relationship types.

Aviation Safety (ontology: eccairs — 540 classes)

Entity types: AerodromeGeneral, Aircraft, Country, Manufacturer, Occurrence, Operator
  Aircraft is_a: Vehicle, Thing | aliases: Airplane, Aeroplane
Edge types: INVOLVED_AIRCRAFT, LOCATED_IN, MANUFACTURED_BY, OCCURRED_AT, OPERATED_BY
  INVOLVED_AIRCRAFT ontology constraint: Occurrence → Aircraft

Safety Recommendations (ontology: safety_recommendations_ontology — 16 classes)

Entity types: Aircraft, Country, Manufacturer, Occurrence,
              SafetyInvestigationAuthority, SafetyRecommendation
  Occurrence is_a: Event
Edge types: INVOLVES, ISSUES, LOCATES, MANUFACTURES, STEMS_FROM
  STEMS_FROM ontology constraint: SafetyRecommendation → Occurrence

Airworthiness Directives (ontology: airworthiness_directives_ontology — 19 classes)

Entity types: AircraftType, AirworthinessDirective, DesignApprovalHolder, Document
Edge types: APPLIES_TO, APPROVED_BY, REFERENCES, SUPERSEDES
  APPLIES_TO ontology constraint: AirworthinessDirective → AircraftType
  SUPERSEDES ontology constraint: AirworthinessDirective → AirworthinessDirective

Tool Reference¶

search¶

Unified search across nodes, edges, and communities in a single call.

Reranker Strategies¶

Examples¶

# Safety recommendations stemming from Airbus incidents
search(query="Airbus safety issues",
       entity_types=["SafetyRecommendation"],
       edge_types=["STEMS_FROM"])

# Diverse results about pneumatic systems
search(query="pneumatic bleed air failure",
       search_mode="combined", reranker="mmr", limit=20)

# Everything structurally close to a known Boeing entity
search(query="system failures",
       center_node_uuid="<boeing-uuid>",
       reranker="node_distance")

# Temporal query: what was true on a specific date
search(query="airworthiness directives A320",
       valid_at="2024-06-15T00:00:00Z")

explore_node¶

Deep-dive on a specific entity showing all connections, facts, and community memberships.

get_schema¶

Structural schema introspection with caching.

Returns node labels with property keys, relationship types with source/target patterns, and counts. Results are cached in-memory and automatically invalidated when data changes via add_memory, delete_entity_edge, delete_episode, or clear_graph.

{
  "type": "schema",
  "graph_name": "safety_recommendations",
  "domain": "Safety Recommendations",
  "node_labels": {
    "SafetyRecommendation": {
      "count": 94,
      "properties": ["date_received", "id_value", "recommendation_text", "reply_type", "status"],
      "sampled": true
    },
    "Occurrence": {
      "count": 138,
      "properties": ["aircraftType", "date_value", "id_value", "registration"],
      "sampled": true
    }
  },
  "relationship_types": {
    "STEMS_FROM": {
      "count": 242,
      "patterns": [["SafetyRecommendation", "Occurrence"]]
    },
    "ISSUES": {
      "count": 158,
      "patterns": [["SafetyInvestigationAuthority", "SafetyRecommendation"]]
    }
  }
}

The sampled: true flag indicates property keys were discovered from a sample of nodes (50 per label) and may not be exhaustive. The :Entity dual label (a Graphiti convention) is filtered out — only meaningful type labels appear.

profile_graph¶

Server-side graph profiling that returns property coverage, sample values, language detection, and relationship validation in a single call. Where get_schema returns structural metadata (labels, property keys, counts), profile_graph adds statistical depth: which properties are populated, what languages the data is in, which relationships actually have data, and how densely connected they are.

{
  "entity_profiles": {
    "Occurrence": {
      "count": 10,
      "properties": {
        "description": {
          "coverage": 1.0,
          "sample_values": ["El 16 de julio...", "On 2 January..."],
          "detected_languages": ["es", "en", "fr"],
          "avg_length": 450
        },
        "primaryCause": {
          "coverage": 0.8,
          "sample_values": ["Bird strike during approach"],
          "detected_languages": ["en"],
          "avg_length": 80
        }
      }
    }
  },
  "relationship_profiles": {
    "INVOLVED_AIRCRAFT": {
      "count": 12,
      "source_target_patterns": [["Occurrence", "Aircraft"]],
      "avg_out_degree": 1.2,
      "sample_paths": [
        {"source": "Barcelona-El Prat incident", "target": "Airbus A321neo"}
      ]
    }
  },
  "language_summary": {
    "primary_languages": ["es", "en"],
    "multilingual_fields": ["Occurrence.description"]
  }
}

Key fields:

• coverage — Fraction of entities with this property populated (0.0 to 1.0). Properties below 100% need IS NOT NULL guards in Cypher.
• detected_languages — Languages found in text properties via langdetect. Multilingual fields need bilingual search keywords.
• avg_out_degree — Average outgoing edges per source entity. Indicates relationship density.
• confirmed — A relationship is confirmed if it has actual data (count > 0). Ghost relationships (declared in schema but empty) are flagged.

Primary consumer: Aletheia's reasoning engine calls profile_graph during Phase 0 capability discovery to build enriched domain knowledge for the investigation planner. The profiler data enables the planner to generate precise Cypher queries (correct property names, null checks, bilingual keywords) without hardcoded domain plugins.

get_ontology_structure¶

Full ontology class hierarchy in a single call. Returns all OntologyClass nodes from the companion ontology graph, partitioned into entity classes and relationship classes.

No parameters — returns the complete ontology for the connector's configured ontology graph.

{
  "ontology_graph": "eccairs",
  "entity_classes": [
    {
      "name": "Aircraft",
      "ontology_type": "class",
      "summary": "A heavier-than-air flying machine with fixed or rotary wings",
      "alt_labels": "Airplane, Aeroplane",
      "inherits_from": "Vehicle, Thing",
      "examples": ""
    },
    {
      "name": "Occurrence",
      "ontology_type": "class",
      "summary": "An aviation safety occurrence or event",
      "alt_labels": "",
      "inherits_from": "Event",
      "examples": ""
    }
  ],
  "relationship_classes": [
    {
      "name": "InvolvedAircraft",
      "ontology_type": "relationship_class",
      "summary": "Aircraft involved in an occurrence",
      "alt_labels": "involved_aircraft",
      "inherits_from": "",
      "source_entity": "Occurrence",
      "target_entity": "Aircraft",
      "examples": ""
    }
  ]
}

Key fields:

• ontology_type — class, abstract_class, or relationship_class. Entity-level types are in entity_classes; relationship types in relationship_classes.
• inherits_from — Comma-separated parent class names (or native list). Encodes the ontology hierarchy that explore_ontology can't surface (the graphs use RELATES_TO edges and inherits_from properties, not SUBCLASS_OF edges).
• alt_labels — Alternative names/synonyms for the class.
• source_entity / target_entity — For relationship classes only. Defines which entity types the relationship connects.

Primary consumer: Aletheia's reasoning engine calls get_ontology_structure once per connector during Phase 0 startup discovery. It populates EntityTypeInfo.inherits_from, EntityTypeInfo.alt_labels, EntityTypeInfo.ontology_description, and EdgeTypeInfo.ontology_source_type/ontology_target_type on the capability model — giving the investigation planner ontology-aware context without per-entity-type round trips.

search_ontology / explore_ontology¶

Each data connector includes embedded ontology access. These tools query the companion ontology graph semantically — no need to switch to a separate server.

Use cases:

• Domain-aware query translation — Decode aviation shorthand (SCF-NP, ATA 36) into precise search terms.
• Structural validation — Confirm that entities across graphs reference the same ontology class before correlating.
• Gap discovery — Compare actual data against the ontology schema to identify missing fields.

run_cypher¶

Read-only Cypher execution. Complements semantic search: use search for discovery, run_cypher for computation.

Full details in the Cypher Analytics section below.

Cypher Analytics¶

Validation Pipeline¶

Every query passes through four stages before execution:

flowchart TD
    A["LLM generates Cypher"] --> B["Stage 1: LLM Fixups"]
    B --> C["Stage 2: FalkorDB Dialect"]
    C --> D["Stage 3: Security Whitelist"]
    D --> E["Stage 4: Safety Injection"]
    E --> F["GRAPH.RO_QUERY"]

    B -.- B1["Smart quotes, unicode, HTML entities\nMissing RETURN injection\nRelationship direction fixes"]
    C -.- C1["Auto-fix: date→string, toLower\nReject: APOC, pattern comp.,\nEXISTS{}, CALL{}, map proj."]
    D -.- D1["Allow: MATCH, WHERE, RETURN,\nWITH, ORDER BY, LIMIT, UNWIND\nReject everything else"]
    E -.- E1["LIMIT 200 if missing\nN+1 truncation detection"]

Stage 1: LLM Fixups — Smart quotes to straight quotes, unicode normalization, code block stripping, missing RETURN clause injection (scope-aware: uses last WITH variables if present).

Stage 2: FalkorDB Dialect — Two tracks. Auto-fix applies lossless transformations: date('2024-06-01') becomes '2024-06-01', lower() becomes toLower(), PROFILE/EXPLAIN prefixes are stripped. Reject catches constructs that would change query semantics: APOC procedures, pattern comprehensions, EXISTS {} subqueries, CALL {} subqueries, map projections — each with a structured error and a concrete alternative suggestion.

Stage 3: Security Whitelist — Fail-safe gate. Only known read-only keywords pass: MATCH, OPTIONAL MATCH, WHERE, WITH, RETURN, ORDER BY, SKIP, LIMIT, UNWIND, UNION, CALL (restricted to db.* namespace). Everything else is rejected.

Stage 4: Safety Injection — LIMIT 200 auto-injected if no LIMIT clause present. Uses N+1 fetch internally (requests 201 rows) for accurate truncation detection without a separate count query.

Final backstop: GRAPH.RO_QUERY enforces read-only at the database engine level.

Response Format¶

All responses use typed JSON envelopes:

{
  "query": "MATCH (o:Occurrence)-[:OCCURRED_AT]->(a:AerodromeGeneral)-[:LOCATED_IN]->(c:Country) RETURN c.name AS country, count(o) AS incidents ORDER BY incidents DESC LIMIT 201",
  "auto_fixes": ["Injected LIMIT 200"],
  "type": "tabular",
  "row_count": 5,
  "truncated": false,
  "limit_applied": 200,
  "execution_ms": 6.1,
  "columns": ["country", "incidents"],
  "rows": [
    ["Spain", 4],
    ["France", 3],
    ["Netherlands", 1],
    ["Germany", 1],
    ["Italy", 1]
  ]
}

Result types:

FalkorDB Dialect Cheatsheet¶

- Dates are ISO strings — no date()/duration() functions
- No APOC procedures — use variable-length paths [*1..N]
- No pattern comprehensions — use WITH + collect()
- No map projections — return properties individually
- No CALL {} subqueries — use WITH + OPTIONAL MATCH
- Nodes use dual labels :Entity:TypeName — filter on :TypeName
- Use toLower()/toUpper() not lower()/upper()
- LIMIT auto-injected at 200 if missing

Example Queries¶

Aviation Safety¶

-- Count occurrences by manufacturer
MATCH (o:Occurrence)-[:INVOLVED_AIRCRAFT]->(a:Aircraft)-[:MANUFACTURED_BY]->(m:Manufacturer)
RETURN m.name AS manufacturer, count(DISTINCT o) AS occurrences
ORDER BY occurrences DESC

-- Occurrences in a specific country with aircraft details
MATCH (o:Occurrence)-[:OCCURRED_AT]->(ap:AerodromeGeneral)-[:LOCATED_IN]->(c:Country)
WHERE c.name = 'Spain'
MATCH (o)-[:INVOLVED_AIRCRAFT]->(a:Aircraft)
RETURN o.id_value, o.date_value, a.name, ap.name

Safety Recommendations¶

-- Open safety recommendations by issuing authority
MATCH (sia:SafetyInvestigationAuthority)-[:ISSUES]->(sr:SafetyRecommendation)
WHERE sr.status = 'Open'
RETURN sia.name, count(sr) AS open_srs
ORDER BY open_srs DESC

-- Recommendations stemming from occurrences involving a specific manufacturer
MATCH (sr:SafetyRecommendation)-[:STEMS_FROM]->(o:Occurrence)-[:INVOLVES]->(a:Aircraft)
WHERE a.name CONTAINS 'Airbus'
RETURN sr.name, sr.status, o.name

Airworthiness Directives¶

-- AD supersession chains
MATCH (newer:AirworthinessDirective)-[:SUPERSEDES]->(older:AirworthinessDirective)
RETURN newer.name AS current_ad, older.name AS superseded_ad

-- ADs by design approval holder
MATCH (ad:AirworthinessDirective)-[:APPROVED_BY]->(dah:DesignApprovalHolder)
RETURN dah.name, count(ad) AS ad_count
ORDER BY ad_count DESC LIMIT 10

-- ADs referencing specific documents
MATCH (ad:AirworthinessDirective)-[:REFERENCES]->(doc:Document)
WHERE doc.name CONTAINS '36'
RETURN ad.name, doc.name, doc.summary

Cross-Graph Workflows¶

The most powerful capability is chaining tools across connectors. Three patterns:

Pattern 1: Semantic Discovery then Cypher Analytics¶

Search finds relevant entities; Cypher computes over them.

1. search("bleed system failures", entity_types=["Occurrence"])
   → find relevant incident UUIDs

2. run_cypher("MATCH (o:Occurrence) WHERE o.id_value IN ['2024-0975-EU', ...]
   MATCH (o)-[:INVOLVED_AIRCRAFT]->(a:Aircraft)-[:MANUFACTURED_BY]->(m:Manufacturer)
   RETURN m.name, count(o)")
   → compute manufacturer statistics for those incidents

Pattern 2: Ontology Decode then Multi-Graph Search¶

The ontology translates domain codes into search terms that work across graphs.

1. search_ontology("SCF-NP ATA 36")
   → decode ECCAIRS codes to "System/Component Failure, Pneumatic"

2. search() on Aviation Safety graph → find matching incidents
3. search() on Airworthiness Directives graph → find applicable directives
4. search() on Safety Recommendations graph → find related recommendations
5. Correlate results using ontology-validated entity resolution

Pattern 3: Full Lifecycle Analysis¶

Combine discovery, traversal, and analytics across all connectors.

1. search("pneumatic overheat") on AD graph
   → find relevant airworthiness directives

2. explore_node("AD 2025-0096", depth=2)
   → map connected service bulletins and aircraft types

3. run_cypher() on SR graph
   → count open safety recommendations for the same aircraft type

4. run_cypher() on Aviation Safety graph
   → check for matching incidents

5. Synthesize: regulatory gap analysis with incident/recommendation/AD correlation

Architecture¶

Per-Connector Architecture¶

┌───────────────────────────────────────────────────────┐
│              Aletheia MCP Connector                   │
│            (one per knowledge domain)                 │
├───────────────────────────────────────────────────────┤
│  Self-Describing Tool Metadata                        │
│  (entity types, edge types, examples)                 │
├──────────────┬──────────────┬─────────────────────────┤
│  Semantic    │   Ontology   │   Analytics & Profiling │
│  Discovery   │   Access     │   get_schema            │
│  search      │   search_    │   get_ontology_         │
│  explore_    │   ontology   │   structure             │
│  node        │   explore_   │   run_cypher            │
│              │   ontology   │   profile_graph         │
├──────────────┴──────────────┴─────────────────────────┤
│         Graphiti Core Library                          │
│    (entity extraction, embeddings,                    │
│     temporal edges, community detection)               │
├───────────────────────────────────────────────────────┤
│         FalkorDB Graph Database                       │
│    (data graph + ontology graph)                      │
└───────────────────────────────────────────────────────┘

Each connector runs as an independent MCP server process. The LLM client (Claude Desktop, Cursor, etc.) connects to one or more connectors simultaneously, enabling cross-graph workflows.

Domain Profile Discovery¶

At startup, each connector introspects its graph to build a DomainProfile:

1. Query node labels and counts
2. Query relationship types and source/target patterns
3. Sample entity names per type
4. Load ontology descriptions (if ontology graph configured)
5. Generate dynamic tool descriptions and example queries from the profile

This profile feeds into every tool description, every example query, and the server-level instructions. When the graph evolves, restart the connector to refresh the profile.

Beyond startup profiling, the reasoning engine's Phase 0 capability discovery calls additional tools per connector:

• get_schema — structural schema (labels, property keys, counts, patterns)
• get_ontology_structure — full ontology hierarchy with inheritance chains, alternative labels, source/target constraints on relationship classes
• profile_graph — statistical analysis: property coverage, language detection, relationship degree statistics, sample paths

These three calls build the CapabilityModel that the investigation planner uses to generate precise queries. Ontology metadata (e.g., "Aircraft inherits from Vehicle", "APPLIES_TO connects AirworthinessDirective → AircraftType") is rendered inline with entity and edge type listings in the planner's structural context.

Performance¶

Measured on live graphs, February 2026.

Graph Sizes¶

Cypher Query Performance¶