Experimental, early beta. Data model and interfaces are unstable; expect breaking changes between releases.

Model Context Protocol

Noumenon exposes its knowledge graph as MCP tools so AI agents can query structured facts instead of scanning raw source. Works with Claude Desktop, Claude Code, or any MCP client.

Setup

Claude Desktop

Add a Noumenon entry to Claude Desktop's MCP config and restart the app.

Or run noum setup desktop. The CLI writes the file for you and adds Noumenon's CLAUDE.md guidance.

Config path: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "noumenon": {
      "command": "noum",
      "args": ["mcp"]
    }
  }
}

Claude Code

Drop a project-local .mcp.json in your repo. Optional: noum setup code also installs a PreToolUse hook that nudges the agent to call MCP first.

Or run noum setup code. The CLI writes the file for you and adds Noumenon's CLAUDE.md guidance.

Config path: .mcp.json (in your project root)

{
  "mcpServers": {
    "noumenon": {
      "command": "noum",
      "args": ["mcp"]
    }
  }
}

Any MCP Client

Spawn noum mcp over stdio. The launcher proxies to the local daemon.

Config path: Whatever shape your client expects. Command plus args.

{
  "mcpServers": {
    "noumenon": {
      "command": "noum",
      "args": ["mcp"]
    }
  }
}

Tool Catalog

Twenty-five tools across discovery, querying, pipeline control, introspection, and benchmarks. All return JSON; most accept the repo name or path as the first argument.

Cheap, Medium, Expensive

The three tools that surface knowledge from a digested repo sit on a clear cost gradient. Reach for the cheapest one that does the job.

  • noumenon_search — milliseconds, zero LLM calls. TF-IDF cosine similarity over per-file and per-component summaries. Returns ranked file paths with scores. The cheapest way to find "which files are about X." Use this when you want discovery without the price of a full agent loop.
  • noumenon_query — milliseconds, zero LLM calls. Run a named or raw Datalog query. The right tool when you know the question maps to existing structure ("hotspots," "files-by-layer," "top-contributors") and want the structured result back.
  • noumenon_ask — seconds, multiple LLM calls. Iterative agent. TF-IDF warm start, routing-model hint, then a loop over Datalog queries until it has enough to answer. Use when the question is open-ended or requires composing multiple facts. See Ask for how it works.

Discovery · 5

ToolPurpose
noumenon_statusEntity counts. Use this to verify the repo has been imported.
noumenon_get_schemaFull attribute and entity-type listing.
noumenon_list_queriesList all named Datalog queries.
noumenon_list_databasesAll known databases with pipeline state and cost.
noumenon_searchTF-IDF semantic search over file/component summaries.

Querying · 2

ToolPurpose
noumenon_queryRun a named Datalog query (with input args).
noumenon_askNatural-language question answered via the Ask agent.

Pipeline · 7

ToolPurpose
noumenon_importParse git history and files into Datomic.
noumenon_enrichResolve cross-file import edges.
noumenon_analyzeLLM extracts code segments per file.
noumenon_synthesizeIdentify components and architectural layers.
noumenon_updateSync to latest git state (import + enrich).
noumenon_digestRun the full pipeline end-to-end (idempotent).
noumenon_reseedDrop and rebuild a database from scratch.

Introspection · 5

ToolPurpose
noumenon_introspectRun the autonomous loop synchronously.
noumenon_introspect_startKick off introspection in the background.
noumenon_introspect_statusCheck progress on a running introspection.
noumenon_introspect_stopHalt a running introspection.
noumenon_introspect_historyPast introspection runs and their deltas.

Benchmarks · 3

ToolPurpose
noumenon_benchmark_runRun benchmarks against the configured question set.
noumenon_benchmark_resultsGet the latest run or look up by ID.
noumenon_benchmark_compareCompare two runs by per-layer score deltas.

Admin · 1

ToolPurpose
noumenon_artifact_historyHistory of analyzed artifacts (prompt/model drift).

MCP tool schemas are part of the OpenAPI mirror under HTTP API. Same shapes, both surfaces.