Synapse MCP
Synapse MCP is a local, persistent code-knowledge graph server that empowers AI agents to search, understand, edit, review, debug, and manage codebases safely.
Search code semantically, by symbol, or regex with structured results.
Explore caller/callee graphs, cycle detection, and structural context.
Retrieve pre-edit safety packs, explanations, and onboarding reading orders.
Modify files safely with dry-run simulation, lint validation, blast-radius checks, atomic writes, and rollback.
Review diffs and commit ranges for blast radius, broken contracts, and risk.
Resolve stack traces to AST root causes and suggested reproducing tests; trace execution flow.
Analyze codebase language mix, public API surface, dead-code deletion safety, dependencies, contracts, and refactor opportunities.
Assess test coverage, find relevant tests, recommend test targets, and configure Trunk linting.
Manage multiple repositories: register, list, archive, restore, unregister, and handle Git worktrees.
Inspect files, read raw chunks, and count lines with optional outline compression.
Persist knowledge via summaries, query-to-chunk learning, and cached pattern retrieval.
Control indexing: check health/status, trigger re-indexing, and discover live tool capabilities.
Provides AST-aware code intelligence for C++ codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Clojure codebases, including semantic search, caller/callee graphs, and refactoring analysis.
Provides AST-aware code intelligence for Dart codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Elixir codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Erlang codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for F# codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for GraphQL schemas and queries, enabling structural search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Haskell codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for HCL (HashiCorp Configuration Language) files, enabling structural search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for JavaScript codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Julia codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Kotlin codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Lua codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for OCaml codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for PHP codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Python codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Ruby codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Rust codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Scala codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Shell scripts, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Solidity codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Swift codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Terraform configurations, enabling structural search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for TypeScript codebases, including semantic search, dependency graphs, and refactoring analysis.
Provides AST-aware code intelligence for Zig codebases, including semantic search, dependency graphs, and refactoring analysis.
Synapse MCP Server
A persistent code-knowledge graph for AI agents. Runs locally. Writes safely.
🏗️ Currently in Preview. Synapse MCP is actively evolving. We want your feedback — open an issue to tell us what breaks, what's missing, or what would make you switch from grep for good.
Synapse MCP is a free, 100% local MCP server that turns your codebase into a persistent, in-memory AST knowledge graph. Claude, Cursor, Copilot, and every MCP-compatible agent gets exact caller trees, semantic search, safe atomic writes, and diff-aware change review — without a single byte of your code leaving the machine.
# Linux / macOS
curl -fsSL https://downloads.synapse-mcp.dev/install.sh | sh
# Windows PowerShell
irm https://downloads.synapse-mcp.dev/install.ps1 | iexWhat Synapse actually does
Most code-graph tools stop at discovery: index the codebase, answer questions about it, done. Synapse goes further.
It runs as a persistent BEAM daemon — not a CLI you invoke, but a long-lived process that keeps your graph in memory across sessions. It watches files for changes automatically (inotify / FSEvents / kqueue) and re-indexes only the changed files, not the whole workspace. When you pull new commits it detects the new Git HEAD and re-indexes only the diff.
On top of that it adds what no competitor offers: safe write capability. Before any proposed edit touches disk, Synapse simulates it in memory, validates it against the compiler and linter, maps the blast radius, and only commits atomically on passing every gate. If anything fails it rolls back. Your files are never left broken.
In plain terms
Think of the difference between a new employee on their first day versus a senior engineer who has worked in the codebase for years.
The new employee opens files, searches for things, asks questions, gets confused by unfamiliar names. Every task starts with exploration.
The senior engineer already knows where everything is. They go straight to the right file, understand the downstream effects of a change before touching it, and know which tests to run. They don't explore — they act.
Synapse turns your AI agent into the senior engineer. The knowledge graph is built once, updated automatically as your code changes, and queried instantly on every agent request — all without any code leaving your machine.
Why should I use it?
Without Synapse | With Synapse |
Agent greps files, reads imports, opens 10 files to find one function | One tool call returns the exact chunk, its callers, and its tests |
Every session starts from zero | Graph persists and improves across sessions |
Agent writes a file, lint fails, file is broken |
|
You paste a stack trace and hope |
|
Code review is manual |
|
Code sent to a cloud service to build an index | Everything runs locally — zero data egress |
You don't change how your agent works. You don't change your workflow. You install Synapse, register your repo, and your agent gets smarter immediately.
What your agent gets
Tool group | What it does |
| Natural-language entry point — routes to the right tool automatically |
| Pre-built structural slices: callers, callees, contracts, summaries |
| Semantic (BM25F + embeddings), symbol, and regex — structured chunk IDs, not file dumps |
| Transitive caller / callee traversal, cycle detection, context |
| Simulate → validate → write atomically → rollback on lint failure |
| Diff analysis, blast-radius ranking, broken-contract detection |
| Stack trace → AST root cause → reproducing test suggestions |
| Coverage bands, test mapping, ranked gap targets |
| Dead-code deletion safety, public API surface, dependency graph, refactor opportunities |
| Persistent summaries and retrieval reinforcement across sessions |
| Multi-repo registry — register, archive, restore; Git worktree support |
Related MCP server: Reporecall
Benchmark — Autonomous Security Audit · 500k LOC · Same Frontier Model
Metric | Synapse vs. shell tools |
Tokens & Cost | −60% |
Speed | 2.2× faster |
Tool calls | −47% |
Accuracy | 100% — identical |
Data sent to cloud | 0 bytes |
Fewer tool calls + no network latency = dramatically faster agent loops. The agent spends tokens on the actual task, not on exploration.
Why not just use X?
We get asked this a lot. Here is the honest answer, with source-verified facts.
"Why not Graphify?"
Graphify is a Python CLI that extracts your codebase into a graph.json file. It is read-only, file-based, and stateless. Every query re-reads the JSON. There is no MCP server, no semantic search, no write safety, no multi-repo support, and no persistent memory. It is a good offline export tool. It is not a graph engine.
"Why not CodeGraph (colbymchenry)?"
CodeGraph is a serious read-only tool with one capability Synapse does not match: HTTP route-chain tracing — following a URL through routing layers into the handler and template for 17 frameworks (Django, Rails, Express, Spring, etc.). If that specific capability is your entire use case, CodeGraph is worth evaluating.
Everything else: CodeGraph has no semantic/vector search (FTS5 only), no write safety, no multi-repo support, no change review, no test mapping, no debug tracing, and no persistent memory. It exposes one MCP tool by default (codegraph_explore). It is per-project only.
"Why not code-graph-mcp (sdsrss)?"
code-graph-mcp is the most technically sophisticated read-only alternative. It has a BLAKE3 Merkle-tree incremental indexer, hybrid BM25 + vector search via Reciprocal Rank Fusion, and 20 tree-sitter parsed languages. It is a well-engineered single binary.
It is still read-only. No write safety, no change review, no multi-repo, no worktrees, no debug tracing. Its 20 languages versus Synapse's 50+ means no Elixir, Erlang, Haskell, OCaml, Scala, Solidity, COBOL, Zig, Gherkin, HCL, Protobuf, GraphQL, or SQL DDL. Its dependency auditing runs on a daily cron; Synapse's runs on every push and blocks the pipeline on failure.
The real difference is that Synapse is the only one in this category that can actively prevent AI agents from breaking production. A tool that cannot write is a tool that cannot protect you from a write.
50+ Languages. One graph.
AST-aware chunking and call-graph edge extraction — no plugins, no configuration, no cloud.
Elixir Python TypeScript JavaScript Go Rust OCaml Haskell F# Clojure Scala Java Kotlin Swift Objective-C C C++ C# Ruby PHP Dart Zig Erlang Julia Groovy Solidity GraphQL HCL / Terraform Protobuf SQL DDL Gherkin Shell PowerShell Lua ...and more
Local First. Always.
🔒 Your code never leaves your machine. No cloud indexing, no API calls with your source, no telemetry, no vendor lock-in.
The full AST graph — every function, every edge, every embedding — is built and stored locally in a persistent on-device store. Agents query it directly over MCP. Nothing goes out.
This matters for:
Enterprise & regulated environments — source code stays inside your perimeter
Open source contributors — your unreleased work stays unreleased
Anyone who values speed and accuracy — local in-memory graph queries at sub-millisecond latency. No network round-trip, ever. No remote index that's out of date.
Engineering
Synapse is built to a production standard.
Security audit on every push —
mix deps.auditruns in CI withallow_failure: false. A dependency vulnerability blocks the pipeline immediately, not within 24 hours.Multi-platform smoke tests — every release candidate is built for Linux x86_64/aarch64, Darwin x86_64/aarch64, and Windows x86_64, then exercised via real-process SSE smoke tests before it reaches R2.
BDD end-to-end — full Cucumber suite runs through the actual packaged binary boundary (Burrito + Rust launcher), not a mock.
Signed release manifest — the launcher verifies binary integrity against a cryptographically signed manifest before executing. A tampered binary does not start.
Launcher version gate — promotion is blocked if the launcher version hasn't been incremented correctly. A mis-versioned release cannot ship.
Zero-latency file watching — the indexer drains all pending file events from its mailbox in a single pass (no sleep, no fixed debounce) and detects new Git HEAD commits, re-indexing only the changed diff.
Features at a Glance
Feature | Description |
🔒 100% Local & Private | Graph built and stored on your machine. Zero cloud dependencies, zero data egress, zero network latency on queries |
⚡ Sub-millisecond Graph Queries | In-memory ETS store — reads are direct table lookups with no I/O |
🚀 SmartCrusher Compression | Responses auto-minified 30–60%: short keys, stripped nulls, relativised paths. Outline mode strips bodies — scan 20+ files at a fraction of the token cost |
Three Search Modes | Semantic (BM25F + random-projection embeddings, in-process, zero external ML runtime), symbol lookup, and PCRE regex |
Transitive Caller Graph | Every direct and transitive caller of any function. Configurable depth, confidence scores, edge labels, production vs. test caller splitting |
Safe Atomic Writes | Simulate edits in memory, validate against the compiler and linter, write atomically, auto-rollback on failure. Files are never left broken |
Instant Crash Resolution | Stack trace → root-cause analysis mapped to your AST → reproducing test suggestions |
Change Review & Impact | Feed a diff or commit range. Get ranked blast radius, broken contracts, tests to run, and blind spots — before you push |
Persistent Agent Memory | Summaries written in one session are available in the next. Retrieval reinforcement improves result ranking from real usage |
Test Intelligence | Coverage bands, test mapping, and ranked test targets — derived from the graph without executing your test suite |
Codebase X-Ray | Language detection, public API surface, dead-code deletion safety, inter-module dependency graph, contract scanning, refactor opportunities |
Multi-repo & Git Worktrees | Register multiple repos. Run parallel sub-agents in Git worktrees — each gets delta indexing against the parent index, no full re-index per worktree |
Pricing
Free — The Golden Graph · $0 forever
Feature | Details |
AST Indexing | 10,000+ files across 50+ languages |
Search | Semantic, symbol & regex — structured results, not file dumps |
Caller Graph | Transitive caller & callee traversal with confidence scores |
Codebase Insights | API surface, deletion safety, dependency graph & refactor candidates |
Compression | SmartCrusher trims payloads 30–60% before they hit your LLM |
Privacy | 100% local — zero cloud dependencies, zero data egress |
Pro — The Shadow Graph · $19 / month
⚡ Typical token savings exceed the subscription cost.
Feature | Details |
Safe Writes | Simulate, validate & auto-rollback on lint failure |
Change Review | Blast radius, broken contracts & ranked risk |
Crash Resolution | Stack trace → root cause → reproducing tests |
Test Intelligence | Coverage bands & precise gap targeting |
Persistent Memory | Summaries survive across sessions |
Knowledge Cache | Queries improve result ranking over time |
Synapse Learns From Every Session
Most AI tools have no memory. Every session starts from zero — the agent reads the same files, discovers the same functions, and asks the same questions all over again. That's expensive and slow.
Synapse is different. It maintains a persistent, on-device knowledge graph that accumulates across every session. But beyond just storing the graph, it has a built-in learning and reinforcement layer that gets smarter the more you use it.
How the learning works — in plain English
Think of it like a highly organised colleague who takes notes.
1. Summaries that stick around
When an agent (or you) explains what a function does — "This handles Stripe webhook validation and checks for duplicate events" — Synapse writes that to the graph permanently. Next session, any agent that touches that function gets your explanation attached automatically. You wrote it once. Every agent benefits forever.
2. Queries that teach themselves Every time a search returns a useful result and the agent uses it, Synapse silently records the association: "when someone asks X, chunk Y was the right answer." Over time, the most useful results for common queries bubble up to the top automatically — without anyone manually tuning anything. This is retrieval reinforcement: the graph improves its own ranking from real usage.
3. Explicit promotion If a result is particularly important, you can tell Synapse directly: "for queries about payment processing, always surface this chunk first." That instruction is stored and applied on every subsequent query.
Installation
See synapse-mcp.dev/download for the full guide and GUI installer.
# Linux / macOS
curl -fsSL https://downloads.synapse-mcp.dev/install.sh | sh
# Windows PowerShell
irm https://downloads.synapse-mcp.dev/install.ps1 | iexClaude plugin
The claude-plugin/ folder is a plugin for Claude Code and Cowork. It connects Claude to the Synapse server running on your machine and adds skills for status, indexing, onboarding, change review, impact analysis and stack-trace resolution. Its README says what it does and what data it touches.
Contributing — Help Agents Use Synapse Better
This is the highest-leverage contribution you can make.
LLMs are trained on billions of lines of code where developers reach for grep, find, cat, and ls to explore a codebase. That muscle memory is baked into the model weights. When an agent is dropped into a new project, its first instinct is to grep — even when a smarter, cheaper tool is available.
Synapse ships a set of agent skill files (.agents/skills/synapse-mcp/SKILL.md) that agents load at session start. These files override the grep instinct by giving agents explicit routing rules, anti-patterns, and example tool calls. They are, in effect, runtime training for the meta-layer — teaching agents how to use the tools they have, not just what the tools do.
The problem: We can only write what we observe. You may have seen failure modes, routing gaps, or phrasing that your specific agent ignores. We haven't. The skill files improve dramatically with real-world usage reports.
What we'd love your help with
Area | What to contribute |
Anti-patterns | Agent behaviours you've seen that Synapse should suppress (e.g. "my agent still greps even after loading the skill") |
Routing rules | Cases where an agent picked the wrong Synapse tool — what was the query, what should it have done? |
Phrasing that works | If a specific instruction wording reliably stops your agent from falling back to grep, share it |
Agent-specific quirks | Claude, GPT, Gemini, and Copilot all have different tendencies. Agent-specific sections in the skill file help enormously |
New tool examples | Concrete JSON examples for actions that aren't yet covered in the skill |
Missing workflows | Scenarios (debugging, onboarding, large refactors) where the skill gives no guidance |
How to contribute
Open an issue — describe the failure mode or gap you observed. Include the agent, the query, and what it did vs. what it should have done.
Open a PR — edit
.agents/skills/synapse-mcp/SKILL.mddirectly. Skill file PRs are reviewed and merged fast — they don't require tests.Share a benchmark — if you've run Synapse vs. shell tools on your own codebase and have numbers, we want to publish them.
The skill files live in .agents/skills/. They are plain Markdown — no Elixir knowledge required. If you can describe what went wrong, you can write the fix.
The Claude plugin carries a copy of the skill at claude-plugin/skills/synapse-mcp/SKILL.md, because a plugin can only load files inside its own folder. It is the same file plus one line, user-invocable: false, which keeps it out of Claude's slash-command menu. When you change the skill, change both.
What's Next — Myelix Agents · Coming Q3 2026
Synapse gives your existing AI agents a precision map of your codebase. Myelix Agents is the next step: AI coding agents built from the ground up to think before they code.
Where current agents react — reading a file, writing a change, hoping for the best — Myelix Agents plan. They maintain an explicit task model, reason about risk before touching code, incorporate learnings from previous sessions (via Synapse's knowledge graph), and course-correct when something goes wrong. Accuracy over speed. Thought over grep.
Synapse Pro subscribers will get early access. Join the waitlist →
Support
Need help? Open an issue and we'll get back to you. Bug reports, feature requests, and integration questions are all welcome.
Links
🌐 synapse-mcp.dev — Website & docs
Available Tools
14 toolsask_synapseAsk SynapseA
Default Synapse entry point for codebase questions, deletion-safety checks, edits, reviews, debugging, test discovery, repository administration, and capability discovery. It routes natural-language objectives through the existing granular tools while preserving their entitlement, readiness, validation, and mutation-safety checks. Pass top-level repo_id and path to scope repository work, and pass exact identifiers in inputs when prose might be ambiguous.
REPLACES: manual Synapse tool and action selection. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Use first for ordinary Synapse requests.
Usage (long): Describe the objective in query and provide concrete identifiers or mutation payloads separately. Prefer top-level repo_id and path for scope; context.repo_path and context.target_file are accepted compatibility aliases. For deletion-safety wording such as 'can I delete X?' or 'is X still used?', provide inputs.chunk_id when available, otherwise repo_id plus an exact arity-qualified inputs.symbol so ask_synapse can route to synapse_codebase_insights/dead_code; descriptive prose without one exact target must ask for clarification instead of guessing. Inspect completion_state, agent_instruction, and follow only the returned safe next_tool_calls guidance when the response is incomplete.
Inputs: query (required), path, depth, limit, +12 more.
synapse_capability_manifestCapability ManifestA
Return a structured manifest describing SynapseMCP's live tool surface, including schemas, mutation characteristics, static safety classification, and tool relationships.
REPLACES: reading MCP tool schemas manually, trial-and-error tool discovery. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Returns a structured manifest of live Synapse MCP tool capabilities.
Usage (long): Use this to discover tool schemas, mutation characteristics, and capability relationships. Includes quick_start onboarding steps and readiness_routing to understand which tools work at each indexing phase.
Inputs: max_tokens, include_tools, include_groups, schema_version, +3 more.
synapse_change_reviewChange ReviewA
Analyses and reviews proposed changes (via diff, commit range, chunk list, or file list). High-level actions include:
'analyse_diff': parses and orientates a change set quickly (modified symbols, must-read files, tests to run, contract signals).
'review_diff': performs a detailed safety and risk review of proposed edits, highlighting blind spots and state/event contract changes.
'impact': evaluates blast radius, downstream callers, and change risk.
REPLACES: git diff, manual diff review, grep_search for impact analysis. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Analyse diffs, review change risks, and evaluate downstream impact.
Usage (long): Inspect commit/branch diffs, review code changes for structural risks, or calculate blast radius impact before refactoring. Use after making changes to verify safety, or before merging to assess risk.
Inputs: action (required), max_tokens, compress_payload.
synapse_codebase_insightsCodebase InsightsA
Analyses codebase structures, API boundaries, contracts, dependencies, and deletion safety. High-level actions include:
'detect': returns percentage language and framework breakdown, file count, and recommended linter audits.
'public_api': lists public modules and functions, helper heuristics, and external callers count.
'dead_code': performs a read-only function-level deletion-safety check for one exact symbol or chunk_id. Prefer chunk_id from a previous Synapse result; otherwise pass repo_id plus an arity-qualified symbol such as Parser.parse/2. It reports whether the symbol appears dead, splits production and test callers, explains confidence and deletion risk, marks clause-level analysis as unsupported, and tells the agent what to do next without deleting source.
'contracts': scans interface boundaries (JSON/HTTP/CLI) and outward-facing schemas.
'dependencies': builds an inter-module dependency graph.
'overview': returns a consolidated repository overview.
'refactor_opportunities': surfaces code quality improvement candidates.
REPLACES: grep_search for API surface discovery, wc for codebase sizing, manual language detection, find for framework detection. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Detect languages, identify public APIs, check deletion safety, build dependency graphs, and surface refactoring opportunities.
Usage (long): Analyze language mix, list public API surfaces, run function-level deletion-safety checks by chunk_id or repo_id + symbol, scan interface boundaries (JSON/HTTP/CLI), build dependency graphs, surface refactoring opportunities, or retrieve a consolidated repository overview. Use 'dead_code' as the backend for ask_synapse questions like 'can I delete X?', 'is X still used?', or 'should I keep X?'. Provide chunk_id, or repo_id plus one exact symbol; bare function names are resolved only when one arity variant is indexed. If the user only gives descriptive prose, ask for the concrete symbol rather than guessing. Read scope, clause_level_analysis, safe_to_delete, deletion_risk, confidence, caveats, and supporting_evidence.production_callers/test_callers before advising. Use 'detect' to understand the language mix before choosing search modes.
Inputs: action (required), max_tokens, compress_payload.
synapse_debug_traceDebug TraceA
Traces code paths or resolves error stack traces to understand execution flow and debug issues. High-level actions include:
'trace_behaviour': maps the execution flow of a function (branching, state access, side effects, tests).
'resolve_stack': parses a runtime crash stack trace and matches frames to repository chunks, root cause, and tests.
REPLACES: manual stack trace reading, grep_search for error origins, sequential file reads to trace execution. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Trace ranked execution paths and map crash stack traces to code chunks. Maps stack traces to chunks.
Usage (long): Trace execution flow (branching, state access, side effects) or resolve runtime stack traces to locate crash-site causes and tests. Use 'trace_behaviour' to understand how a function works without running it. Use 'resolve_stack' to map crash stack traces to indexed code chunks with root cause analysis.
Inputs: action (required), max_tokens, compress_payload.
synapse_explore_graphExplore GraphA
Explores structural relationships within the codebase graph. High-level actions include:
'callers': finds all chunks that call a given chunk, with transitive depth support (1–3).
'callees': finds all functions, modules, or types that a chunk calls or depends on, with transitive depth support (1–3).
'context': retrieves rich structural context (callers, callees, related chunks) around a specific chunk.
'cycles': detects circular dependencies reachable from a given chunk. All four actions accept chunk_id OR (repo_id + symbol) OR (repo_id + file_path + optional line) — no separate lookup needed.
REPLACES: grep_search for caller discovery, manual import tracing, find_references, caller guessing. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Explore caller-callee dependency relationships and semantic context in the code graph. Pass symbol + repo_id directly — no separate lookup needed.
Usage (long): Trace incoming callers, downstream callees, detect cycles, or retrieve immediate neighbours/references for a code chunk. ALL four actions (callers, callees, context, cycles) accept:
chunk_id (direct) — fastest, use when already known.
repo_id + symbol — resolves the symbol and runs in one call.
repo_id + file_path (+ optional line) — resolves by file position. Token-saving: both callers and callees support depth 1–3. Use depth: 2+ to get multi-hop results in a SINGLE call instead of chaining multiple depth-1 calls. One-call examples: callers: {action: 'callers', repo_id: 'MY_REPO', symbol: 'MyModule.my_fn', depth: 2} callees: {action: 'callees', repo_id: 'MY_REPO', symbol: 'MyModule.my_fn', depth: 2} cycles: {action: 'cycles', repo_id: 'MY_REPO', symbol: 'MyModule.my_fn'} Replaces manual import/caller guessing. Returns transitive callers/callees with depth control. Compression is on by default — graph results can be large.
Inputs: action (required), max_tokens, compress_payload.
synapse_get_contextGet ContextA
Retrieves rich context about the codebase for understanding, editing, explaining, or onboarding. Pass the exact repo_id to keep results focused on the intended repository, especially when multiple repositories are registered; if repo_id is unknown, call synapse_manage_repos with action 'list'. High-level actions include:
'find': runs semantic search, exact symbol lookup, fuzzy matching, and call-graph traversal to locate relevant chunks. Without repo_id, it returns at most 5 high-confidence matches.
'edit': gathers callers, callees, related tests, risk assessment, and behaviour boundaries before editing a chunk.
'explain': produces a layered explanation of a chunk.
'onboard': builds a subsystem reading order and learning path.
REPLACES: multi-file grep_search chains, sequential view_file reads, manual code comprehension. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Retrieve codebase context, explain chunks, build onboarding reading orders, or prepare pre-edit safety packs. Pass the exact repo_id to keep results focused on the intended repository. For the freshest just-edited path, use action 'edit' (analogous to current symbol lookup and graph context workflows).
Usage (long): Prepare context before edit, retrieve layered explanations, locate files/chunks for a feature, or construct reading paths. Pass the exact repo_id to keep results focused on the intended repository. If repo_id is unknown, call synapse_manage_repos with action 'list' and copy it verbatim. Without repo_id, action 'find' returns at most 5 high-confidence matches and reports meta.unscoped_retrieval. Action 'edit' is the essential pre-edit step — always call it before modifying code. It gathers callers, callees, tests, and risk in one call.
Inputs: action (required), kind, line, path, +15 more.
synapse_indexer_controlIndexer ControlA
Controls and inspects the indexing pipeline and server health. High-level actions include:
'health': cheap health probe for transport and runtime readiness. Call this first before anything else — one call tells you the server is alive and which tools are loaded.
'status': returns per-repository indexing phase progress, ETS chunk counts, embedding readiness, unresolved edge counts, and top summary candidates. Pass repo_id for a fast direct lookup of one repository; omit it to see all repositories at once. Status responses are cached for 60 seconds when all indexers are idle (5/10 s during active indexing) — this prevents 50-repo installations from timing out.
'trigger': triggers a re-index of a repository or a specific file/directory.
REPLACES: manual health probing, process monitoring, ad-hoc tool listing. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Confirms the server is alive and reports indexing progress per repository. Monitor indexing progress, health state, and trigger indexing manually. Always pass repo_id to status for a fast scoped lookup; omit it only when you need all repos.
Usage (long): Call 'health' first to confirm the server is running, then 'status' with a repo_id to check whether that repository is ready for search. The status response includes:
repos[]: one entry per matching repository, each with phase progress, chunk_count, indexed_files, embeddings_partial, repo_unresolved_edges (edges whose target chunk has not yet been indexed), and needs_summary (top chunks that have been queried but lack a cached summary, ranked by hit_count — use these as summarisation targets).
unresolved_edges: global total across all repos (useful for cross-repo health checks).
repo_id scoping: passing repo_id performs a direct SQLite lookup rather than scanning all registered repositories, making it safe to call at 50+ repo scale.
readiness_guide: shows which tool actions work at the current indexing phase.
include_profile: true adds language/kind chunk distribution breakdown (slower).
Inputs: action (required), mode, path, force, +5 more.
synapse_inspect_filesInspect FilesA
Inspects files in the workspace. High-level actions include:
'read_files': reads one or more files from disk with line numbers, byte sizes, and metadata (supports directories too).
'read_chunk': reads the full raw source of a specific code chunk from the in-memory store (no disk access).
'count_lines': counts total lines across workspace files.
REPLACES: view_file, read_file, cat, wc, list_dir for file inspection. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Read files, chunks, or count lines in the workspace.
Usage (long): Inspect multiple source files with line numbers, retrieve raw chunk code, or perform line counts across files. Supports format: 'outline' to compress function bodies during retrieval, saving context tokens — use this when scanning many files. Compression is on by default — pass compress_payload: false to opt out for debugging.
Inputs: action (required), path, files, format, +7 more.
synapse_knowledge_cacheKnowledge CacheA
Manages persistence, feedback loops, and learning metadata within the codebase graph. High-level actions include:
'learn': records explicit query-to-chunk relevance; repeated evidence promotes cache hits.
'save_summary': persists single or batch plain-English annotations on code chunks.
'suggest': lists high-value chunks needing summary based on access history and traffic weight.
'query': searches cached summaries, identifiers, and exact learned associations to recall established patterns.
REPLACES: repeated searches for the same patterns, manual note-taking, re-discovering code paths. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Record search feedback signals, save chunk summaries, suggest docs tasks, and query cached patterns.
Usage (long): Save feedback signals to cache search queries, write natural language summaries for chunks, suggest highest priority needs_summary targets, and query established patterns.
Call 'learn' after useful search results to record explicit query-to-chunk relevance; a single learn signal is queryable immediately but remains provisional until repeated evidence promotes it. Call 'save_summary' to permanently annotate chunks with natural language descriptions. Call 'query' with natural language, filenames, symbols, or chunk IDs to retrieve matching summarized chunks and exact learned associations.
Inputs: action (required), max_tokens, compress_payload.
synapse_manage_reposManage ReposA
Manages repository registrations. High-level actions include:
'list': lists all configured repositories and their index state. Each row includes suggested_actions with ready-to-fire tool calls.
'register': registers a new workspace for watching and indexing. Git worktrees are transparently auto-detected.
'archive': marks a registered workspace as archived, stops its indexer, and keeps existing graph data searchable.
'restore': marks an archived workspace active again and restarts indexing.
'keep': dismisses a dirty-merged worktree advisory for the current session (signals that uncommitted changes are intentional).
'unregister': permanently removes a repository from the registry and graph store.
'update_excludes': updates the set of excluded paths for a repository. Clean Git worktrees whose branch work is already merged are auto-archived conservatively before indexing work is scheduled.
REPLACES: ls, find for workspace discovery, manual git worktree management. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Manage repository registrations, lifecycle, exclusions, and workspace lists.
Usage (long): Use to register new repositories, list registered repositories, manage active/archived lifecycle state, update exclude paths, or unregister repositories.
KEY WORKFLOW — always read suggested_actions first: Each 'list' row (both scoped and unscoped) contains a suggested_actions field with structured objects {label, tool, args}. These are ready-to-fire tool calls — pick the appropriate one and call it directly without reformatting.
DIRTY-MERGED WORKTREE ADVISORY: When a worktree branch is merged but has uncommitted changes, the row will contain dirty_merged_worktree: true and 3 suggested_actions:
archive — keep graph searchable, stop indexing
unregister — delete graph data permanently
keep — changes are intentional, dismiss advisory for this session Call one of these immediately with just repo_id + action.
LIFECYCLE RULES: Use 'archive' for stale or merged worktrees; use 'restore' to reactivate indexing; use 'unregister' only for destructive removal; use 'keep' when changes are intentional.
When registering, you MUST provide an absolute path for root (e.g. /Users/name/repo). Do not use . or relative paths. Always call 'list' first if unsure of the repo_id.
Inputs: action (required), root, merge, exclude, +4 more.
synapse_modify_filesModify FilesA
Modifies files in the workspace. For safe agent workflows, first call 'write_safely' with dry_run: true, pre_check: true, and lint: true; review the preview, then call again with dry_run: false only when applying. High-level actions include:
'write_safely': writes content with atomic lint validation, dry-run semantic diff simulation, pre_check blast radius mapping, and automatic rollback on failure.
'find_and_replace': runs global regex find-and-replace across matching indexed files with instant re-indexing.
'delete_chunk': removes a chunk from the index.
REPLACES: write_to_file, replace_file_content, multi_replace_file_content, manual lint + commit cycles. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Preview and apply atomic safe file writes, global find-and-replace, or delete chunks.
Usage (long): Write files safely with automatic lint checks and revert on failure, run workspace-wide find and replace, or purge chunk entries. Always call synapse_get_context (edit) before this tool to understand callers, callees, and tests. For write_safely, first call with dry_run: true, pre_check: true, and lint: true so the agent sees semantic safety, compilation errors, contract warnings, and blast radius without touching disk. Apply with dry_run: false only after reviewing that preview. Validates with Trunk linter — rolls back atomically on lint failure.
Inputs: action (required), kind, lint, path, +13 more.
synapse_search_codebaseSearch CodebaseA
Searches the repository codebase using different modes. Pass the exact repo_id with every action to keep results focused on the intended repository; if repo_id is unknown, call synapse_manage_repos with action 'list'. High-level actions include:
'semantic': cosine similarity search over in-memory embeddings; best for conceptual or descriptive queries.
'symbol': fast exact/fuzzy symbol index lookup; best when looking for a named function, module, or class.
'regex': line-matching grep over indexed source; best for exact string or pattern matching. Without repo_id, every action returns at most 5 high-confidence matches across indexed repositories and reports the policy in meta.unscoped_retrieval.
REPLACES: grep_search, find, rg, list_dir for code search. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Search codebase using semantic embeddings, symbol index, or regex grep. Pass the exact repo_id to keep results focused on the intended repository. For the freshest just-edited file, use actions 'symbol' or 'regex' (analogous to current symbol, regex, and graph context workflows).
Usage (long): Run a natural language semantic search, exact/fuzzy symbol lookup, or line-matching regex grep over indexed files. Pass the exact repo_id with every action to keep results focused on the intended repository. If repo_id is unknown, call synapse_manage_repos with action 'list' and copy it verbatim. Without repo_id, semantic requires score >= 0.75, fuzzy symbols require score >= 0.90, regex keeps exact textual matches, and every action is capped at 5 results. The response reports this in meta.unscoped_retrieval. Compression is on by default — pass compress_payload: false to opt out for debugging. Actions 'symbol' and 'regex' work immediately after quick_pass — they do not require embeddings. Action 'semantic' requires embeddings — avoid when repo_status.embeddings_partial is true.
Inputs: action (required), kind, path, fuzzy, +12 more.
synapse_test_qualityTest QualityA
Handles code quality, testing context, and linting control. High-level actions include:
'coverage': reports production files with no, weak, or strong test coverage using the indexed graph.
'find_tests': discovers behavioral tests, features, step definitions, or fixtures covering a symbol/query. Without repo_id, it returns at most 5 direct-confidence matches and stops once that bound is filled.
'setup_trunk': automatically configures Trunk linting and enables recommended linters for a repository.
'recommend_test_targets': recommends test targets (both unit/integration and BDD features) with behaviour summaries and coverage analysis.
REPLACES: grep_search for test files, find _test. patterns, manual test-to-code mapping. Use this tool instead of these alternatives for better results with 30-60% fewer tokens via automatic compression.
Usage (short): Report test coverage gaps, find relevant test files, recommend test targets, and configure Trunk linting.
Usage (long): Report static test coverage bands, locate feature files or unit tests for a symbol, recommend candidate files for unit and BDD test coverage (via recommend_test_targets) with behaviour summaries (excluding nested repositories/submodules by default, or opting in via targeted path filters), and run Trunk setup/audit check enable. Unscoped find_tests returns only direct-confidence matches, capped at 5.
Inputs: action (required), max_tokens, compress_payload.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each Synapse tool has a clearly scoped domain (graph exploration, indexing, file work, retrieval, etc.), and a shared prefix prevents collisions. Still, there is some overlap between synapse_get_context's 'find', synapse_search_codebase, and synapse_explore_graph, and ask_synapse intentionally overlaps everything as a routing layer.
All tool names use the uniform 'synapse_' prefix and snake_case, making them easy to group and remember. The naming mixes verb-led entries like synapse_inspect_files with noun-headed ones like synapse_capability_manifest or synapse_test_quality, which keeps things readable but not perfectly uniform.
At 14 tools, the surface is substantial but still well-scoped. Each tool covers a distinct functional area rather than being a thin wrapper, so the count feels appropriate for the breadth of the code graph assistant.
The tool surface covers the full lifecycle: repository registration and indexing, health/status control, code search/context retrieval, graph exploration, diff review, debug tracing, safe file modification, test discovery, and knowledge caching. There are no obvious dead ends for the stated capabilities, and operators are well covered.
Maintenance
Related MCP Connectors
Deterministic memory & code intelligence MCP for 15 IDEs (100% LongMemEval in 12.9ms, 0 LLM tokens).
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnterprise-grade (40m+ lines) codebase intelligence in a zero-setup, private and local MCP: managed indexing, hybrid semantic search, polyglot code dependency graphs, and DB/API/infra knowledge. Benchmark: 61% less tokens, 84% fewer calls, 37x faster than standard AI grep.264,056 npm3,372AGPL 3.0
- AlicenseNot gradedqualityAmaintenanceZero-tool-call codebase intelligence for Claude Code and MCP clients. Automatically injects the right code context, functions, callers, and call chains, before the LLM starts thinking. Replaces 4-6 grep/read round-trips with a single 5ms hook injection, cutting token usage by 3-8x.88 npm37MIT
- AlicenseNot gradedqualityDmaintenanceTurn any codebase into an AI-readable neural map — with proof. Every claim linked to code anchors (line + SHA-256 hash), every context window optimized with greedy token budgeting, every session protected by drift detection. Tree-sitter indexing across 11 languages, cross-session learning, AI enrichment, and 28 MCP tools. Zero config — just connect and your AI agent remembers everything.5 npm14GPL 3.0

knowingofficial
AlicenseNot gradedqualityBmaintenanceContent-addressed code graph that produces ranked context for AI agents in one call. 22 MCP tools across indexing, blast radius, test scope, semantic diff, runtime traffic, and feedback-aware context packing. Incremental updates via Merkle DAG (no re-indexing). GCF wire format saves 84% tokens vs JSON24Apache 2.0