@synchronex/mcp-proxy

@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.