MCP Setup

Connect Cursor, Claude Code, Windsurf, or any MCP-compatible agent to Synapse.

Synapse exposes all retrieval tools via the Model Context Protocol (MCP) over stdio. Your IDE agent communicates with Synapse using standard JSON-RPC 2.0 messages.

Step 1: Initialize & Start

synap init .      # Build the AST graph (one-time)
synap start .     # Start the background daemon

Step 2: Get Your Config

synap mcp config .

This prints the exact JSON snippet for your IDE. Copy it directly.

IDE Setup

Cursor

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "synapse": {
      "command": "synap",
      "args": ["mcp", "serve", "/absolute/path/to/your/repo"],
      "autoConnect": true
    }
  }
}

Claude Code

claude mcp add synapse synap -- mcp serve /absolute/path/to/your/repo

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "synapse": {
      "command": "synap",
      "args": ["mcp", "serve", "/absolute/path/to/your/repo"]
    }
  }
}

Roo Code / Cline

In the MCP Servers panel, add:

Command: synap
Args: mcp serve /absolute/path/to/your/repo

Response Envelope

Every MCP tool returns a standardized JSON envelope:

{
  "ok": true,
  "data": { ... },
  "warnings": [],
  "trace_id": "8b51d087-93e1-4560-9304-c36b412ee17f",
  "dirty_tree": false
}

| Field | Description | |---|---| | ok | true on success, false on error | | data | Tool-specific payload | | warnings | Non-fatal issues (e.g. stale index) | | trace_id | UUID for debugging | | dirty_tree | Whether the working tree has uncommitted changes |

Error response:

{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "No checkpoint found for current branch.",
    "suggestion": "Run synap checkpoint create . first."
  }
}

Error codes: INTERNAL_ERROR, INDEX_STALE, NOT_FOUND

Tool Reference

`search`

Hybrid AST + FTS5 + vector retrieval. The primary tool agents should call for code context.

Input:

{ "query": "AuthService.verify_jwt", "max_tokens": 4000 }

Response data:

{
  "context": [
    {
      "name": "verify_jwt",
      "kind": "function_definition",
      "file": "src/auth/service.py",
      "start_line": 45,
      "end_line": 56,
      "source_text": "def verify_jwt(token: str) -> Claims:\n    ...",
      "reason": "ast:exact_symbol"
    }
  ],
  "trace": {
    "latency_ms": 9.2,
    "tokens_used": 420,
    "nodes_explored": 8
  }
}

`get_status`

Current indexing state and daemon health.

Response data:

{
  "branch": "main",
  "git_commit": "d980cf7f...",
  "symbols": 8421,
  "files": 1120,
  "mode": "active",
  "is_dirty": false
}

`create_checkpoint`

Save current agent progress as an L3 checkpoint.

Input:

{
  "doing": "Refactoring JWT auth service",
  "changed_files": ["src/auth/service.py"],
  "next_step": "Run pytest tests/test_auth.py",
  "blockers": "None"
}

`restore_checkpoint`

Fetch the latest checkpoint on the current branch. Call at session start to resume work.

`log_decision`

Record an architectural decision into L3 permanent memory.

Input:

{
  "decision": "Use SQLite WAL mode for concurrent daemon access",
  "rationale": "Allows readers and the indexer to work simultaneously without locking.",
  "tags": ["architecture", "storage"]
}

`get_approved_memory`

Retrieve all active L3 lessons the agent must adhere to. Always call this at session start.

`get_pending_memory`

Retrieve lessons awaiting human review.

`submit_lesson_analysis`

Submit a root-cause explanation for a failed/reverted commit.

Input:

{
  "lesson_id": "1e2c345d-...",
  "why_failed": "Used un-aliased columns in the migration script, breaking the column name resolution."
}

`verify_system`

Run database integrity checks and return diagnostics.

`signal_low_context`

Notify Synapse when the agent's context window is running low. Synapse will recommend checkpointing.

Input:

{ "token_count": 45000, "capacity": 60000 }

System Prompt Template

Paste this into your IDE's system prompt or .cursorrules:

You have access to a Synapse MCP server providing local codebase context.

At the start of every session:
1. Call get_approved_memory — adhere strictly to all returned lessons
2. Call restore_checkpoint — resume from where you left off
3. Call get_status — verify the index is current

During work:
- Use search before writing any code that touches existing symbols
- Call log_decision when making architectural choices
- Call create_checkpoint every ~10 significant changes
- Call signal_low_context when your token usage exceeds 60%

Never modify files that appear in approved lessons' files_affected without explicit user approval.