AI Governance API's

List MCP servers

get

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

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

limitinteger · min: 1 · max: 100Optional

Maximum number of records to return (default 20, max 100)

pageTokenstringOptional

Opaque pagination cursor returned as nextPageToken in a prior response

sortstring · enumOptional

Sort order (default DEVICE_COUNT_DESC)

Possible values:

searchstring · max: 255Optional

Case-insensitive match on the server name

transportstring · max: 64Optional

Exact match on transport (e.g. stdio, http, sse)

clientstring[] · max: 20Optional

Filter to these client names (e.g. cursor, vscode). Repeatable, max 20.

minLastActiveAtintegerOptional

Unix timestamp in seconds; exclude servers not active since this time

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get/mcp-servers

HTTPcURLJavaScriptPython

GET /ai-governance/v1/mcp-servers HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "mcpServers": [
    {
      "id": "text",
      "serverId": "text",
      "canonicalName": "text",
      "version": "text",
      "transport": "text",
      "risk": 1,
      "riskLabel": "text",
      "riskIndicator": "text",
      "isShadow": true,
      "remoteUrl": "text",
      "clients": [
        "text"
      ],
      "deviceCount": 1,
      "clientCount": 1,
      "totalSpawns": 1,
      "totalNetworkCalls": 1,
      "totalRequestBytes": 1,
      "totalResponseBytes": 1,
      "firstSeen": 1,
      "lastUsed": 1,
      "registry": {
        "name": "text",
        "description": "text",
        "isOfficial": true,
        "isVerified": true,
        "popularityScore": 1,
        "repositoryUrl": "text",
        "websiteUrl": "text",
        "license": "text",
        "packageName": "text",
        "packageRegistry": "text"
      }
    }
  ],
  "total": 1,
  "nextPageToken": "text"
}

Get an MCP server

get

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

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

serverIdstringRequired

Opaque MCP server id from a list response

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

404

MCP server does not exist

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get/mcp-servers/{serverId}

HTTPcURLJavaScriptPython

GET /ai-governance/v1/mcp-servers/{serverId} HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "serverId": "text",
  "canonicalName": "text",
  "version": "text",
  "transport": "text",
  "risk": 1,
  "riskLabel": "text",
  "riskIndicator": "text",
  "isShadow": true,
  "remoteUrl": "text",
  "clients": [
    "text"
  ],
  "deviceCount": 1,
  "clientCount": 1,
  "totalSpawns": 1,
  "totalNetworkCalls": 1,
  "totalRequestBytes": 1,
  "totalResponseBytes": 1,
  "firstSeen": 1,
  "lastUsed": 1,
  "registry": {
    "name": "text",
    "description": "text",
    "isOfficial": true,
    "isVerified": true,
    "popularityScore": 1,
    "repositoryUrl": "text",
    "websiteUrl": "text",
    "license": "text",
    "packageName": "text",
    "packageRegistry": "text"
  }
}

List devices for an MCP server

get

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

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

serverIdstringRequired

Opaque MCP server id from a list response

Query parameters

limitinteger · min: 1 · max: 100Optional

pageTokenstringOptional

sortstring · enumOptional

Sort order (default LAST_USED_DESC)

Possible values:

searchstring · max: 255Optional

Match on device id, machine name, user name, or user email

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get/mcp-servers/{serverId}/devices

HTTPcURLJavaScriptPython

GET /ai-governance/v1/mcp-servers/{serverId}/devices HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "devices": [
    {
      "deviceId": "text",
      "userEmail": "text",
      "userName": "text",
      "machineName": "text",
      "clients": [
        "text"
      ],
      "totalSpawns": 1,
      "totalNetworkCalls": 1,
      "totalRequestBytes": 1,
      "totalResponseBytes": 1,
      "lastUsed": 1,
      "clientBreakdown": [
        {
          "client": "text",
          "configuredName": "text",
          "stdioTimesSpawned": 1,
          "timesNetworkCalled": 1,
          "lastUsedAt": 1,
          "isShadow": true,
          "stdioCommand": "text",
          "execArgs": [
            "text"
          ]
        }
      ]
    }
  ],
  "total": 1,
  "nextPageToken": "text"
}

List devices with MCP servers

get

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

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

limitinteger · min: 1 · max: 100Optional

pageTokenstringOptional

sortstring · enumOptional

Sort order (default SERVER_COUNT_DESC)

Possible values:

searchstring · max: 255Optional

Match on device machine name

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get/devices

HTTPcURLJavaScriptPython

GET /ai-governance/v1/devices HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "devices": [
    {
      "deviceId": "text",
      "serverCount": 1,
      "totalSpawns": 1,
      "totalNetworkCalls": 1,
      "lastActive": 1,
      "firstSeen": 1,
      "machineName": "text",
      "os": "text",
      "osVersion": "text",
      "userEmail": "text",
      "agentStatus": "text"
    }
  ],
  "total": 1,
  "nextPageToken": "text"
}

Get a device and its MCP servers

get

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

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdstringRequired

Device id from a device list response

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

404

Device does not exist

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get/devices/{deviceId}

HTTPcURLJavaScriptPython

GET /ai-governance/v1/devices/{deviceId} HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "device": {
    "deviceId": "text",
    "serverCount": 1,
    "totalSpawns": 1,
    "totalNetworkCalls": 1,
    "lastActive": 1,
    "firstSeen": 1,
    "machineName": "text",
    "os": "text",
    "osVersion": "text",
    "userEmail": "text",
    "agentStatus": "text"
  },
  "mcpServers": [
    {
      "id": "text",
      "serverId": "text",
      "canonicalName": "text",
      "version": "text",
      "transport": "text",
      "risk": 1,
      "riskLabel": "text",
      "riskIndicator": "text",
      "isShadow": true,
      "remoteUrl": "text",
      "clients": [
        "text"
      ],
      "deviceCount": 1,
      "clientCount": 1,
      "totalSpawns": 1,
      "totalNetworkCalls": 1,
      "totalRequestBytes": 1,
      "totalResponseBytes": 1,
      "firstSeen": 1,
      "lastUsed": 1,
      "registry": {
        "name": "text",
        "description": "text",
        "isOfficial": true,
        "isVerified": true,
        "popularityScore": 1,
        "repositoryUrl": "text",
        "websiteUrl": "text",
        "license": "text",
        "packageName": "text",
        "packageRegistry": "text"
      }
    }
  ]
}