# @synchronex/mcp-proxy

Credential-aware MCP proxy for Synchronex.

It provides:
- local standalone memory tools backed by SQLite + FTS:
  - `get_kernel`
  - `remember`
  - `log_decision`
  - `recall`
- `proxy_search`
- `proxy_schema`
- `proxy_call`

and routes credentials per project/profile using:
- `~/.synchronex/vault.enc`
- `~/.synchronex/master.key`
- `~/.synchronex/projects.json`
- `~/.synchronex/servers.json`

Local memory state is stored per profile at:
- `~/.synchronex/local-memory/<profile>.sqlite`

The local tools do not depend on Supabase or embeddings. They are the
local-mode MVP for Synchronex Memory MCP.

## Upstream servers: stdio and http

Each `servers.json` entry declares `serverType: 'stdio' | 'http'` (defaults to
`'stdio'` for entries written before this existed):

- `stdio` spawns `command`/`args` as a local process; `credentialKeys` become
  env vars merged into the child process's environment.
- `http` connects via MCP Streamable HTTP to `url`; `credentialKeys` are
  literal HTTP header names (e.g. `Authorization`, `X-Sendinel-Project-Id`)
  sent as-is from the vault credential map — no local process, no npx.

See `docs/brain/ops/mcp-proxy.md` for server-classification guidance.

## Terminal session attribution

When the proxy runs inside a Synchronex desktop terminal pane, the terminal
injects `SYNCHRONEX_SESSION_ID` into the pane environment before launching the
AI CLI. Stdio MCP servers inherit that environment, so the proxy attaches the
session id to each local-memory or upstream `proxy_call` telemetry record.

The proxy posts those call records to Synchronex through `/api/proxy/health`
once per minute. The app verifies the MCP API key, checks that the terminal
session belongs to the authenticated user, then writes `ai_cost_events` rows
with `source="interactive_terminal"` and `cost_usd=0`. `api_equivalent_cost_usd`
is estimated server-side from the reported input/output token counts so local
MCP usage can be shown honestly as avoided API spend.

This uses environment inheritance rather than MCP request metadata because
stdio MCP does not provide a portable per-request Synchronex session header. If
the proxy is launched outside a Synchronex terminal pane, `SYNCHRONEX_SESSION_ID`
is absent and aggregate proxy telemetry still reports, but per-terminal cost
events are skipped.