Local (stdio) Servers

They're ideal for tools that need access to local files, local services, or packages installed on the machine SynapseOrch runs on.

Connecting a local server

In Apps, go to Connect a server, below Connected Servers, and choose Local (stdio) (the alternative is Remote (URL)). Fill the fields:

Click Connect Server. SynapseOrch checks that the command exists, saves the server, spawns the process, performs the MCP handshake and loads its tools; the card shows Connected.

• If the command isn't on the server's PATH, nothing is saved and the form says so — for uvx, with the command to install uv.
• If the handshake fails, the server is saved but shows Disconnected ("Config saved. Use Retry to reconnect."). The process's error output goes to the backend's log, not to Runs › Logs.

The process runs with the SynapseOrch backend's environment plus the variables you add, and connection and tool calls time out after 60 seconds (SYNAPSE_MCP_SESSION_READ_TIMEOUT, SYNAPSE_MCP_TOOL_CALL_TIMEOUT).

Preset shortcuts

Local Presets above the form has one preset, Git (uvx mcp-server-git, Unique ID Git). Click it to fill the form, add --repository /path/to/repo to the arguments, then click Connect Server.

When local servers are not allowed

A local server runs a command on the SynapseOrch host, so it can be turned off. Local (stdio) servers, on the Apps screen, holds both controls:

• Allow local (stdio) servers (allow_stdio_mcp, on by default) — off, a local server cannot be added: stdio MCP server registration is disabled on this deployment. Turn it off if the install can be reached over a network.
• Allowed commands (mcp_command_allowlist) — when not empty, only the commands it lists may run as local servers (for example npx, uvx); another is refused, Command 'x' is not in the allowed MCP command list. Empty allows any command.
• In scale mode local servers are always off, whatever the switch says.

A saved local server that is not allowed shows as disabled and is not started. See Settings → Security.

Common examples

Git

• Unique ID: git
• Command: uvx
• Arguments: mcp-server-git --repository /home/user/my-project

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

Filesystem

SynapseOrch already runs a built-in Filesystem server rooted at your repositories, the vault and the Allowed directories in Settings → General — see Code Repositories → Filesystem access. Add your own only to reach other directories:

• Unique ID: projects
• Command: npx
• Arguments: -y @modelcontextprotocol/server-filesystem /home/user/projects

Custom Python MCP server

• Unique ID: my-tools
• Command: python
• Arguments: /home/user/my-mcp-server.py
• Environment Variables: API_KEY = secret

Advanced: how a local server is stored

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

Servers are stored in SynapseOrch's database; Import & Export moves them between instances.

Finding MCP servers

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

Prerequisites for common servers

Troubleshooting

If a local server fails to connect:

1. Test the command manually in a terminal on the SynapseOrch host — it should start without errors.
2. Check that the command is on the backend's PATH.
3. Verify any required environment variables are set.
4. Check the backend's log for the server's error output.
5. Click Retry connection on the card.

Assigning local server tools to agents

After connecting, open the agent in Agents and enable the tools you want in its Tools section. The server appears as its own card, marked MCP; its tools are named with the server's prefix (e.g. git__git_status).