mcp-tools

name	mcp_tools
description	Buddy MCP server: 15 tools for system observability, feedback loop control, OANDA state, and knowledge management. Use when querying system health, investigating trades, or triggering diagnostics/self-heal.
user-invocable	false

Buddy MCP Tools

15 tools via Model Context Protocol (stdio transport) for orchestrator observability, feedback loop control, OANDA queries, and knowledge management.

---

Server Launch

python src/mcp/buddy_server.py    # stdio transport

Register in Claude Desktop mcp.json:

{
  "mcpServers": {
    "buddy": {
      "command": "python",
      "args": ["src/mcp/buddy_server.py"],
      "env": {"OANDA_API_TOKEN": "your-token", "OANDA_ACCOUNT_ID": "your-account-id"}
    }
  }
}

---

Tool Reference

1. health_check -- Aggregate health snapshot

Params: None. Use: Start of any investigation, morning check, post-deployment.

{"diagnostics": {"status": "HEALTHY", "issues": []}, "last_feedback": {"trade_id": "12345", "shaped_reward": 8.5}, "last_decision": null, "agent_weights_count": 48, "rl_model_age_hours": 12.3, "overall": "HEALTHY"}

2. get_system_status -- Orchestrator module/session/improvement status

Params: None. Use: When you need module availability or session stats beyond health_check.

3. get_trade_feedback_log -- Tail of trade feedback JSONL

Params: n: int = 50. Use: After trade close, shaped reward trend analysis, post-loss review.

{"count": 1, "records": [{"trade_id": "12345", "pair": "EUR_USD", "shaped_reward": 8.5, "pnl_pips": 12.0, "slippage_pips": 1.5, "mae_pips": 4.0, "regime": "NORMAL"}]}

4. get_system_decisions -- Tail of self-heal decision JSONL

Params: n: int = 50. Use: After self-heal runs, verifying corrective actions, auditing decisions.

{"count": 1, "records": [{"trigger": "drawdown_streak", "issue": "5 consecutive losses", "action_taken": "reduce_risk_per_trade_pct", "degraded_mode": false}]}

5. get_agent_weights -- Current agent weights by regime bucket

Params: None. Use: Investigating agent performance, post self-heal reset, post-loss analysis.

{"NORMAL": {"trend": 1.2, "mean_reversion": 0.8}, "_meta": {"last_updated": "2026-04-12T08:00:00+00:00"}}

6. get_gate_health -- Gate firing rate issues only

Params: None. Use: When gates seem too tight (blocking all) or too loose (passing all).

{"status": "DEGRADED", "gate_issues": [{"check": "gate_firing_rate", "severity": "warning", "detail": "gate 'confidence_passed' pass rate 0.980 above ceiling"}], "thresholds": {"gate_broken_off_lt": 0.05, "gate_broken_on_gt": 0.95, "gate_window": 50}}

7. get_learnings -- Read .claude/learnings.md

Params: None. Use: Reviewing insights, checking patterns, following up on health_check issues. Returns "truncated": true if file exceeds 100 KB.

8. trigger_diagnostics -- Run the 5-check diagnostics suite

Params: None. Use: Get a health report without applying corrections. Use before trigger_self_heal to review first.

{"status": "DEGRADED", "issues": [{"check": "drawdown_streak", "severity": "warning", "value": 5, "threshold": 5}], "recommended_actions": ["reduce_risk_per_trade_pct"], "metadata": {"trades_analyzed": 150}}

9. trigger_self_heal -- Diagnostics + corrective actions

Params: diag_result: dict | null = null (if null, runs diagnostics first). Use: Automated correction of flagged issues.

{"diagnostics": {"status": "DEGRADED"}, "heal": {"status": "applied", "actions_taken": [{"action": "reduce_risk_per_trade_pct", "success": true}], "files_modified": [".claude/config_adjustments.json"], "degraded_mode": false}}

10. trigger_rl_update -- Feedback loop for one trade

Params: trade_id: str (required). Use: Manually process a specific trade through shaped-reward logging, diagnostics, self-heal. Does NOT update agent weights.

{"status": "processed", "trade_id": "12345", "shaped_reward": 8.5, "diagnostics": {"status": "HEALTHY"}, "self_heal": null}

11. trigger_gate_retrain -- Retrain gate models

Params: None. Use: When direction accuracy is degraded. Respects 60-minute cooldown. Returns {"error": "online_retrainer not available"} if module missing.

12. write_learning -- Append to learnings.md

Params: content: str (required, max 5000 chars). Use: Record a pattern or insight from trade analysis.

{"status": "appended", "path": ".claude/learnings.md"}

13. write_rule -- Create a rule file

Params: filename: str (must match [a-z0-9_]+.md), content: str (required). Use: Promote a 3x-observed learning to a rule. Cannot overwrite trading.md or improvement.md.

14. get_open_positions -- OANDA open positions

Params: None. Use: Check current exposure, pre-trade risk assessment. Requires: OANDA_API_TOKEN + OANDA_ACCOUNT_ID env vars.

{"trades": [{"tradeID": "12345", "instrument": "EUR_USD", "currentUnits": "1000", "unrealizedPL": "3.50"}]}

15. get_closed_trades -- OANDA closed trade history

Params: count: int = 50 (max 500). Use: Review recent history, correlate with feedback log. Requires: OANDA_API_TOKEN + OANDA_ACCOUNT_ID env vars.

{"trades": [{"tradeID": "12340", "instrument": "GBP_USD", "realizedPL": "-5.20", "closeTime": "2026-04-12T09:15:00Z"}]}

---

Tool Chains

Morning Health Check

health_check --> review status --> if issues: get_learnings to check for recurring patterns.

Post-Loss Investigation

get_trade_feedback_log(5) --> trigger_diagnostics --> get_agent_weights --> decide: trigger_self_heal or escalate to human.

Gate Tune

get_gate_health --> trigger_self_heal if issues --> get_system_decisions to verify actions applied.

Full Reset

trigger_diagnostics --> trigger_self_heal --> trigger_gate_retrain --> health_check to confirm HEALTHY.

---

OANDA Tools Caveat

Tools 14 and 15 require OANDA_API_TOKEN + OANDA_ACCOUNT_ID env vars. If missing, they return {"error": "credentials_missing"}. All other tools work without credentials.

Error Handling

Every tool returns structured JSON even on failure. Check for the "error" key in every response before acting on data. No tool raises an unhandled exception to the MCP client.

---

Key Source File

• src/mcp/buddy_server.py -- All 15 tool definitions, Pydantic return models, FastMCP server setup