trader-mcp/MCP_SURFACE_PROPOSAL.md

Trader MCP Surface Proposal

Keep the public MCP surface small and standardized.

Proposed tools

1. list_strategies()

Returns a compact inventory of loaded strategies.

{
  "strategies": [
    {
      "id": "grid-1",
      "name": "Grid Trader",
      "mode": "active",
      "status": "running"
    }
  ]
}

2. get_strategy(id)

Returns the full strategy record, including config, state, and key live metadata.

Optional flags:

• include_render

• include_debug

  {
  "id": "grid-1",
  "name": "Grid Trader",
  "mode": "active",
  "config": {
  "grid_levels": 6,
  "fee_rate": 0.0025
  },
  "state": {
  "center_price": 2375.2,
  "last_price": 2374.8,
  "last_side": "buy",
  "open_order_count": 4,
  "last_error": ""
  },
  "account_id": "qndd8o9ppop6",
  "market_symbol": "xrpusd"
  }
  

3. update_strategy(id, config?, state?)

Writes config/state changes for an existing strategy, then reconciles it.

{
  "id": "grid-1",
  "updated": true
}

4. control_strategy(id, action)

Single control entry point for start, pause, resume, stop, and reconcile.

{
  "id": "grid-1",
  "action": "pause",
  "ok": true
}

Design notes

• get_strategy() is the main read tool.
• update_strategy() is the write tool for config/state.
• control_strategy() handles lifecycle and reconcile.
• Keep the surface compact and predictable.
• Prefer returning real live metadata in get_strategy() instead of adding more specialized tools.