milele-mcp

Read-only MCP server for Milele Prime. Lets a verified client connect their own AI (Claude / ChatGPT) to their own trading account and read account data — no order execution in phase 1.

Stack

TypeScript · Node 22 · Express · @modelcontextprotocol/sdk · Zod · Postgres (Supabase) · opaque revocable tokens · Vitest · Railway.

Related MCP server: hl-read

The core idea: two interfaces are the swap point

Everything in src/ talks to two interfaces, never to a real API:

• IdentityProvider (src/providers/interfaces/identity.ts) — Brokeret fills this

• TradingDataProvider (src/providers/interfaces/trading.ts) — MT5 Manager API fills this

Trading is real (MT5, verified live). Identity is still mock — see the warning under Deploy.

Run it

npm install
cp .env.example .env      # defaults to mock providers, no infra needed
npm run dev               # boots on :8080
npm test                  # 56 tests, fully offline
npm run mt5:test          # staged MT5 connectivity probe (needs credentials)
npm run mt5:verify        # exercises all 6 read methods against the live server

The tool surface (6 read tools)

There is no get_price_history. This access server's Web API exposes no OHLC/bars command — CHART_GET, CHART_REQUEST, BAR_GET, RATE_GET, TICK_HISTORY and ~50 other spellings were all rejected by the live server while every real command answered (an unknown command drops the socket, which makes that a reliable negative). Rather than advertise a tool that always fails, the capability is absent from the interface and the MCP surface. Restoring it needs a separate feed: the MT5 Gateway/datafeed API, or the broker's own history service.

The five write tools (place_market_order, place_pending_order, modify_position, close_position, cancel_order) are still registered but unimplemented against MT5 — the real adapter throws not wired yet, so they return internal_error. Phase 2.

How MT5 is wired

The MT5 "Web API" is not HTTP/REST despite the name and the :443 port. It is a raw TCP socket protocol, and the session is the socket — no cookie, no bearer token. Framing and the challenge-response handshake live in src/providers/real/mt5/protocol.ts.

src/providers/real/mt5/connection.ts holds ONE persistent authenticated manager socket and multiplexes every query over it:

• Requests are serialized. The protocol correlates a response to a request by an echoed packet number on a single byte stream, so two in-flight requests would corrupt the framing for both. Concurrent tool calls are safe.

• Drops auto-recover. A dead socket loses the session, so a transport failure re-dials, re-authenticates with exponential backoff, and retries the read once. A non-zero RETCODE is an answer, not an outage, and never triggers a reconnect.

• Isolation is unchanged. The socket authenticates as the manager and can see every account on the server. It queries only the login the adapter hands it, and the auth gate remains the only thing that decides that login.

Security model (proven by the test suite)

Every tool call goes through AuthGate.resolve() which:

1. validates the token (exists, not revoked),

2. confirms via the CRM that the token's login is owned by that client,

3. confirms the account is KYC-approved and live,

then runs the tool with the login the gate resolved — never a login from the caller. A client cannot pass a login and read another account. test/isolation.test.ts proves: own-account read works, cross-account is blocked, forged/revoked/garbage tokens are rejected, suspended accounts are blocked.

Deploy (Railway)

⚠️ Identity is still MOCK

This deployment runs IDENTITY_PROVIDER=mock with TRADING_PROVIDER=real. That means:

• Token issuance uses mock fixtures, not real client credentials. Anyone who knows a fixture client id and password (client_A / portal-pw-A, which are in this repo) can mint a token.

• That token then reads real money data from the live MT5 server.

This is acceptable only for the owner-testing phase, on accounts the owner controls. It is NOT safe for real clients. Do not hand the URL to anyone outside the team, and swap IDENTITY_PROVIDER=real (Brokeret) before onboarding a single real client.

Mock identity also owns fixture logins (50001–50003) that do not exist on the MT5 server, so every live read would come back empty. Set MOCK_OWNER_LOGIN to a real MT5 login to repoint client_A at it for testing.

Railway environment variables

Secrets live only in Railway environment variables. .env is gitignored and has never been committed — verify with git log --all -- .env (empty).

Outbound network — the thing most likely to break

Railway must reach 91.243.178.145:443 over raw TCP. This is not an HTTPS request, so anything that assumes HTTP (proxies, L7 egress filtering) will not work.

If the MT5 side enforces an IP allowlist, Railway's egress IP must be whitelisted. Railway egress IPs are not stable on the free/hobby tiers — a static egress IP generally needs a paid plan or an outbound proxy. Confirm this with the MT5 admin before assuming it works.

An allowlist that drops packets (the common case) does not produce a connection-refused error; it looks like a silent timeout. /health reports both the same way, with an explicit hint.

Health check

GET /health:

{
  "ok": true,
  "identity": "mock",
  "trading": "real",
  "mt5": {
    "configured": true,
    "endpoint": "91.243.178.145:443",
    "state": "connected",
    "transport": "plain-tcp",
    "lastConnectedAt": "2026-07-31T08:14:33.304Z"
  }
}

mt5.state is one of connected, disconnected (was up, socket since dropped — normal when idle, the next call re-dials), never_connected, or error. On failure, mt5.lastError carries the reason:

{
  "configured": true,
  "endpoint": "198.51.100.99:443",
  "state": "error",
  "lastError": "could not establish an authenticated MT5 session to 198.51.100.99:443 after 5 attempts: Error: socket idle timeout after 3000ms — the MT5 access server refused, dropped or ignored the TCP connection. Check outbound egress from this host, and if the access server enforces an IP allowlist, this host's egress IP must be whitelisted."
}

Two deliberate choices:

• ok reflects this service, not the broker. A refused MT5 socket must not fail Railway's health check and trigger a restart loop — the server is healthy and serving; the upstream is not. Point Railway's health check at /health and read mt5.state separately.

• /health never dials. It reports the last observed state, so the check stays cheap and cannot hang on a dead broker. Use GET /health?probe=1 to force a live dial attempt when diagnosing egress.

The MT5 socket is opened in the background at boot, so /health has a real answer within a second or two of startup without waiting for the first tool call. A broker that is unreachable at boot never stops the server from starting — the failure is recorded and surfaced, not fatal.

Deploy checklist

1. Set every variable in the table above in Railway.

2. Run db/migrations/001_init.sql against Supabase (npm run migrate).

3. Deploy. Confirm the boot log shows mt5_boot_state with "state":"connected".

4. curl https://<app>.up.railway.app/health → mt5.state should be connected (or disconnected if it has been idle — that is fine).

5. If state is error, read lastError. A timeout almost always means egress or an IP allowlist, not a bug.

6. Mint a token via POST /connect/initiate and call get_account_summary.

Build sequence (status)

• Server skeleton + config + factory (swap point)

• Two provider interfaces

• Mock implementations of both

• Token service (Postgres-backed; falls back to in-memory without DATABASE_URL)

• Authorization gate + audit log + tool runner

• Cross-account isolation test passing

• All 6 read tools

• MCP SDK streamable-HTTP transport

• CRM "Connect AI Assistant" portal flow — POST /connect/initiate|revoke, GET /connect/activity

• Real MT5 trading adapter (read side), verified live

• Real Brokeret identity adapter ← the blocker for real clients

• Write/execution tools against MT5 (phase 2, needs compliance sign-off)

• Price history — needs a datafeed the Web API doesn't provide

Adding a tool

1. Add the method to TradingDataProvider + both mock and real impls.

2. Add a tool function in src/tools/index.ts using runTool(...) (gate + audit are automatic).

3. Register it in buildMcpServer in src/server.ts.

4. Add an isolation assertion for it in test/isolation.test.ts.