SynapsesOS
Getting Started

Editor Setup

Synapses connects to AI agents via the Model Context Protocol (MCP) over stdio transport. The synapses init command auto-detects your editor and writes the correct configuration, but you can also set things up manually.

Claude Code

When you run synapses init in a project that uses Claude Code, Synapses automatically configures two files:

.claude/settings.json — Registers Synapses as an MCP server:

{
  "mcpServers": {
    "synapses": {
      "command": "synapses",
      "args": ["start", "--path", "/absolute/path/to/your/project"]
    }
  }
}

.claude/CLAUDE.md — Adds agent instructions tailored to your project’s scale. For large projects, this includes guidance to use Synapses tools (get_context, search) instead of raw file scanning.

After setup, Claude Code automatically launches the Synapses MCP server when you open the project. No manual server start is needed.

Cursor

Synapses writes .cursor/mcp.json:

{
  "mcpServers": {
    "synapses": {
      "command": "synapses",
      "args": ["start", "--path", "/absolute/path/to/your/project"],
      "transport": "stdio"
    }
  }
}

Restart Cursor after adding this configuration. The Synapses tools will appear in Cursor’s MCP tool list.

Windsurf

Synapses writes .windsurf/mcp_config.json:

{
  "mcpServers": {
    "synapses": {
      "command": "synapses",
      "args": ["start", "--path", "/absolute/path/to/your/project"],
      "transport": "stdio"
    }
  }
}

Restart Windsurf to pick up the new MCP configuration.

Zed

Synapses writes .zed/settings.json (or merges into an existing one):

{
  "mcpServers": {
    "synapses": {
      "command": "synapses",
      "args": ["start", "--path", "/absolute/path/to/your/project"]
    }
  }
}

Manual Setup (Any MCP-Compatible Agent)

Any agent that supports MCP over stdio can connect to Synapses. The pattern is the same regardless of the agent:

  1. Start Synapses with your project path:
Terminal window
synapses start --path /path/to/your/project
  1. Configure your agent to use that command as its MCP server with stdio transport.

The --path flag tells Synapses which project to load. If you’re already in the project directory, you can omit it:

Terminal window
cd /path/to/your/project
synapses start

Connecting Additional Agents

If you’ve already initialized a project and want to add another agent, use:

Terminal window
synapses connect

This presents an interactive prompt to select which agent to configure, then writes the appropriate config file without re-indexing the project.

Verifying the Connection

Once your agent is connected, the quickest way to verify is to ask it to call the session_init tool. A successful response means Synapses is running and the agent can access all 12 MCP tools.

If the connection fails, check:

  • The synapses binary is on your system PATH
  • The project path in the config is an absolute path
  • The project has been indexed (synapses index)
  • No other process is using the same stdio channel

Multiple Projects

Each project gets its own Synapses instance. If you work across multiple projects, each one has its own synapses.json and index. Agents connect to the correct instance automatically based on the --path argument in their MCP configuration.

For monorepo and multi-project setups, see the federation documentation.

Next Steps

Now that your editor is connected, read Core Concepts to understand how the code graph, context carving, and brain tiers work under the hood.