list_companies
List all companies associated with your firm with pagination and optional filtering by company IDs.
Instructions
List all companies associated with your firm.
Args: page: Page number for pagination (default: 1) per_page: Results per page (default: 100, max: 100) ids: Filter by specific company IDs
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| per_page | No | ||
| ids | No |
Implementation Reference
- src/tools.py:43-57 (handler)The MCP tool handler for 'list_companies' decorated with @mcp.tool. Uses StandardMetrics client to call get_companies with pagination params and optional IDs filter.
@mcp.tool async def list_companies( page: int = 1, per_page: int = 100, ids: list[str] | None = None, ) -> PaginatedCompanies: """List all companies associated with your firm. Args: page: Page number for pagination (default: 1) per_page: Results per page (default: 100, max: 100) ids: Filter by specific company IDs """ async with StandardMetrics() as client: return await client.get_companies(page=page, page_size=per_page, ids=ids) - src/_types.py:82-99 (schema)The Company Pydantic model returned by list_companies, containing id, name, slug, description, city, sector, etc.
class Company(pydantic.BaseModel): id: str name: str slug: str | None = None description: str | None = None city: str | None = None sector: CompanySector | None = None firm_sector: str | None = None fiscal_year_end: str | None = pydantic.Field( None, description="MM/DD format", ) website: str | None = None logo_url: str | None = None status: str | None = None investment_lead_id: str | None = None invested_fund_ids: list[str] | None = None unique_ref: str | None = None - src/_types.py:265-273 (schema)The PaginatedResponse generic model and PaginatedCompanies type alias used as the return type of list_companies.
class PaginatedResponse[T](pydantic.BaseModel): results: list[T] count: int | None = None next: str | None = None previous: str | None = None # These can't be type-aliases as we need to make use of runtime behavior. PaginatedCompanies = PaginatedResponse[Company] - src/server.py:74-78 (registration)Where all tools (including list_companies) are registered: the FastMCP server instance and the wildcard import that pulls in all @mcp.tool decorated functions from src/tools.py.
mcp = fastmcp.FastMCP[Any]( "smx-mcp", instructions=_MCP_INSTRUCTIONS, ) from src.tools import * # noqa: F403 - need to register all of the tools - src/_client.py:120-133 (helper)The underlying API client method get_companies that sends a GET request to 'v1/companies/' and parses the response into PaginatedCompanies.
async def get_companies( self, *, page: int = 1, page_size: int = 100, ids: list[str] | None = None, ) -> PaginatedCompanies: """Get all companies associated with your firm.""" params: dict[str, Any] = {"page": page, "page_size": page_size} if ids: for company_id in ids: params.setdefault("ids[]", []).append(company_id) response = await self._request("GET", "v1/companies/", params=params) return PaginatedCompanies.model_validate(response)