Language Support

🐍Python

Supported

·Coming soon:

☕Java✦

🔷.NET✦

v0.1.4Node.js 18+

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

⌘K

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: Node.js 18 or higher

Install Synapse CLI globally from npm (recommended) or run it on demand via npx.

RecommendedInstall globally via npm

bash

npm install -g @2ndbrainlabs-ai/synapse-cli

Requires Node.js 18+. After installation, run synapse init inside your project directory.

Run once via npx

bash

npx @2ndbrainlabs-ai/synapse-cli init

No install step — npx fetches and runs the CLI on demand. Good for trying it out; each subsequent command needs the npx @2ndbrainlabs-ai/synapse-cli prefix unless you install it globally.

Verify installation

bash

synapse --version# or, without a global install:npx @2ndbrainlabs-ai/synapse-cli --version

Quick Start

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

Set Up a Python Environment for the Generated Server

Optional

Synapse CLI itself runs on Node.js, but the MCP server it generates is Python-based. Using uv and a virtual environment keeps that server's dependencies isolated from the rest of your machine.

Install uv — macOS / Linux

bash

curl -LsSf https://astral.sh/uv/install.sh | sh

Install uv — Windows (PowerShell)

bash

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Create a virtual environment in your project directory

bash

uv venv

Activate it

bash

source .venv/bin/activate   # macOS / Linux.venv\Scripts\activate      # Windows

Your Python executable path (use this in MCP config later)

bash

.venv/bin/python3

Once activated, install the generated server's dependencies (e.g. pip install mcp) and run it inside this isolated environment.

Install Synapse CLI

Install globally from npm.

bash

npm install -g @2ndbrainlabs-ai/synapse-cli

Prefer not to install anything? Run npx @2ndbrainlabs-ai/synapse-cli init instead — no global install, just a slower cold start each time.

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.

How to get your Synapse API Key

Go to the Console page (top-right of the navbar after logging in)
Click API Keys in the left sidebar
Click Create API Key, give it a name, and confirm
Copy the key immediately — it is shown only once and cannot be retrieved later
Use that key as <YOUR_API_KEY> in the commands below

Option A — Store via CLI (recommended)

bash

synapse config --global --key <YOUR_API_KEY>

Option B — Environment variable (takes highest precedence)

bash

export SYNAPSE_API_KEY=<YOUR_API_KEY>

Verify it was saved

bash

synapse config

API Key Precedence Order

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

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

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.

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 output

bash

synapse analyze --verbose

Save analysis to a custom directory

bash

synapse analyze --output ./my-analysis

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

Build Your MCP Server

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

Interactive mode: select endpoints

bash

synapse build

Or with a query

bash

synapse build --query "expose the database query functions as MCP tools"

Specify a custom output filename

bash

synapse build --query "wrap the authentication endpoints" --output auth_mcp_server.py

Skip validation step

bash

synapse 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 reinitialize

bash

synapse 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 output

bash

synapse 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.

Interactive mode: select endpoints and describe your needs

bash

synapse build

With inline query

bash

synapse build --query "expose all database access functions"

Custom output file, skip validation

bash

synapse 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.

View current config

bash

synapse config

Set a project-level API key

bash

synapse config --key sk-ant-xxxxxxxxxxxx

Set a global API key (all projects)

bash

synapse config --global --key sk-ant-xxxxxxxxxxxx

Interactive update

bash

synapse 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

SYNAPSE_API_KEYEnvironment Variable

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

.synapse/config.jsonProject Key

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

~/.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:

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

Open "API Keys" from the sidebar

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

Click "Create API Key"

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

Copy your key immediately

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

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

macOS~/Library/Application Support/Claude/claude_desktop_config.json

Windows%APPDATA%\Claude\claude_desktop_config.json

Open (or create) the config file at the path shown for your OS above
Add the mcpServers block below — if the file already has content, merge the new entry inside the existing mcpServers object
Replace /absolute/path/to/mcp_server.py with the real path — run pwd in your project directory and append /mcp_server.py
If you set up a virtual env in Step 1, replace "python" with your venv path, e.g. .venv/bin/python3
Save the file, then fully quit Claude Desktop (Cmd+Q on macOS, or right-click the taskbar icon → Quit on Windows) and reopen it

json

{  "mcpServers": {    "my-project": {      "command": "python",      "args": ["/absolute/path/to/mcp_server.py"]    }  }}

After reopening, Claude Desktop will connect to your MCP server. You can verify this in the connector/plug icon in the Claude Desktop toolbar.

Cursor

Global~/.cursor/mcp.json

Project.cursor/mcp.json

Open (or create) ~/.cursor/mcp.json for a global config, or .cursor/mcp.json inside your project to scope it to one workspace
Add the mcpServers block below, merging if the file already has content
Replace /absolute/path/to/mcp_server.py with the real path and update "python" to your venv path if applicable
Save the file — Cursor picks up MCP config changes automatically. Go to Cursor Settings → MCP to confirm the server appears as enabled

json

{  "mcpServers": {    "my-project": {      "command": "python",      "args": ["/absolute/path/to/mcp_server.py"]    }  }}

Use the project-level file (.cursor/mcp.json) to scope the server to one workspace only.

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.

Verify Your MCP Server

Use these two checks to confirm your MCP server is running correctly end-to-end.

Step A — Console verification

Go to the Console page and click Manage MCP Servers in the left sidebar
Your MCP server and its exposed tools should be listed there
If the server is missing, re-run synapse build in your project directory and confirm the mcp_server.py file exists

Step B — Claude Desktop verification

After reopening Claude Desktop, click the plug / connectors icon in the toolbar
Your server (e.g. my-project) should appear under Connected in the MCP connectors list
Open a new chat and ask Claude: "What tools do you have access to?" — Claude should list your Synapse MCP tools in its response, confirming the connection is working

Synapse v1.0.0 | MIT License

Documentation

Introduction

Installation

Quick Start

Set Up a Python Environment for the Generated Server

Install Synapse CLI

Set Up Global Authorization

Initialize Synapse in Your Project

Analyze Your Codebase

Build Your MCP Server

Commands

Configuration

Configuration Files

API Key Precedence

Generating Your API Key

Secrets & Variables

Env Secrets: ${VAR_NAME}

Dynamic URL Params: {param}

Full Example

Connect to AI Tools

Claude Desktop

Cursor

Windsurf

Verify Your MCP Server

Env Secrets: `${VAR_NAME}`

Dynamic URL Params: `{param}`