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

Go to Settings → MCP Servers → Add Server and choose Local (stdio).

Fields

Field	Description
Name	Unique identifier (used as tool prefix)
Label	Human-friendly display name
Command	The executable to run (e.g. uvx, npx, python)
Args	Command arguments as a list
Env	Environment variables to pass to the process

Example: Git MCP server

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

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

Example: Filesystem MCP server

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

Example: Python script as MCP server

{
  "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. Use the Reconnect button to retry

Assigning local server tools to agents

After connecting, go to the agent editor and select the tools you want to give the agent access to. Local server tools appear in the tool list prefixed with the server name.