HydraGraph MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@HydraGraph MCP Show me the impact of changing analyzeWithAI."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
HydraGraph MCP
AI coding agents such as Claude Code and Codex usually answer “what depends on this?” by searching for similar text and inferring the result. HydraGraph instead parses a real codebase into a structural call graph, persists that graph in HydraDB, and exposes it through MCP. The agent receives verified callers, callees, source locations, and change-impact paths instead of guesses—including dependencies that cross from a frontend fetch() call to the matching backend route.
Why HydraDB
HydraDB makes the code graph persistent and independently queryable; it is not a temporary cache rebuilt privately by an agent during each session. HydraGraph uses the self-hosted HydraDB OSS container and its OpenCypher HTTP endpoint:
POST /v1/graphs/{graph_id}/queryAST-derived nodes and CONTAINS, IMPORTS, CALLS, and CALLS_API relationships are written with parameterized OpenCypher queries. MCP tools then query those stored relationships for direct and transitive dependency evidence.
Related MCP server: codegraph-mcp
Quick start
Requirements: Node.js 20+, npm, Docker Desktop, and PowerShell. The bundled HydraDB launcher binds its HTTP, Bolt, and admin ports to localhost only.
git clone https://github.com/sayan365/hydragraph-mcp.git hydragraph
cd hydragraph
npm install
npm run build
# Start the self-hosted HydraDB OSS container and configure its local-only token.
npm run hydradb:start
$env:HYDRADB_TOKEN = "local-development-token-32-bytes"
# Expose the package's `hydragraph` executable on your local npm path.
npm link
hydragraph init
# Use any local TypeScript repository, or clone the verified Docwise target.
git clone https://github.com/sayan365/docwise.git ../target-docwise
hydragraph add ../target-docwise
# Starts the existing MCP stdio server; it waits silently for an MCP client.
hydragraph mcphydragraph init checks HydraDB and writes .hydragraph/config.json. hydragraph add replaces the generated code graph with data from the supplied repository. Run one repository per configured HydraDB graph.
An MCP client normally launches hydragraph mcp itself, so do not also keep a separate copy running. For Codex, add this to ~/.codex/config.toml and replace the launcher path with the absolute path on your machine:
[mcp_servers.hydragraph]
command = "node"
args = ["C:\\absolute\\path\\to\\hydragraph\\bin\\hydragraph.js", "mcp"]
env = { HYDRADB_URL = "http://127.0.0.1:8443", HYDRADB_TOKEN = "local-development-token-32-bytes", HYDRADB_NAMESPACE = "default" }The equivalent project-level .mcp.json configuration for Claude Code is:
{
"mcpServers": {
"hydragraph": {
"type": "stdio",
"command": "node",
"args": [
"C:\\absolute\\path\\to\\hydragraph\\bin\\hydragraph.js",
"mcp"
],
"env": {
"HYDRADB_URL": "http://127.0.0.1:8443",
"HYDRADB_TOKEN": "local-development-token-32-bytes",
"HYDRADB_NAMESPACE": "default"
}
}
}
}Restart the client after adding the configuration. The token shown above is the fixed credential generated by the localhost-only development launcher, not a production secret.
What it does today
find_callers(symbol)returns the code nodes that directly call an exact qualified symbol or HTTP route, with relationship and call-site evidence.impact_of_change(symbol)walks incomingCALLSandCALLS_APIrelationships to return the transitive blast radius with depths and source locations.explain_context(question)matches a natural-language question to a graph symbol and returns its callers, callees, evidence, and two-hop impact for the calling agent to reason over.
This verified question demonstrates the frontend-to-backend boundary:
explain_context("what would break in the frontend if the /api/analyze-document response format changed?")Relevant output from the live Docwise graph:
{
"matchedSymbol": "api._backend.route.POST./api/analyze-document",
"callers": [
{
"caller": "src.context.DocumentContext.DocumentProvider.analyzeWithAI",
"file": "src/context/DocumentContext.tsx",
"line": 140,
"relationship": "CALLS_API",
"evidence": "src/context/DocumentContext.tsx:154 fetch(\"/api/analyze-document\")"
}
],
"impact": [
{
"symbol": "src.context.DocumentContext.DocumentProvider.analyzeWithAI",
"depth": 1,
"relationship": "CALLS_API"
},
{
"symbol": "src.context.DocumentContext.DocumentProvider.scanDocumentFile",
"depth": 2,
"relationship": "CALLS"
}
]
}Reference run: real numbers
The verified target is sayan365/docwise, a real TypeScript/React document-analysis application.
Parsed 27 files, 92 nodes, 165 edges
65 CONTAINS
45 IMPORTS
51 CALLS
4 CALLS_API
6 Express route nodes
449 external or ambiguous calls left unresolved
0 static fetch calls left unresolvedCurrent scope
TypeScript and TSX parsing only.
51 of 500 ordinary call sites resolve to internal
CALLSedges (about 10%); the 449 unresolved sites are primarily external or ambiguous and are never guessed.One repository per configured HydraDB graph.
CALLS_APImatches staticfetch()paths to Express routes by path string; dynamic paths, Axios, GraphQL, and response-schema analysis are not modeled.explain_contextreturns a two-hop impact view by default.
Roadmap — not built yet
Multi-project graphs and project-aware namespacing.
Hosted or remote MCP instances per project.
Parsers for additional programming languages.
Team-wide context spanning services owned by different developers.
Architecture
┌──────────────────────┐ ┌─────────────────────┐ ┌──────────────────────┐
│ Target TS/TSX repo │───▶│ tree-sitter parser │───▶│ Self-hosted HydraDB │
│ src/ + api/ │ │ nodes + call edges │ │ persisted OpenCypher │
└──────────────────────┘ └─────────────────────┘ └──────────┬───────────┘
│
▼
┌──────────────────────┐
│ HydraGraph MCP stdio │
│ three graph tools │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Claude Code / Codex │
│ reasons over evidence│
└──────────────────────┘Tech stack and attribution
TypeScript on Node.js.
tree-sitter with
tree-sitter-typescriptfor TypeScript/TSX AST parsing.HydraDB, AGPL-3.0, as the self-hosted graph database and OpenCypher query engine.
Model Context Protocol TypeScript SDK for the stdio MCP server and tools.
Zod for MCP tool input schemas.
Docwise as the real validation target; it is not redistributed here.
HydraGraph MCP is available under the MIT License. Implementation status and evidence are tracked in docs/PRD.md.
Available Tools
3 toolsexplain_contextA
Given a natural-language question about the codebase, find the most relevant symbol and return its callers, callees, call-site evidence, and two-hop change impact from HydraDB. Use this structured graph data to answer the user's question yourself.
Inputs: question (required).
find_callersA
Find functions or methods that directly call an exact fully-qualified TypeScript symbol.
Inputs: symbol (required).
impact_of_changeA
Find the transitive blast radius of changing an exact fully-qualified TypeScript symbol.
Inputs: symbol (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools have clearly distinct primary purposes: find_callers for direct callers, impact_of_change for transitive blast radius, and explain_context for natural-language-driven exploration. Some overlap exists between find_callers and impact_of_change (the latter can include direct callers), but descriptions are sufficient to differentiate them.
Tool names are descriptive but not uniformly patterned. find_callers and explain_context use an imperative verb_noun form, while impact_of_change is a noun_phrase. This mixed convention is still readable, but inconsistent.
Three tools is on the lower end but reasonable for a focused code-analysis server covering direct query, impact analysis, and natural-language explanation. The set does not feel overly thin given the specificity of the domain.
The tools cover the core workflow of understanding callers and change impact. Missing explicit callee querying or symbol metadata retrieval could be gaps, but impact_of_change likely subsumes some of those needs. Overall, the surface is workable for its apparent purpose.
Maintenance
Related MCP Connectors
Repository knowledge graph MCP server for codebase understanding and debugging.
Shared context for your codebase: a hosted code knowledge graph over MCP. Free plan, OAuth sign-up.
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA local MCP server that gives AI coding agents symbol definitions, dependency graphs, and a live architecture vocabulary for TypeScript/JavaScript repos, with no network or embeddings.16 npmMIT
- AlicenseAqualityDmaintenanceAn MCP server that indexes TypeScript/JavaScript codebases into precise call and import graphs using the TypeScript compiler API, allowing Claude or any MCP client to query definitions, callers, callees, and perform impact analysis.7MIT
- AlicenseNot gradedqualityCmaintenanceSemantic code intelligence MCP server for TypeScript/JavaScript codebases, enabling AI agents to retrieve specific symbols, types, and relationships without reading entire files.21MIT
- AlicenseNot gradedqualityDmaintenanceCompiler-exact TypeScript code graph MCP server exposing find-references, change impact analysis, and repo map tools for AI agents, powered by the TypeScript compiler via ts-morph.MIT