synapse-cli-ts

Enterprise Context Engine

Today: MCP Servers. Tomorrow: Every Context Surface Your Stack Needs.

Turn any codebase into a production-ready Model Context Protocol server — from your terminal, in seconds.

Homepage · Docs · Report an issue · Discussions

What is Synapse?

Synapse is building the context layer enterprises need to make their internal systems agent-ready. Today, we're open-sourcing the first piece of that vision: an agentic MCP server generator that analyzes existing codebases and generates production-ready MCP servers.

Synapse is a CLI that reads your codebase and generates a runnable MCP server — the tool schemas, argument marshalling, and boilerplate are all handled for you. Point it at a project, describe what you want exposed, and drop the resulting server into Claude Desktop, Cursor, or any MCP-compatible client.

The CLI does source exploration client-side — nothing is uploaded. Generation runs on the Synapse backend by default, so model routing, retries, and quota stay centrally managed — or entirely on your own model with --local, using Anthropic, OpenAI, Groq, xAI, OpenRouter, Ollama, Amazon Bedrock, Google Vertex AI, or your own inference endpoint. See Run locally with your own model.

Install

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

Requires Node.js 18+. Verify with synapse --version.

Quick start

cd my-project
synapse init                    # one-time: paste your API key
synapse analyze                 # scans code, writes .synapse/schema.json
synapse build                   # discovers use cases, prompts you to pick

The generated server lands at ./mcp_server.py. Copy the printed JSON snippet into your MCP client config and you're done.

Prefer to describe it yourself:

synapse build --query "Expose user auth and profile lookup as MCP tools"

Run locally with your own model

Skip the hosted Synapse service entirely — codegen runs in-process using your inference provider. No quota, no code upload, no signup required.

export ANTHROPIC_API_KEY=sk-ant-…

cd my-project
synapse build --local           # generates locally on your own key

--local is a per-invocation flag — no project config pins a repo to local mode, so switching back is just dropping the flag. synapse init is not required for a local build.

Locally-generated servers don't count against any quota; analyze runs are unbounded. Anonymous usage telemetry (no code, no prompts — just event names + counts) still flows to api.synaps3.ai; opt out with SYNAPSE_TELEMETRY=0.

Local-mode limits:

• Python target only (TypeScript target follows).
• Auto flow (--auto) requires the hosted service. Use --custom (the default in local mode).
• Provider selection applies to local mode only — hosted builds run on the Synapse service, and synapse model does not change them.

Choosing a provider

Local mode is not Anthropic-only. synapse model picks the provider and models it runs on:

synapse model                   # what a local build would use right now
synapse model list              # every provider, its default model, key status
synapse model set groq          # switch (keeps that provider's defaults)
synapse model reset             # back to Anthropic

Pin models per stage — the pipeline uses a cheap model for high-volume triage and a strong one for codegen, so you can mix:

synapse model set groq --generate "openai/gpt-oss-120b" --triage "llama-3.1-8b-instant"
synapse model set openai --model gpt-5        # one --model pins every stage

Model ids are not validated against a built-in list — provider catalogues change often (Groq retired the Kimi and Llama-4-Scout ids during 2026; xAI redirects whole grok-3 / grok-4-fast families), so a hardcoded allowlist would reject valid models and need a CLI release to fix. Any id your provider accepts works. If an id is wrong, the provider says so.

Providing your API key

Synapse does not sniff for keys. You choose the provider; the provider's spec declares which environment variable holds its key. There are three ways to supply one, checked in this order:

1. Environment variable — the default, and the recommended path.

Two conveniences:

• xAI accepts either name — both XAI_API_KEY and GROK_API_KEY are in circulation, so both are read (XAI_API_KEY wins).
• SYNAPSE_LLM_API_KEY is a universal fallback for every provider, tried after the provider-specific var. Useful in CI, where one secret can serve whichever provider is configured.

Ollama needs no key, and Synapse omits the Authorization header entirely when there isn't one — so a bare local Ollama works with no credentials at all.

2. A flag, for a single run — nothing is written anywhere:

synapse build --local --llm-api-key sk-… --provider openai

3. Stored, encrypted — explicit opt-in (see Where keys are stored):

synapse model set groq --save-key gsk_…

Copy-paste quickstarts

# Anthropic (default — nothing to configure)
export ANTHROPIC_API_KEY=sk-ant-…
synapse build --local

# Groq
export GROQ_API_KEY=gsk_…
synapse model set groq
synapse build --local

# OpenAI
export OPENAI_API_KEY=sk-…
synapse model set openai
synapse build --local

# xAI (Grok)
export XAI_API_KEY=xai-…
synapse model set grok
synapse build --local

# OpenRouter
export OPENROUTER_API_KEY=sk-or-…
synapse model set openrouter
synapse build --local

# Ollama — no key needed
ollama pull qwen3-coder:30b
synapse model set ollama
synapse build --local

Cloud providers: Amazon Bedrock and Google Vertex AI

Run local codegen on models in your own AWS or Google Cloud account. Synapse never sees or stores a cloud credential: it uses the same credentials your aws / gcloud CLI already uses, and --save-key is refused for these providers.

Amazon Bedrock — credentials from the standard AWS chain: AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, a profile (AWS_PROFILE or --profile), an SSO session from aws sso login, or a Bedrock API key in AWS_BEARER_TOKEN_BEDROCK. Requires Node 20+.

aws sso login --profile work
synapse model set bedrock --region us-east-1 --profile work
synapse build --local

• Defaults are Claude Sonnet 4.5 (generate) and Haiku 4.5 (triage) via cross-region inference profiles. The us. / eu. / apac. prefix is picked from your region automatically.
• Enable access to the models in the Bedrock console (Model access) for that region first. Otherwise Bedrock returns an access-denied error, which Synapse explains.
• Any Bedrock model works through the Converse API, e.g. --model us.amazon.nova-pro-v1:0. Claude, Nova and Mistral get a forced tool call. Other families get a JSON fallback.
• Region comes from --region, then SYNAPSE_LLM_REGION, then the saved config, then AWS_REGION / AWS_DEFAULT_REGION, then us-east-1.

Google Vertex AI — credentials from Application Default Credentials: gcloud auth application-default login, GOOGLE_APPLICATION_CREDENTIALS pointing at a service-account key, or the attached service account on GCP. The account needs roles/aiplatform.user.

gcloud auth application-default login
synapse model set vertex --project my-gcp-project            # Claude, global location
synapse model set vertex --project my-gcp-project --model gemini-2.5-pro
synapse build --local

• claude-* model ids go to Vertex's Anthropic API, so behaviour, forced tool calls and prompt caching match the direct Anthropic path. Enable the Claude models in Model Garden first.
• Any other id (gemini-2.5-pro, gemini-2.5-flash, Model Garden models) goes to Vertex's OpenAI-compatible endpoint. You can mix them per stage: --triage gemini-2.5-flash --generate claude-sonnet-4-5@20250929.
• Location defaults to global. Use --region us-east5 (or GOOGLE_CLOUD_LOCATION) to pin a region.
• Project comes from --project, then SYNAPSE_LLM_PROJECT, then the saved config, then GOOGLE_CLOUD_PROJECT.

For a one-off build without saving anything: synapse build --local --provider vertex --llm-project my-proj --llm-region us-east5.

Checking that a key was picked up

synapse model reports the resolved key and where it came from, so a key that isn't being read is visible before a build rather than after:

  Provider        Groq (project)
  API key         gsk_t*************** (env GROQ_API_KEY)

keySource is one of flag, env <VAR>, stored, or (not set). If a required key is missing, Synapse names the variable to set and links the provider's key page instead of failing mid-build.

Provider differences Synapse handles for you

The OpenAI chat-completions contract is not implemented identically everywhere. Synapse carries four capability flags per provider and adjusts the request; you don't configure any of this for the built-in providers.

Why this matters: every stage of local codegen is a single forced tool call returning JSON that matches a strict schema. tool_choice is how that is normally enforced — so a provider that ignores it needs a second path, not a warning.

Both paths are always tolerated on the way back. Tools are advertised even on the JSON path, so a model that can call them still does; and extraction accepts either a tool_calls entry or a JSON object in the message content, regardless of which was requested. A server that claims to support tool_choice and quietly ignores it therefore still works.

Model capability, not API capability. The JSON fallback makes weaker models reachable, not competent. Codegen needs a model that can hold a strict schema; small local models often can't, and fail with returned no emit_tool_plan call. The fix is a stronger model, and the error message says so.

Your own inference endpoint

Anything exposing POST {base_url}/chat/completions with the OpenAI request/response shape works — vLLM, TGI, LM Studio, llama.cpp, SGLang, an internal gateway, or your own GPU cluster:

synapse model set custom \
  --base-url http://gpu.internal:8000/v1 \
  --model qwen3-coder-30b \
  --header "X-Route: a100"          # repeatable

Because Synapse can't probe your server, partial compatibility is something you declare. These are the same flags as the capability table above, exposed for custom:

A key is optional for custom. When supplied (via SYNAPSE_LLM_API_KEY, --llm-api-key, or --save-key) it is sent as Authorization: Bearer <key>.

Config schema

synapse model set writes an llm block to .synapse/config.json, or to ~/.synapse/config.json with --global. You can also hand-write it.

Field reference

Any subset of models is valid — unset stages fall back to that provider's defaults. Omitted capability fields fall back to the provider's built-in flags.

Example

{
  "llm": {
    "provider": "custom",
    "base_url": "http://gpu.internal:8000/v1",
    "models": {
      "triage": "qwen3-4b",
      "generate": "qwen3-coder-30b",
      "verify": "qwen3-coder-30b",
      "fallback_generate": "qwen3-4b"
    },
    "headers": { "X-Route": "a100" },
    "tool_choice": false,
    "api_key_prefix": "sk-in",
    "api_key_encrypted": "gAAAAAB…"
  }
}

Validation

The block is schema-validated on every read and is strict — an unknown or misspelled key is rejected rather than silently ignored. An invalid block does not fail your build: Synapse prints a warning naming the offending field and falls back to the next source in the resolution order.

Resolution order

Provider, model and endpoint resolve independently, highest first:

1. CLI flags — --provider, --model, --llm-base-url
2. Env — SYNAPSE_LLM_PROVIDER, SYNAPSE_LLM_MODEL, SYNAPSE_LLM_BASE_URL
3. Project .synapse/config.json → llm
4. Global ~/.synapse/config.json → llm
5. Anthropic with its default models

Keys resolve on their own track: --llm-api-key flag → the provider's env var → SYNAPSE_LLM_API_KEY → a --save-key stored value.

Stored models and capability flags apply only to the provider they were saved for. Switching provider with --provider never inherits the previous provider's model ids.

Environment variables

Plus the provider-specific key variables in the table above.

Where keys are stored

By default, nowhere. Inference keys are read from the environment (or a flag) on every invocation and never written to disk.

synapse model set <provider> --save-key <key> is an explicit opt-in. It stores the key Fernet-encrypted (AES-128-CBC + HMAC-SHA256) under a key derived from your username and hostname, so the file will not decrypt on another machine — moving the config elsewhere yields a warning telling you to re-enter it, not a silent failure. Only a 5-character prefix is stored in cleartext, for display. Remove it with synapse model reset.

Use --global to apply any of this to ~/.synapse instead of the current project.

Features

• Bring your own model — local builds run on Anthropic, OpenAI, Groq, xAI (Grok), OpenRouter, Ollama, or any OpenAI-compatible endpoint you host. Switch with one command; no quota, no code upload.
• Zero boilerplate — tool schemas, argument validation, and MCP wire format handled for you.
• Client-side exploration — grep, AST symbol lookup, and definition/usage tracing all run on your machine.
• First-class Python + TypeScript — full symbol and navigation support. Go, Java, C#, Rust get grep-based fallback.
• Streaming gRPC — bidirectional session with the agent so you can watch tool calls land in real time.
• Deterministic surface extraction — tree-sitter parsers with a 64KB head-sniff make repeat runs cache-friendly.
• Signed API keys — Ed25519 envelope keys, per-request quota, revocation in under 30 seconds.

Commands

Add --dev to any command to talk to a local backend on localhost:50051.

Configuration

Config is resolved in this order:

1. Environment variables (SYNAPSE_API_KEY, SYNAPSE_BACKEND_URL, SYNAPSE_DEV=1)
2. Project-local ./.synapse/config.json
3. Global ~/.synapse/config.json

This covers the hosted service. The inference provider used by --local builds is configured separately — see Config schema and Providing your API key.

How build works

synapse build opens a bidirectional gRPC stream with the backend agent. The agent never sees your code — it asks the CLI for exactly what it needs:

• read_file, find_files, grep — bounded reads over your working directory
• list_symbols, find_definition, find_usages — AST navigation via tree-sitter
• write_file, replace_file, insert_file — final artifact writes

Every tool call is scoped to process.cwd(). Only the specific bytes the agent asks for flow back over the wire.

Language support

Troubleshooting

Documentation

• Getting started — synaps3.ai/docs
• API reference — synaps3.ai/docs/api
• Examples — github.com/2ndbrainlabs-ai/synapse-examples

Development

git clone https://github.com/2ndbrainlabs-ai/synapse-cli.git
cd synapse-cli
npm install
npm run dev -- <command>        # run against source
npm run build                   # produce dist/
npm test                        # vitest suite
npm run typecheck

Contributing

Contributions are welcome. See CONTRIBUTING.md for how to file issues, run the test suite, and open a PR. All participation is subject to our Code of Conduct.

Security

Please review our Security Policy before reporting vulnerabilities.

License

Licensed under the Apache License, Version 2.0. See NOTICE for attribution.