# Synapse MT5 Installation Guide

Synapse MT5 is a commercial MCP bridge for MetaTrader 5 on Windows. This guide covers the standard customer setup: install the package, attach the included Expert Advisor, add your license key to your MCP client, and choose the permission profile you want.

## Requirements

- Windows 10/11 x64
- MetaTrader 5
- Node.js 16 or newer
- A Synapse MT5 license key delivered after purchase

## 1. Install

Use `npx` in your MCP client configuration. You do not need a separate global install:

```json
{
  "mcpServers": {
    "synapse-mt5": {
      "command": "npx",
      "args": ["-y", "synapse-mt5", "--", "--profile", "read_only"],
      "env": {
        "SYNAPSE_LICENSE_KEY": "YOUR-LICENSE-KEY"
      }
    }
  }
}
```

The `--` separator is required when using `npx`; it tells npm to pass the following arguments to Synapse MT5.

## 2. Install the MT5 Expert Advisor

1. Open MetaTrader 5.
2. Go to **File > Open Data Folder**.
3. Open `MQL5\Experts`.
4. Copy `ea\SynapseMT5.ex5` from the npm package into that folder.
5. Restart MetaTrader 5.
6. Attach `SynapseMT5` to one chart.

The license key belongs in the MCP config as `SYNAPSE_LICENSE_KEY`. Do not paste license keys into the EA inputs.

## 3. EA Inputs

These are the normal customer-facing controls:

| EA input | Default | Purpose |
|---|---:|---|
| `InpPort` | `7777` | Bridge port; only change this if you also pass `--port` |
| `InpAllowTrading` | `true` | EA-side gate for order tools |
| `InpAllowedSymbols` | `all` | EA-side symbol allowlist |
| `InpMaxVolume` | `0.10` | EA-side max lots per order |
| `InpDryRun` | `false` | Checks orders without sending them |

## 4. Permission Profiles

Use `--profile <name>` in the MCP config:

| Profile | Use it for |
|---|---|
| `read_only` | Account, positions, orders, logs, market data, history, and trade previews |
| `analysis` | Read-only tools plus chart screenshots |
| `chart_control` | Analysis plus chart drawing and chart cleanup tools |
| `trade_draft_only` | Trade planning without confirmed order sends |
| `trade_execution_enabled` | Guarded order placement, modification, and closing |
| `admin` | Diagnostics and support recovery tools |

## 5. Trading Configuration

For trade execution, configure both the profile and the trading guard arguments:

```json
{
  "mcpServers": {
    "synapse-mt5": {
      "command": "npx",
      "args": [
        "-y", "synapse-mt5",
        "--",
        "--profile", "trade_execution_enabled",
        "--allow-trading",
        "--allowed-symbols", "EURUSD,GBPUSD",
        "--max-volume", "0.01"
      ],
      "env": {
        "SYNAPSE_LICENSE_KEY": "YOUR-LICENSE-KEY"
      }
    }
  }
}
```

Use `--allowed-symbols all` if you want the MCP bridge to allow every symbol that your broker exposes. Keep the EA input allowlist aligned with the same policy.

## 6. Useful Arguments

| Argument | Purpose |
|---|---|
| `--profile <name>` | Selects the permission profile |
| `--port <number>` | Matches the EA bridge port; default is `7777` |
| `--allow-trading` | Enables order-routing tools on the MCP side |
| `--allowed-symbols <list>` | Comma-separated exact symbols, `all`, or empty to block trading |
| `--max-volume <lots>` | MCP-side max lots per order |
| `--dry-run` | Checks orders without sending them |

If you change trading arguments while Synapse MT5 is already running, restart your MCP client so the new settings take effect.

## 7. Recovery

Agents can call:

| Tool | Purpose |
|---|---|
| `bridge.status` | Show license, connection, profile, EA, and runtime status |
| `bridge.refresh` | Refresh license/status state and request a fresh EA handshake |
| `chart.list` | Confirm which charts are open |
| `chart.close` / `chart.close_all` | Clean up chart windows after analysis |

If the bridge reports `EA_NOT_CONNECTED`, confirm that the EA is attached to a chart, MT5 is running, and the port matches.

If the license state looks stale after editing your MCP config, restart the MCP client. Current builds also support `bridge.refresh` for normal recovery.

If `bridge.status` shows an older EA version after updating the npm package, copy the new `ea\SynapseMT5.ex5` into MT5 again and reattach the EA or restart MT5.

## 8. Support

- Purchase and license delivery: https://mfalme4.gumroad.com/l/synapse-mt5
- Setup notes: https://synapse-mt5.vercel.app
- Support: support@synapse-mt5.dev

Synapse MT5 is infrastructure software. It is not a signal service, broker, or financial advisor. Test on a demo account first and keep conservative risk limits when enabling execution.