MCP

Compass exposes an MCP (Model Context Protocol) server at /mcp. Any MCP-compatible AI tool can connect and query the knowledge graph using structured tools.

Setup

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "compass": {
      "type": "sse",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Cursor

Add to Cursor's MCP settings (Settings > MCP Servers):

{
  "compass": {
    "type": "sse",
    "url": "http://localhost:8080/mcp"
  }
}

Windsurf

Add to Windsurf's MCP configuration:

{
  "mcpServers": {
    "compass": {
      "serverUrl": "http://localhost:8080/mcp"
    }
  }
}

Tools

search_entities

Search the knowledge graph with keyword, semantic, or hybrid mode.

ParameterRequiredDescription
textYesSearch query
typesNoComma-separated entity types (e.g., table,topic)
sourceNoFilter by source system
modeNokeyword, semantic, or hybrid (default: keyword)
sizeNoMax results (default: 10)

get_context

Get full context about an entity: the entity itself, its relationships, and related entities.

ParameterRequiredDescription
urnYesEntity URN
depthNoTraversal depth, 1-5 (default: 2)

impact

Analyze downstream blast radius — what entities are affected if this entity changes.

ParameterRequiredDescription
urnYesEntity URN
depthNoDownstream traversal depth (default: 3)

get_documents

Get documents (runbooks, annotations, decisions) attached to an entity.

ParameterRequiredDescription
urnYesEntity URN

assemble_context

Assemble a curated, token-budget-aware context window for an AI agent task. This is the primary tool for agents — it replaces the pattern of calling search, context, impact, and documents separately.

ParameterRequiredDescription
queryYesWhat you're trying to accomplish
seed_urnsNoComma-separated entity URNs to start from
intentNoTask intent: debug, build, analyze, govern, general (default: general)
token_budgetNoMax tokens in response (default: 4000)
depthNoGraph traversal depth, 1-5 (default: 2)

The tool works in five phases:

  1. Seed resolution — If seed_urns are given, uses those. Otherwise, runs hybrid search to find the most relevant entities.
  2. Graph expansion — Walks edges bidirectionally from each seed up to the configured depth.
  3. Document fetching — Retrieves attached documents for seed and top-ranked related entities.
  4. Intent-aware ranking — Scores all entities by relevance. The intent parameter adjusts weights: debug prioritizes upstream lineage, analyze prioritizes metrics and dashboards, build prioritizes downstream consumers, govern prioritizes policies and ownership.
  5. Budget packing — Packs the highest-value context into the token budget. If the budget is exceeded, lower-ranked items are omitted and Truncated: yes is indicated.

Returns structured markdown with seed entities, related entities, relationships, documents, and provenance metadata.

Usage Patterns

Quick Start: Use assemble_context

For most agent tasks, assemble_context is the only tool you need:

assemble_context(query: "debug the user sessions pipeline", intent: "debug")
assemble_context(query: "what metrics come from this table", seed_urns: "table:user_sessions", intent: "analyze")

Composable Tools

For fine-grained control, agents can compose the individual tools:

  1. Discover — search_entities to find relevant entities
  2. Understand — get_context to see relationships and neighbors
  3. Assess risk — impact to evaluate downstream effects
  4. Get knowledge — get_documents for runbooks and decisions