> For the complete documentation index, see [llms.txt](https://help.nightfall.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.nightfall.ai/developer-api/nightfall_apis/ai-governance-apis.md).

# AI Governance API's

## List MCP servers

> List the inventory of MCP servers, aggregated per server (one row per fingerprint + version) with device counts, usage metrics, and risk.

```json
{"openapi":"3.0.3","info":{"title":"Nightfall AI Governance API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/ai-governance/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"McpServer":{"type":"object","properties":{"id":{"type":"string","description":"Opaque server id. Use this value in path parameters; it encodes the (fingerprint, version) key."},"serverId":{"type":"string","description":"The server fingerprint (e.g. \"npm:@scope/pkg\", \"oci:image:tag\", \"url:domain\")."},"canonicalName":{"type":"string"},"version":{"type":"string"},"transport":{"type":"string","description":"Transport mechanism (stdio, http, sse, etc.)"},"risk":{"type":"integer"},"riskLabel":{"type":"string"},"riskIndicator":{"type":"string"},"isShadow":{"type":"boolean","description":"True when the server is not associated with any known client."},"remoteUrl":{"type":"string"},"clients":{"type":"array","items":{"type":"string"}},"deviceCount":{"type":"integer"},"clientCount":{"type":"integer"},"totalSpawns":{"type":"integer"},"totalNetworkCalls":{"type":"integer"},"totalRequestBytes":{"type":"integer"},"totalResponseBytes":{"type":"integer"},"firstSeen":{"type":"integer","description":"Unix timestamp (seconds) of first observation."},"lastUsed":{"type":"integer","description":"Unix timestamp (seconds) of last activity. Omitted when never used."},"registry":{"$ref":"#/components/schemas/McpRegistryMetadata"}}},"McpRegistryMetadata":{"type":"object","description":"Public registry metadata; only populated on the single-server detail endpoint.","properties":{"name":{"type":"string"},"description":{"type":"string"},"isOfficial":{"type":"boolean"},"isVerified":{"type":"boolean"},"popularityScore":{"type":"integer"},"repositoryUrl":{"type":"string"},"websiteUrl":{"type":"string"},"license":{"type":"string"},"packageName":{"type":"string"},"packageRegistry":{"type":"string","description":"Source registry (npm, pypi, oci, etc.)"}}},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"A status code to uniquely describe this error."},"message":{"type":"string","description":"A message associated with the status code."},"description":{"type":"string","description":"Additional details to explain what may have occurred. Omitted if empty."}}}}},"paths":{"/mcp-servers":{"get":{"summary":"List MCP servers","description":"List the inventory of MCP servers, aggregated per server (one row per fingerprint + version) with device counts, usage metrics, and risk.","parameters":[{"name":"limit","in":"query","description":"Maximum number of records to return (default 20, max 100)","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"pageToken","in":"query","description":"Opaque pagination cursor returned as nextPageToken in a prior response","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","description":"Sort order (default DEVICE_COUNT_DESC)","required":false,"schema":{"type":"string","enum":["DEVICE_COUNT_DESC","DEVICE_COUNT_ASC","NAME_ASC","NAME_DESC","RISK_DESC","RISK_ASC","LAST_USED_DESC","LAST_USED_ASC"]}},{"name":"search","in":"query","description":"Case-insensitive match on the server name","required":false,"schema":{"type":"string","maxLength":255}},{"name":"transport","in":"query","description":"Exact match on transport (e.g. stdio, http, sse)","required":false,"schema":{"type":"string","maxLength":64}},{"name":"client","in":"query","description":"Filter to these client names (e.g. cursor, vscode). Repeatable, max 20.","required":false,"schema":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":128}}},{"name":"riskLevel","in":"query","description":"Filter to these risk levels. Repeatable.","required":false,"schema":{"type":"array","items":{"type":"string","enum":["KNOWN","LOW","MEDIUM","HIGH","CRITICAL"]}}},{"name":"minLastActiveAt","in":"query","description":"Unix timestamp in seconds; exclude servers not active since this time","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","headers":{"X-Rate-Limit-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next second before being throttled"}},"X-Quota-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next quota period"}},"X-Quota-Period-End":{"schema":{"type":"string","format":"date-time","description":"When the current quota period expires"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"mcpServers":{"type":"array","items":{"$ref":"#/components/schemas/McpServer"}},"total":{"type":"integer","description":"Total matching servers (present on the first page)"},"nextPageToken":{"type":"string","description":"Opaque cursor for the next page; omitted when there are no more results"}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","headers":{"Retry-After":{"schema":{"type":"integer","description":"Seconds after which to retry the request"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Get an MCP server

> Fetch a single MCP server by its opaque id, including registry metadata when available.

```json
{"openapi":"3.0.3","info":{"title":"Nightfall AI Governance API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/ai-governance/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"McpServer":{"type":"object","properties":{"id":{"type":"string","description":"Opaque server id. Use this value in path parameters; it encodes the (fingerprint, version) key."},"serverId":{"type":"string","description":"The server fingerprint (e.g. \"npm:@scope/pkg\", \"oci:image:tag\", \"url:domain\")."},"canonicalName":{"type":"string"},"version":{"type":"string"},"transport":{"type":"string","description":"Transport mechanism (stdio, http, sse, etc.)"},"risk":{"type":"integer"},"riskLabel":{"type":"string"},"riskIndicator":{"type":"string"},"isShadow":{"type":"boolean","description":"True when the server is not associated with any known client."},"remoteUrl":{"type":"string"},"clients":{"type":"array","items":{"type":"string"}},"deviceCount":{"type":"integer"},"clientCount":{"type":"integer"},"totalSpawns":{"type":"integer"},"totalNetworkCalls":{"type":"integer"},"totalRequestBytes":{"type":"integer"},"totalResponseBytes":{"type":"integer"},"firstSeen":{"type":"integer","description":"Unix timestamp (seconds) of first observation."},"lastUsed":{"type":"integer","description":"Unix timestamp (seconds) of last activity. Omitted when never used."},"registry":{"$ref":"#/components/schemas/McpRegistryMetadata"}}},"McpRegistryMetadata":{"type":"object","description":"Public registry metadata; only populated on the single-server detail endpoint.","properties":{"name":{"type":"string"},"description":{"type":"string"},"isOfficial":{"type":"boolean"},"isVerified":{"type":"boolean"},"popularityScore":{"type":"integer"},"repositoryUrl":{"type":"string"},"websiteUrl":{"type":"string"},"license":{"type":"string"},"packageName":{"type":"string"},"packageRegistry":{"type":"string","description":"Source registry (npm, pypi, oci, etc.)"}}},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"A status code to uniquely describe this error."},"message":{"type":"string","description":"A message associated with the status code."},"description":{"type":"string","description":"Additional details to explain what may have occurred. Omitted if empty."}}}}},"paths":{"/mcp-servers/{serverId}":{"get":{"summary":"Get an MCP server","description":"Fetch a single MCP server by its opaque id, including registry metadata when available.","parameters":[{"name":"serverId","in":"path","required":true,"description":"Opaque MCP server id from a list response","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","headers":{"X-Rate-Limit-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next second before being throttled"}},"X-Quota-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next quota period"}},"X-Quota-Period-End":{"schema":{"type":"string","format":"date-time","description":"When the current quota period expires"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpServer"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"MCP server does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","headers":{"Retry-After":{"schema":{"type":"integer","description":"Seconds after which to retry the request"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## List devices for an MCP server

> List the devices using a specific MCP server, with a per-client usage breakdown.

```json
{"openapi":"3.0.3","info":{"title":"Nightfall AI Governance API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/ai-governance/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"McpServerDevice":{"type":"object","properties":{"deviceId":{"type":"string"},"userEmail":{"type":"string"},"userName":{"type":"string"},"machineName":{"type":"string"},"clients":{"type":"array","items":{"type":"string"}},"totalSpawns":{"type":"integer"},"totalNetworkCalls":{"type":"integer"},"totalRequestBytes":{"type":"integer"},"totalResponseBytes":{"type":"integer"},"lastUsed":{"type":"integer","description":"Unix timestamp (seconds) of last activity on this device."},"clientBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/McpServerDeviceClient"}}}},"McpServerDeviceClient":{"type":"object","properties":{"client":{"type":"string"},"configuredName":{"type":"string"},"stdioTimesSpawned":{"type":"integer"},"timesNetworkCalled":{"type":"integer"},"lastUsedAt":{"type":"integer","description":"Unix timestamp (seconds) of last activity for this client."},"isShadow":{"type":"boolean"},"stdioCommand":{"type":"string"},"execArgs":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"A status code to uniquely describe this error."},"message":{"type":"string","description":"A message associated with the status code."},"description":{"type":"string","description":"Additional details to explain what may have occurred. Omitted if empty."}}}}},"paths":{"/mcp-servers/{serverId}/devices":{"get":{"summary":"List devices for an MCP server","description":"List the devices using a specific MCP server, with a per-client usage breakdown.","parameters":[{"name":"serverId","in":"path","required":true,"description":"Opaque MCP server id from a list response","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"pageToken","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","description":"Sort order (default LAST_USED_DESC)","required":false,"schema":{"type":"string","enum":["LAST_USED_DESC","LAST_USED_ASC","DEVICE_ID_ASC"]}},{"name":"search","in":"query","description":"Match on device id, machine name, user name, or user email","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Successful response","headers":{"X-Rate-Limit-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next second before being throttled"}},"X-Quota-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next quota period"}},"X-Quota-Period-End":{"schema":{"type":"string","format":"date-time","description":"When the current quota period expires"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"devices":{"type":"array","items":{"$ref":"#/components/schemas/McpServerDevice"}},"total":{"type":"integer"},"nextPageToken":{"type":"string"}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","headers":{"Retry-After":{"schema":{"type":"integer","description":"Seconds after which to retry the request"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## List devices with MCP servers

> List devices that have any MCP server installed, aggregated per device.

```json
{"openapi":"3.0.3","info":{"title":"Nightfall AI Governance API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/ai-governance/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"McpDevice":{"type":"object","properties":{"deviceId":{"type":"string"},"serverCount":{"type":"integer"},"totalSpawns":{"type":"integer"},"totalNetworkCalls":{"type":"integer"},"lastActive":{"type":"integer","description":"Unix timestamp (seconds) of last activity across all servers."},"firstSeen":{"type":"integer","description":"Unix timestamp (seconds) of first observation across all servers."},"machineName":{"type":"string"},"os":{"type":"string"},"osVersion":{"type":"string"},"userEmail":{"type":"string"},"agentStatus":{"type":"string"}}},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"A status code to uniquely describe this error."},"message":{"type":"string","description":"A message associated with the status code."},"description":{"type":"string","description":"Additional details to explain what may have occurred. Omitted if empty."}}}}},"paths":{"/devices":{"get":{"summary":"List devices with MCP servers","description":"List devices that have any MCP server installed, aggregated per device.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"pageToken","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","description":"Sort order (default SERVER_COUNT_DESC)","required":false,"schema":{"type":"string","enum":["SERVER_COUNT_DESC","LAST_ACTIVE_DESC","FIRST_SEEN_DESC"]}},{"name":"search","in":"query","description":"Match on device machine name","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Successful response","headers":{"X-Rate-Limit-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next second before being throttled"}},"X-Quota-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next quota period"}},"X-Quota-Period-End":{"schema":{"type":"string","format":"date-time","description":"When the current quota period expires"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"devices":{"type":"array","items":{"$ref":"#/components/schemas/McpDevice"}},"total":{"type":"integer"},"nextPageToken":{"type":"string"}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","headers":{"Retry-After":{"schema":{"type":"integer","description":"Seconds after which to retry the request"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Get a device and its MCP servers

> Fetch a device and the full list of MCP servers running on it. The server list is returned inline and is not paginated.

```json
{"openapi":"3.0.3","info":{"title":"Nightfall AI Governance API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/ai-governance/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"McpDevice":{"type":"object","properties":{"deviceId":{"type":"string"},"serverCount":{"type":"integer"},"totalSpawns":{"type":"integer"},"totalNetworkCalls":{"type":"integer"},"lastActive":{"type":"integer","description":"Unix timestamp (seconds) of last activity across all servers."},"firstSeen":{"type":"integer","description":"Unix timestamp (seconds) of first observation across all servers."},"machineName":{"type":"string"},"os":{"type":"string"},"osVersion":{"type":"string"},"userEmail":{"type":"string"},"agentStatus":{"type":"string"}}},"McpServer":{"type":"object","properties":{"id":{"type":"string","description":"Opaque server id. Use this value in path parameters; it encodes the (fingerprint, version) key."},"serverId":{"type":"string","description":"The server fingerprint (e.g. \"npm:@scope/pkg\", \"oci:image:tag\", \"url:domain\")."},"canonicalName":{"type":"string"},"version":{"type":"string"},"transport":{"type":"string","description":"Transport mechanism (stdio, http, sse, etc.)"},"risk":{"type":"integer"},"riskLabel":{"type":"string"},"riskIndicator":{"type":"string"},"isShadow":{"type":"boolean","description":"True when the server is not associated with any known client."},"remoteUrl":{"type":"string"},"clients":{"type":"array","items":{"type":"string"}},"deviceCount":{"type":"integer"},"clientCount":{"type":"integer"},"totalSpawns":{"type":"integer"},"totalNetworkCalls":{"type":"integer"},"totalRequestBytes":{"type":"integer"},"totalResponseBytes":{"type":"integer"},"firstSeen":{"type":"integer","description":"Unix timestamp (seconds) of first observation."},"lastUsed":{"type":"integer","description":"Unix timestamp (seconds) of last activity. Omitted when never used."},"registry":{"$ref":"#/components/schemas/McpRegistryMetadata"}}},"McpRegistryMetadata":{"type":"object","description":"Public registry metadata; only populated on the single-server detail endpoint.","properties":{"name":{"type":"string"},"description":{"type":"string"},"isOfficial":{"type":"boolean"},"isVerified":{"type":"boolean"},"popularityScore":{"type":"integer"},"repositoryUrl":{"type":"string"},"websiteUrl":{"type":"string"},"license":{"type":"string"},"packageName":{"type":"string"},"packageRegistry":{"type":"string","description":"Source registry (npm, pypi, oci, etc.)"}}},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"A status code to uniquely describe this error."},"message":{"type":"string","description":"A message associated with the status code."},"description":{"type":"string","description":"Additional details to explain what may have occurred. Omitted if empty."}}}}},"paths":{"/devices/{deviceId}":{"get":{"summary":"Get a device and its MCP servers","description":"Fetch a device and the full list of MCP servers running on it. The server list is returned inline and is not paginated.","parameters":[{"name":"deviceId","in":"path","required":true,"description":"Device id from a device list response","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","headers":{"X-Rate-Limit-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next second before being throttled"}},"X-Quota-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next quota period"}},"X-Quota-Period-End":{"schema":{"type":"string","format":"date-time","description":"When the current quota period expires"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"device":{"$ref":"#/components/schemas/McpDevice"},"mcpServers":{"type":"array","items":{"$ref":"#/components/schemas/McpServer"}}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Device does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","headers":{"Retry-After":{"schema":{"type":"integer","description":"Seconds after which to retry the request"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.nightfall.ai/developer-api/nightfall_apis/ai-governance-apis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.