list_fai_departments next channel

Status: Modified (auth/endpoint migration to production data-api/v2; input/output unchanged) This tool is on the private next MCP channel for allow-listed orgs. When promoted, this file moves to mcp-tools/list-fai-departments.md.

List Functional Area Intelligence (FAI) departments and their roles from the official HG Insights catalog. Returns each department's hex ID and name along with its roles (role hex ID and name). Pass the returned department IDs to company_fai as department_ids to filter FAI results.

Integration required: hginsights_v2__data_api Cache schema version: 2 (differs from base — stale cached payloads from the public channel will not be served)

Parameters

Parameter	Type	Required	Default	Description
name	string	Optional	—	Filter departments by name (case-insensitive partial match), e.g. 'engineering'. Matching is delegated to the upstream catalog. Omit to list the full catalog.
limit	integer	Optional	—	Maximum number of departments to return (>= 0). Omit for the upstream default.
offset	integer	Optional	—	Number of departments to skip for pagination (>= 0). Omit to start from the first record.

Response Format

{
  "count": 45,
  "data": [
    {
      "id": "a1b2c3d4…",
      "name": "Engineering",
      "roles": [
        { "id": "e5f6a7b8…", "name": "Software Engineer" },
        { "id": "c9d0e1f2…", "name": "DevOps Engineer" }
      ]
    }
  ]
}

Response fields

Field	Meaning
count	Total number of matching FAI departments (upstream total; may exceed returned rows).
data	Array of FAI department records.
data[].id	FAI department ID (hex-encoded). Use in company_fai department_ids.
data[].name	FAI department name.
data[].roles	Roles within the department; each has id (hex-encoded) and name.

Example Usage

{
  "tool": "list_fai_departments",
  "parameters": {
    "name": "engineering"
  }
}

Related Tools

• company_fai — use department and role IDs from here to filter FAI results.
• company_technographic — get product_ids to filter company_fai.

Changelog

2026-08-06 — Migrate to data-api/v2 + Bearer token auth

Availability: live on next only (allow-listed orgs via POST /api/mcp/next). This entry moves to webapp/docs/tool-changelogs/list-fai-departments.md when promoted.

Why this changed: list_fai_departments was calling an internal staging proxy endpoint instead of the production data-api/v2 that all other HG catalog tools use. Aligning it ensures every allow-listed partner gets consistent credential requirements and production reliability across the FAI catalog and company FAI tools.

Integration key change (allow-listed orgs only)

	Before (v1, public /api/mcp)	After (next channel)
Integration key	hginsights_v2	hginsights_v2__data_api
Auth header	X-API-Key: <key>	Authorization: Bearer <key>
Base URL	unified-api.yavin.hip.staging.hginsights.com	api.hginsights.com
Endpoint path	/v2/catalog/fai_departments	/data-api/v2/catalog/fai_departments

What stayed the same

All parameters (name, limit, offset), output fields (count, data[].id, data[].name, data[].roles), tool key (list_fai_departments), credit cost (0), and the tool description are identical to v1. The only changes are internal to the HTTP call: the integration key, auth header, and base URL.