DebtStack MCP Server

Instructions

Implementation Reference

• debtstack/mcp_server.py:196-237 (registration)

  Tool registration with name, description, and input schema for search_companies

  @app.list_tools()
  async def list_tools() -> list[Tool]:
      """List available DebtStack tools."""
      return [
          Tool(
              name="search_companies",
              description=(
                  "Search companies by ticker, sector, leverage ratio, and risk flags. "
                  "Use to find companies with specific characteristics, compare leverage across peers, "
                  "or screen for structural subordination risk. "
                  "Example: 'Find tech companies with leverage above 4x'"
              ),
              inputSchema={
                  "type": "object",
                  "properties": {
                      "ticker": {
                          "type": "string",
                          "description": "Comma-separated tickers (e.g., 'AAPL,MSFT,GOOGL')"
                      },
                      "sector": {
                          "type": "string",
                          "description": "Filter by sector (e.g., 'Technology', 'Energy')"
                      },
                      "min_leverage": {
                          "type": "number",
                          "description": "Minimum leverage ratio"
                      },
                      "max_leverage": {
                          "type": "number",
                          "description": "Maximum leverage ratio"
                      },
                      "has_structural_sub": {
                          "type": "boolean",
                          "description": "Filter for structural subordination"
                      },
                      "limit": {
                          "type": "integer",
                          "description": "Maximum results (default 10)"
                      }
                  },
                  "required": []
              }

• debtstack/mcp_server.py:423-434 (handler)

  Handler that executes search_companies by calling the API, formatting results, and returning formatted text

  if name == "search_companies":
      params = {k: v for k, v in arguments.items() if v is not None}
      params.setdefault("limit", 10)
      result = api_get("/companies", params)
  
      companies = result.get("data", [])
      if not companies:
          return [TextContent(type="text", text="No companies found matching criteria.")]
  
      text = f"Found {len(companies)} companies:\n\n"
      text += "\n\n---\n\n".join(format_company(c) for c in companies)
      return [TextContent(type="text", text=text)]

• debtstack/mcp_server.py:95-120 (helper)

  Helper function that formats company data for readable output

  def format_company(c: dict) -> str:
      """Format company data for display."""
      lines = [f"**{c.get('name', 'Unknown')}** ({c.get('ticker', '?')})"]
  
      if c.get('sector'):
          lines.append(f"Sector: {c['sector']}")
  
      debt = c.get('total_debt')
      if debt:
          lines.append(f"Total Debt: ${debt / 100_000_000_000:.2f}B")
  
      lev = c.get('net_leverage_ratio')
      if lev:
          lines.append(f"Net Leverage: {lev:.1f}x")
  
      cov = c.get('interest_coverage')
      if cov:
          lines.append(f"Interest Coverage: {cov:.1f}x")
  
      if c.get('has_structural_sub'):
          lines.append("⚠️ Has structural subordination")
  
      if c.get('has_near_term_maturity'):
          lines.append("⚠️ Near-term maturities")
  
      return "\n".join(lines)

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

  Helper function that makes HTTP GET requests to the DebtStack API

  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/langchain.py:118-150 (schema)

  Pydantic schema for search_companies input validation used in LangChain integration

  class SearchCompaniesInput(BaseModel):
      """Input for company search tool."""
      ticker: Optional[str] = Field(
          None,
          description="Comma-separated tickers (e.g., 'AAPL,MSFT,GOOGL')"
      )
      sector: Optional[str] = Field(
          None,
          description="Filter by sector (e.g., 'Technology', 'Energy')"
      )
      min_leverage: Optional[float] = Field(
          None,
          description="Minimum leverage ratio (e.g., 3.0)"
      )
      max_leverage: Optional[float] = Field(
          None,
          description="Maximum leverage ratio (e.g., 6.0)"
      )
      has_structural_sub: Optional[bool] = Field(
          None,
          description="Filter for companies with structural subordination"
      )
      fields: Optional[str] = Field(
          None,
          description="Comma-separated fields to return (e.g., 'ticker,name,net_leverage_ratio')"
      )
      sort: Optional[str] = Field(
          None,
          description="Sort field, prefix with - for descending (e.g., '-net_leverage_ratio')"
      )
      limit: int = Field(
          10,
          description="Maximum results to return"