Language Support
🐍Python
Supported
·Coming soon:
☕Java✦
🔷.NET✦
v1.0.0Python 3.11+

Documentation

Automatically analyze any codebase and generate production-ready MCP servers — bridging your existing code with AI tools like Claude Desktop, Windsurf, Cursor and more.

GitHub

Introduction

Synapse is the context infrastructure that governs how AI accesses enterprise systems and knowledge, so every user interaction is informed by the full context of the business.

🚀

Instant MCP Servers

Point Synapse at any codebase and get a production-ready MCP server with a single command — no manual configuration.

🤝

Works With Your AI Tools

Native compatibility with Claude, Cursor, Windsurf, and any MCP-compliant AI assistant.

🔑

Secure by Default

API keys are encrypted and scoped per project. Secrets stay local — never sent to the AI.

Development Status

✅ Phase 1 — Init & Config✅ Phase 2 — Analysis & Detection✅ Phase 3 — MCP Generation

Installation

Requirements: Python 3.11 or higher

Install Synapse CLI from PyPI (recommended) or directly from source.

RecommendedInstall from PyPI

bash
pip install synapse-cli

Install from source

bash
# Clone the repositorygit clone https://github.com/synaps3ai/synapse-clicd synapse-cli# Install in development modepip install -e .# Or install dependencies directlypip install -r requirements.txt

Verify installation

bash
synapse --version# synapse v1.0.0

Quick Start

From zero to a working MCP server in five steps — with an optional first step to set up a clean Python environment.

1

Install uv & Create a Virtual Environment

Optional

uv is a fast Python package manager. Using a virtual environment keeps your project's dependencies isolated and avoids conflicts with system packages.

bash
# Install uv (macOS / Linux)curl -LsSf https://astral.sh/uv/install.sh | sh# Install uv (Windows — PowerShell)powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"# Create a virtual environment in your project directoryuv venv# Activate itsource .venv/bin/activate   # macOS / Linux.venv\Scripts\activate      # Windows# Your Python executable path.venv/bin/python3

Once activated, all subsequent pip install and synapse commands will run inside the isolated environment.

2

Install Synapse CLI

Install via pip from PyPI.

bash
pip install synapse-cli
3

Set Up Global Authorization

Store your API key globally so every project on this machine automatically picks it up — no need to re-enter it per project.

bash
# Option A — store via CLI (recommended)synapse config --global --key <YOUR_API_KEY># Option B — environment variable (takes highest precedence)export SYNAPSE_API_KEY=<YOUR_API_KEY># Verify it was savedsynapse config

API Key Precedence Order

  1. 1stSYNAPSE_API_KEY environment variable— highest priority
  2. 2ndProject key — .synapse/config.json— project-scoped
  3. 3rdGlobal key — ~/.synapse/config.json— machine-wide fallback

API keys are encrypted at rest using Fernet symmetric encryption with a machine-derived key.

4

Initialize Synapse in Your Project

Run this inside your project directory. Synapse creates a .synapse/ configuration folder and securely stores your API key.

bash
cd /path/to/your/projectsynapse init

This creates .synapse/config.json in your project root. Use --force to reinitialize an existing project.

5

Analyze Your Codebase

Synapse parses your project with AST (Abstract Syntax Tree) analysis and semantic indexing, generating a schema and indexing your code for AI retrieval.

bash
synapse analyze# With verbose outputsynapse analyze --verbose# Save analysis to a custom directorysynapse analyze --output ./my-analysis

Produces .synapse/project_schema.txt and .synapse/statistics.json.

6

Build Your MCP Server

Describe what you want to expose. Synapse's AI-powered generation pipeline will build a production-ready MCP server.

bash
# Interactive mode: select endpointssynapse build# Or with a querysynapse build --query "expose the database query functions as MCP tools"# Specify a custom output filenamesynapse build --query "wrap the authentication endpoints" --output auth_mcp_server.py# Skip validation stepsynapse build --query "expose all REST API handlers" --no-validate

Output defaults to mcp_server.py in your project root.

Commands

Synapse provides five core commands. Run synapse --help or synapse <command> --help for details.

synapse initPhase 1

Initialize Synapse in the current directory. Creates a .synapse/ folder and securely stores your API key.

Options

--forceReinitialize even if the project is already initialized. Overwrites existing configuration.
bash
synapse init# Force reinitializesynapse init --force
synapse analyzePhase 2

Scan and analyze the project codebase. Performs AST parsing, semantic code indexing with Qdrant vector search, and endpoint detection. Generates a project schema and statistics file used by synapse build.

Options

--output <dir>Directory to write analysis output files. Defaults to .synapse/ in the project root.
--verbosePrint detailed analysis progress including file-by-file parsing and indexing stats.
bash
synapse analyze# Verbose mode with custom outputsynapse analyze --verbose --output ./analysis
synapse buildPhase 3

Generate a production-ready MCP server based on your natural language query. Connects to the Synapse gRPC backend where the AI generation pipeline runs, then streams the generated code back.

Options

--query <query>Natural language description of what to expose as MCP tools (e.g. 'expose the database query functions').
--output <file>Output filename for the generated MCP server. Defaults to mcp_server.py.
--no-validateSkip the generated code validation step.
--no-docsSkip auto-generating documentation for the MCP server.
--generateForce regeneration even if an mcp_server.py already exists.
bash
# Interactive mode — select endpoints and describe your needssynapse build# With inline querysynapse build --query "expose all database access functions"# Custom output file, skip validationsynapse build --query "wrap the auth module" --output auth_server.py --no-validate
synapse configPhase 1

View or update Synapse configuration. Displays the current API key (first 5 characters + asterisks), active model, and config file location. Supports both project-level and global (machine-wide) keys.

Options

--updateEnter interactive update mode to change configuration values.
--key <API_KEY>Directly set an API key without entering interactive mode.
--globalApply the key change to the global ~/.synapse/config.json instead of the project config.
bash
# View current configsynapse config# Set a project-level API keysynapse config --key sk-ant-xxxxxxxxxxxx# Set a global API key (all projects)synapse config --global --key sk-ant-xxxxxxxxxxxx# Interactive updatesynapse config --update
synapse statusPhase 1

Display the current project status: initialization state, configuration health, and analysis readiness. Useful as a quick sanity check before running synapse build.

bash
synapse status

Configuration

Configuration Files

🌍

Global Config

~/.synapse/config.json

Machine-wide settings. API key here is the fallback for all projects on this machine.

📁

Project Config

.synapse/config.json

Project-scoped settings. Overrides global config for this specific project.

API Key Precedence

1
SYNAPSE_API_KEYEnvironment Variable

Set this to override all config files. Ideal for CI/CD pipelines.

2
.synapse/config.jsonProject Key

Scoped to the current project. Set via synapse config --key.

3
~/.synapse/config.jsonGlobal Key

Fallback for all projects. Set via synapse config --global --key.

Generating Your API Key

API keys are created from the Synapse web console. Follow these steps:

1

Sign in to the Synapse Console

Go to synaps3.ai and sign in to your account.

2

Open "API Keys" from the sidebar

In the left sidebar of the console, click API Keys.

3

Click "Create API Key"

Give your key a descriptive name (e.g. "my-laptop") so you can identify it later.

4

Copy your key immediately

The full key is displayed only once. Copy it now — you won't be able to see it again.

5

Apply it globally with Synapse CLI

Run the command below to store it machine-wide:

bash
synapse config --global --key <YOUR_API_KEY>

Security

Your key is encrypted at rest using Fernet symmetric encryption — never shared or logged. Config files are automatically excluded from version control via .gitignore. Keys are never displayed in full — only the first 5 characters are shown followed by asterisks.

Secrets & Variables

When building no-code MCP servers through the Synapse Console, you often need to include API keys, auth tokens, or other credentials in your endpoint headers or payload. Synapse supports two special syntaxes so that no credentials are ever stored in the Synapse database — everything sensitive stays on your machine.

${VAR_NAME}Env Secret

Resolved silently from your local environment at runtime. Never exposed to the AI model. Use this for API keys, auth tokens, tenant IDs, and anything you don't want leaving your machine.

✓ Works in header values
✓ Works in payload field values
✓ Works in URLs
{param}Dynamic URL Param

Becomes a required input parameter in the MCP tool schema. The AI model provides this value on every call. Use this for resource IDs, slugs, or any path segment that changes per request.

✓ Works in URLs only
✓ URL-encoded automatically
✓ Shown as AI tool parameter

Env Secrets — ${VAR_NAME}

When adding an endpoint, use ${VAR_NAME} anywhere you would normally paste a secret. When generating the MCP config, Synapse automatically detects these placeholders and adds them as empty entries in the env block — you fill them in locally.

Header Example
Key:   AuthorizationValue: Bearer ${AUTH_TOKEN}# AUTH_TOKEN will appear in your generated config as:# "AUTH_TOKEN": ""# — fill it in with your actual token locally
Payload Example
{  "message": "user provides this",  "api_key": "${MY_API_KEY}"}# api_key is resolved from env — the AI never sees it# message becomes a normal tool parameter

Dynamic URL Params — {param}

Use single-brace syntax in the URL to create AI-configurable path parameters. Each {param} becomes a required string input in the MCP tool schema. The value is URL-encoded before substitution.

URL Example
https://api.example.com/users/{user_id}/posts/{post_id}# The AI model is asked to provide:#   user_id (string) — URL path parameter#   post_id (string) — URL path parameter

Full Example

A single endpoint combining all three — static env secret in the domain, auth token in headers, and AI-provided path param in the URL:

Endpoint Config
URL:     https://${API_DOMAIN}/v1/documents/{document_id}Method:  GETHeaders: Authorization: Bearer ${AUTH_TOKEN}
Generated claude_desktop_config.json
{  "mcpServers": {    "my-server": {      "command": "npx",      "args": ["-y", "@2ndbrainlabs-ai/synapse-mcp"],      "env": {        "SYNAPSE_API_KEY": "YOUR_SYNAPSE_API_KEY",        "SYNAPSE_SERVER_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",        "SYNAPSE_API_URL": "https://api.synaps3.ai",        "API_DOMAIN": "",        "AUTH_TOKEN": ""      }    }  }}

Zero credentials stored

document_id is an AI parameter — not in this config at all. API_DOMAIN and AUTH_TOKEN are empty placeholders you fill in locally. Neither the Synapse database nor the npm package ever sees your actual secrets.

Connect to AI Tools

After running synapse build, you'll have a mcp_server.py file in your project root. Register it in your AI tool's MCP config so the tool can talk to your codebase.

Replace /absolute/path/to/mcp_server.py with the real path on your machine and my-project with any name you like.

Claude Desktop

Claude Desktop

macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json
json
{  "mcpServers": {    "my-project": {      "command": "python",  // your python executable path: .venv/bin/python3      "args": ["/absolute/path/to/mcp_server.py"]    }  }}

Fully quit and reopen Claude Desktop after saving the config.

Cursor

Cursor

Global~/.cursor/mcp.json
Project.cursor/mcp.json
json
{  "mcpServers": {    "my-project": {      "command": "python",  // your python executable path: .venv/bin/python3      "args": ["/absolute/path/to/mcp_server.py"]    }  }}

Open Cursor Settings → MCP, or use the project-level file to scope the server to one workspace.

Windsurf

Windsurf

macOS / Linux~/.codeium/windsurf/mcp_config.json
json
{  "mcpServers": {    "my-project": {      "command": "python",  // your python executable path: .venv/bin/python3      "args": ["/absolute/path/to/mcp_server.py"]    }  }}

Restart Windsurf after saving. The server will appear in the MCP panel in Cascade.

Synapse v1.0.0 — MIT License