`get_orgs`

Read-only

Calls GET /api/orgs as the signed-in person · REST reference

List organizations the caller is entitled to see

Platform staff see every org. Every other caller is narrowed AFTER the fetch to the orgs in which they hold org.view, and is refused 403 when they hold it nowhere. Holding it in a parent org does not list the parent's children: each org is listed only to a caller holding org.view in that org. count is recomputed from what survives that narrowing, so it describes the returned array and NOT the platform total. filters echoes only the filters the caller sent. Note the shape: an OBJECT with an organizations array — not the bare array that /api/orgs/tree and GET /api/users return, and not the { success, data } envelope that /api/groups and /api/roles return. name and ids are applied in-process after the DAL read, which pages through every organization. A failed read is never an empty list: a status the DAL does not know is 400, an unreachable DAL 503, any other failure 500.

Arguments

Argument	Type	Description
`status`query	string	Passed to the DAL verbatim.
`type`query	string	Passed to the DAL verbatim.
`name`query	string	Case-insensitive substring match, applied in-process after the DAL read.
`ids`query	string	Comma-separated id list, applied in-process after the DAL read.

Example call

A client sends this over the MCP session; Claude and other agents build it for you. The values are placeholders — the shape is real.

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_orgs",
    "arguments": {}
  }
}

Result

On success (HTTP 200) the tool returns one text item holding the API's JSON, pretty-printed.

The visible organizations, with a recomputed count and the echoed filters.

json

{
  "count": 1,
  "filters": {},
  "organizations": [
    {
      "createdAt": "2026-01-15T12:00:00Z",
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "string",
      "status": "string",
      "type": "string",
      "address": "string",
      "email": "string",
      "parentId": "11111111-1111-4111-8111-111111111111",
      "phone": "string",
      "taxId": "string"
    }
  ]
}

Fields

Field	Type	Description
`count`	integer	Length of `organizations` after the org.view scoping.
`filters`	object	The filters this request supplied; `{}` when none were sent.
`organizations`	array of object
`organizations[].address`	string \| null
`organizations[].createdAt`	string (date-time)
`organizations[].email`	string \| null
`organizations[].id`	string (uuid)
`organizations[].name`	string
`organizations[].parentId`	string (uuid) \| null
`organizations[].phone`	string \| null
`organizations[].status`	string
`organizations[].taxId`	string \| null
`organizations[].type`	string

When it fails

A failed call returns isError: true with the API's message as text.

400: The request was malformed or failed a guard.
403: Authenticated, but the caller holds none of the required permissions.

What the model is shown

This is the tool exactly as the server lists it in tools/list. The description starts with the REST call it makes.

json

{
  "name": "get_orgs",
  "description": "GET /api/orgs — Platform staff see every org. Every other caller is narrowed AFTER the fetch to the orgs in which they hold `org.view`, and is refused 403 when they hold it nowhere. Holding it in a parent org does not list the parent's children: each org is listed only to a caller holding `org.view` in that org. `count` is recomputed from what survives that narrowing, so it describes the returned array and NOT the platform total. `filters` echoes only the filters the caller sent. Note the shape: an OBJECT with an `organizations` array — not the bare array that `/api/orgs/tree` and `GET /api/users` return, and not the `{ success, data }` envelope that `/api/groups` and `/api/roles` return. `name` and `ids` are applied in-process after the DAL read, which pages through every organization. A failed read is never an empty list: a `status` the DAL does not know is 400, an unreachable DAL 503, any other failure 500.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "status": {
        "type": "string",
        "description": "Passed to the DAL verbatim."
      },
      "type": {
        "type": "string",
        "description": "Passed to the DAL verbatim."
      },
      "name": {
        "type": "string",
        "description": "Case-insensitive substring match, applied in-process after the DAL read."
      },
      "ids": {
        "type": "string",
        "description": "Comma-separated id list, applied in-process after the DAL read."
      }
    }
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false
  }
}