Local MCP Servers

Local MCP servers run as processes on your machine and communicate via stdin/stdout. They're ideal for tools that need access to your local filesystem, local services, or packages installed on your machine.

Connecting a local server

In Settings → MCP Servers, scroll to the Add Server form and click the Local toggle (the alternative is Remote). Fill the fields:

Field	Description
Name	Unique identifier — used as the tool prefix (e.g. git__git_status)
Label	Human-friendly display name shown on the card
Command	Executable to run (e.g. uvx, npx, python)
Args	Command arguments — space-separated in the input box, parsed into a list
Env	Optional environment variables to pass to the process

Click Connect. Synapse spawns the process, performs the MCP handshake, and the server appears as a card with a green status dot. If the handshake fails, the card shows error and the Settings → Logs tab carries the underlying stderr.

Preset shortcuts

Above the form, the Local Presets row offers one-click pre-fills for common servers — most prominently Git (uvx mcp-server-git). Click a preset to populate the form, edit fields if needed, then click Connect.

Common examples

Git

• Name: git
• Command: uvx
• Args: mcp-server-git --repository /home/user/my-project

Tools available: git__git_status, git__git_log, git__git_diff, git__git_commit, etc.

Advanced: equivalent settings.json entry

{
  "name": "git",
  "label": "Git",
  "server_type": "stdio",
  "command": "uvx",
  "args": ["mcp-server-git", "--repository", "/home/user/my-project"],
  "env": {}
}

Filesystem

• Name: filesystem
• Command: npx
• Args: -y @modelcontextprotocol/server-filesystem /home/user/projects

Advanced: equivalent settings.json entry

{
  "name": "filesystem",
  "label": "Filesystem",
  "server_type": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
  "env": {}
}

Custom Python MCP server

• Name: my-tools
• Command: python
• Args: /home/user/my-mcp-server.py
• Env: API_KEY=secret

Advanced: equivalent settings.json entry

{
  "name": "my-tools",
  "label": "My Custom MCP",
  "server_type": "stdio",
  "command": "python",
  "args": ["/home/user/my-mcp-server.py"],
  "env": { "API_KEY": "secret" }
}

Finding MCP servers

Browse the MCP server registry for community-maintained servers. Any server that implements the MCP stdio transport works with Synapse.

Prerequisites for common servers

Server	Install command
mcp-server-git	pip install uvx (uvx handles the rest)
@modelcontextprotocol/server-filesystem	Node.js + npm install -g @modelcontextprotocol/server-filesystem
mcp-server-sqlite	pip install uvx

Troubleshooting

If a local server fails to connect:

1. Test the command manually in your terminal — it should start without errors.
2. Check that the command is in your PATH.
3. Verify any required environment variables are set.
4. Check server logs in Settings → Logs.
5. Click Reconnect on the card to retry.

Assigning local server tools to agents

After connecting, open the agent editor (Agents → click your agent) and tick the tools you want this agent to use under the Tools section. Local server tools appear in the list prefixed with the server name (e.g. git__git_status).