DebtStack MCP Server

Instructions

Implementation Reference

• debtstack/mcp_server.py:393-414 (registration)

  Tool registration - defines the get_changes tool with name, description, and input schema (ticker and since parameters)

  Tool(
      name="get_changes",
      description=(
          "See what changed in a company's debt structure since a date. "
          "Returns new issuances, matured debt, leverage changes, and pricing movements. "
          "Use to monitor companies for material changes."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "ticker": {
                  "type": "string",
                  "description": "Company ticker"
              },
              "since": {
                  "type": "string",
                  "description": "Compare since date (YYYY-MM-DD)"
              }
          },
          "required": ["ticker", "since"]
      }
  ),

• debtstack/mcp_server.py:560-612 (handler)

  Tool handler - executes get_changes logic by calling API and formatting the response with new debt, removed debt, metric changes, and summary

  elif name == "get_changes":
      ticker = arguments.get("ticker", "").upper()
      since = arguments.get("since", "")
      result = api_get(f"/companies/{ticker}/changes", {"since": since})
  
      data = result.get("data", {})
      changes = data.get("changes", {})
  
      text = f"**Changes for {data.get('company_name', ticker)}**\n"
      text += f"Comparing {data.get('snapshot_date', '?')} → {data.get('current_date', 'now')}\n\n"
  
      # New debt
      new_debt = changes.get("new_debt", [])
      if new_debt:
          text += f"**New Debt ({len(new_debt)})**\n"
          for d in new_debt:
              text += f"• {d.get('name', '?')} - ${d.get('principal', 0) / 100_000_000_000:.2f}B\n"
          text += "\n"
  
      # Removed debt
      removed = changes.get("removed_debt", [])
      if removed:
          text += f"**Removed/Matured Debt ({len(removed)})**\n"
          for d in removed:
              text += f"• {d.get('name', '?')} ({d.get('reason', 'removed')})\n"
          text += "\n"
  
      # Metric changes
      metrics = changes.get("metric_changes", {})
      if metrics:
          text += "**Metric Changes**\n"
          for name, vals in metrics.items():
              if isinstance(vals, dict) and 'previous' in vals:
                  prev = vals['previous']
                  curr = vals['current']
                  if isinstance(prev, (int, float)) and isinstance(curr, (int, float)):
                      change = curr - prev
                      sign = "+" if change > 0 else ""
                      text += f"• {name}: {prev} → {curr} ({sign}{change})\n"
          text += "\n"
  
      summary = data.get("summary", {})
      if summary:
          text += "**Summary**\n"
          if summary.get("new_issuances"):
              text += f"• New issuances: {summary['new_issuances']}\n"
          if summary.get("maturities"):
              text += f"• Maturities: {summary['maturities']}\n"
          if summary.get("net_debt_change"):
              change = summary['net_debt_change'] / 100_000_000_000
              text += f"• Net debt change: ${change:+.2f}B\n"
  
      return [TextContent(type="text", text=text)]

• debtstack/mcp_server.py:67-76 (helper)

  API helper function - makes GET requests to DebtStack API with authentication headers

  def api_get(endpoint: str, params: dict = None) -> dict:
      """Make GET request to DebtStack API."""
      response = httpx.get(
          f"{BASE_URL}{endpoint}",
          params=params,
          headers=get_headers(),
          timeout=30.0
      )
      response.raise_for_status()
      return response.json()

• debtstack/mcp_server.py:57-64 (helper)

  Authentication helper - generates headers with API key for requests

  def get_headers() -> dict:
      """Get API headers."""
      if not API_KEY:
          raise ValueError("DEBTSTACK_API_KEY environment variable not set")
      return {
          "X-API-Key": API_KEY,
          "Content-Type": "application/json",
      }