EffectiveToolSurfaceResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/stormmcp/json-schema/stormmcp-effective-tool-surface-response-schema.json",
  "title": "EffectiveToolSurfaceResponse",
  "description": "Dynamic gateway self-service summary response (MCPG-882, Phase 2a): the current user's apps, each with\nits admin/preference flags and runtime McpConnectionState ResolvedMcpServerResponse.ConnectionState,\nresolved from the effective tool surface. Never exposes the hidden Dynamic gateway row id.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/stormmcp-dynamicgateway-api-openapi.yml#/components/schemas/EffectiveToolSurfaceResponse",
  "type": "object",
  "properties": {
    "tenantId": {
      "type": "string",
      "description": "Gets or sets the tenant identifier.",
      "format": "uuid"
    },
    "dynamicMcpUrl": {
      "type": "string",
      "description": "Gets or sets the public dynamic MCP URL."
    },
    "resolvedAt": {
      "type": "string",
      "description": "Gets or sets the resolution timestamp.",
      "format": "date-time"
    },
    "snapshotHash": {
      "type": "string",
      "description": "Gets or sets the effective surface snapshot hash."
    },
    "mcpServers": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ResolvedMcpServerResponse"
      },
      "description": "Gets or sets the summary libraries."
    },
    "toolkits": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ToolkitSummaryResponse"
      },
      "description": "Gets or sets the user's toolkits with their rollups (MCPG-1130). Empty for users with no toolkits."
    },
    "assignedToolkits": {
      "type": [
        "null",
        "array"
      ],
      "items": {
        "$ref": "#/$defs/AssignedToolkitSummaryResponse"
      },
      "description": "Gets or sets admin-assigned toolkits (MCPG-1672). Null when\n`self-service-dashboard` is off so flag-off summaries stay byte-identical."
    },
    "skillsToolkit": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "description": "Gets or sets the virtual Skills toolkit projection (MCPG-1511). Null when the tenant\nhas no SkillLink servers.",
          "$ref": "#/$defs/SkillsToolkitSummaryResponse"
        }
      ]
    }
  },
  "$defs": {
    "AdminToolkitAssignmentMode": {
      "description": "How assignees may change an admin-assigned toolkit (MCPG-1699).\nExisting rows default to AdminToolkitAssignmentMode.Editable."
    },
    "ApprovalClassificationResponse": {
      "type": "object",
      "properties": {
        "approved": {
          "type": "boolean",
          "description": "Gets or sets a value indicating whether the calling user holds app approval for this library."
        },
        "toolMode": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "description": "Gets or sets the approved tool scope when bool ApprovalClassificationResponse.Approved is true; null otherwise.\nApprovalToolMode.All is symbolic — the consuming surface expands it against the\nlibrary's live tool inventory.",
              "$ref": "#/$defs/ApprovalToolMode"
            }
          ]
        },
        "selectedToolNames": {
          "type": [
            "null",
            "array"
          ],
          "items": {
            "type": "string"
          },
          "description": "Gets or sets the approved tool names when ApprovalToolMode? ApprovalClassificationResponse.ToolMode is\nApprovalToolMode.Selected; empty for ApprovalToolMode.All, null when\nunapproved."
        }
      },
      "description": "The calling user's approval classification for one summary row (MCPG-1550). Informational: the\nserver never narrows a listing or refuses an operation on it — the personal gateway and personal\ntoolkit pickers render from it, and refusal at use is MCPG-1652's. ApprovalToolMode\nreaches the TypeScript client by DTO reference (MCPG-1547); do not register it in\n`StandaloneEnumSchemaProcessor`."
    },
    "ApprovalToolMode": {
      "type": "integer"
    },
    "AssignedToolkitSummaryResponse": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Gets or sets the admin toolkit identifier.",
          "format": "uuid"
        },
        "name": {
          "type": "string",
          "description": "Gets or sets the toolkit name."
        },
        "description": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets the optional description."
        },
        "origin": {
          "type": "string",
          "description": "Gets or sets the origin stamp. Always string DynamicToolkitOrigins.Admin."
        },
        "hidden": {
          "type": "boolean",
          "description": "Gets or sets a value indicating whether the caller has hidden this assignment."
        },
        "assignmentMode": {
          "description": "Gets or sets the assignment mode so the dashboard can gate hide/edit affordances (MCPG-1699).",
          "$ref": "#/$defs/AdminToolkitAssignmentMode"
        },
        "memberCount": {
          "pattern": "^-?(?:0|[1-9]\\d*)$",
          "type": [
            "integer",
            "string"
          ],
          "description": "Gets or sets the number of members in the toolkit.",
          "format": "int32"
        },
        "effectiveToolCount": {
          "pattern": "^-?(?:0|[1-9]\\d*)$",
          "type": [
            "integer",
            "string"
          ],
          "description": "Gets or sets the count of explicitly-selected tools across Selected-mode members.",
          "format": "int32"
        },
        "allToolsMemberCount": {
          "pattern": "^-?(?:0|[1-9]\\d*)$",
          "type": [
            "integer",
            "string"
          ],
          "description": "Gets or sets the count of contributing entries with `SelectedToolNames == null` (all-tools)\n(MCPG-1715). An explicit empty subset is `0` here and on int AssignedToolkitSummaryResponse.EffectiveToolCount.",
          "format": "int32"
        },
        "connectionRollup": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "description": "Gets or sets the worst-of connection rollup across the toolkit's effective member libraries.",
              "$ref": "#/$defs/McpConnectionState"
            }
          ]
        },
        "libraryIds": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Gets or sets the member library ids, ordered. Reverse join for\nIReadOnlyList<Guid>? ResolvedMcpServerResponse.AssignedToolkitIds; never mixed into user `toolkitIds`."
        }
      },
      "description": "Dynamic gateway self-service summary rollup for one admin-assigned toolkit (MCPG-1672)."
    },
    "DynamicGatewayToolCountsResponse": {
      "type": "object",
      "properties": {
        "available": {
          "pattern": "^-?(?:0|[1-9]\\d*)$",
          "type": [
            "integer",
            "string"
          ],
          "description": "Gets or sets the number of available tools.",
          "format": "int32"
        },
        "selected": {
          "pattern": "^-?(?:0|[1-9]\\d*)$",
          "type": [
            "integer",
            "string"
          ],
          "description": "Gets or sets the number of selected tools.",
          "format": "int32"
        }
      },
      "description": "Dynamic gateway tool-count DTO."
    },
    "DynamicGatewayToolPreferenceResponse": {
      "type": "object",
      "properties": {
        "mode": {
          "description": "Gets or sets the tool preference mode.",
          "$ref": "#/$defs/DynamicToolPreferenceMode"
        },
        "selectedToolNames": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Gets or sets selected original upstream tool names."
        }
      },
      "description": "Dynamic gateway tool preference DTO."
    },
    "DynamicToolPreferenceMode": {
      "type": "integer",
      "description": "Specifies how a user's dynamic gateway should expose upstream tools for a library."
    },
    "KnownMcpProvider": {
      "type": "integer",
      "description": "An MCP Server provider type."
    },
    "McpConnectionOutcome": {
      "type": "integer",
      "description": "            Coarse outcome of an MCP server's connection state — the FE-aligned ubiquitous\n            language used end-to-end across BE and FE to drive UI affordances.\n            One outcome per state; string? McpConnectionState.Reason refines an\nMcpConnectionOutcome.Error outcome with a machine-readable code from\nMcpConnectionReasons."
    },
    "McpConnectionState": {
      "type": "object",
      "properties": {
        "outcome": {
          "description": "Gets the coarse outcome — the ubiquitous language shared across BE and FE.",
          "$ref": "#/$defs/McpConnectionOutcome"
        },
        "disabled": {
          "type": "boolean",
          "description": "Gets a value indicating whether an admin has disabled this integration at\nthe tenant level. Orthogonal to McpConnectionOutcome McpConnectionState.Outcome: the outcome still\nreflects the underlying connection readiness, so re-enabling needs no\nre-derivation. Only a configured row can be disabled."
        },
        "reason": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets the machine-readable reason from McpConnectionReasons,\nor null when none applies. Set for McpConnectionOutcome.Error,\nfor Connected plus string McpConnectionReasons.RefreshPending, and\nfor NeedsSetup plus\nstring McpConnectionReasons.SchemaCredentialNotConfigured."
        },
        "reasonDetails": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets optional developer-facing detail refining the reason (e.g. UCS error\ncode, exception message). May be surfaced in logs and ProblemDetails but\nmust not be used for end-user UI strings."
        },
        "interactiveAvailable": {
          "type": [
            "null",
            "boolean"
          ],
          "description": "Gets a value indicating whether an interactive personal-OAuth connect,\nsetup, or reconnect can clear this classification. Present as\n`true` only for `not_configured`,\n`awaiting_credentials`, `credential_invalid`, and\n`misconfigured` when the primary credential of an interactive\npersonal-OAuth source is the cause. Absent (`null`) for\nnon-interactive sources, Connected results, and reasons a primary\nconnect cannot clear. Never `false`."
        },
        "recoveryCommand": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "description": "Gets the recovery action for this classification. Null on an unstamped\nsingleton (omitted from JSON and gRPC). A stamped wire state always\ncarries a value other than RecoveryCommand.Unspecified.\nAbsent means the client keeps today's derivation. Present is authoritative\nand replaces reading string? McpConnectionState.Reason to choose Connect, Reconnect,\nConfigure, or Save credential.",
              "$ref": "#/$defs/RecoveryCommand"
            }
          ]
        }
      },
      "description": "            State-only view of an MCP server connection — the wire-shape primitive that\n            every transport (REST, gRPC, SignalR push, future Orleans grain messages)\n            can carry without dragging the entire `McpServerConfiguration`\n            along. The build-outcome wrapper `McpConnectionResult` composes a\n            state with the optional built configuration.\n            Shape contract:* McpConnectionOutcome McpConnectionState.Outcome is always set.\n* string? McpConnectionState.Reason is set when\n                McpConnectionOutcome McpConnectionState.Outcome is McpConnectionOutcome.Error (from\n                McpConnectionReasons), when McpConnectionOutcome McpConnectionState.Outcome is\n                McpConnectionOutcome.Connected and the value is\n                string McpConnectionReasons.RefreshPending, or when\n                McpConnectionOutcome McpConnectionState.Outcome is McpConnectionOutcome.NeedsSetup\n                and the value is\n                string McpConnectionReasons.SchemaCredentialNotConfigured. Other\n                Connected and NeedsSetup results keep string? McpConnectionState.Reason null.\n                Unknown non-error reasons are informational and never a gate.\n* string? McpConnectionState.ReasonDetails is an optional human-readable refinement\n                (UCS error code, exception message) intended for logs and developer-facing\n                diagnostics — not for end-user UI strings.\n* Exception? McpConnectionState.Error is the original exception when the outcome was\n                caused by one. Internal use only — never serialized.\n* bool McpConnectionState.Disabled is an orthogonal admin-disable flag — it can\n                be true alongside any McpConnectionOutcome McpConnectionState.Outcome (a Connected or NeedsAuth\n                server can still be admin-disabled), so it does not collapse into the\n                readiness outcome.\n* bool? McpConnectionState.InteractiveAvailable is present (`true`)\n                only for a user-recoverable classification of an interactive personal-OAuth\n                source. It is omitted (`null`) otherwise and is never\n                `false`.\n* RecoveryCommand? McpConnectionState.RecoveryCommand is the recovery action. It is omitted\n                (`null`) on an unstamped singleton so an old payload stays\n                absent. A present value is authoritative. RecoveryCommand.Unspecified\n                is never stored."
    },
    "McpServerAuthType": {
      "type": "integer",
      "description": "An enumeration representing the authentication types for MCP servers."
    },
    "McpServerStatus": {
      "enum": [
        "Available",
        "ComingSoon",
        "Beta",
        "Deprecated",
        "Custom"
      ],
      "description": "Availability status for MCP servers."
    },
    "McpServerType": {
      "type": "integer",
      "description": "An mcp server type enumeration."
    },
    "ReachabilityClassification": {
      "type": "integer"
    },
    "RecoveryCommand": {
      "type": "integer"
    },
    "ResolvedMcpServerResponse": {
      "type": "object",
      "properties": {
        "libraryId": {
          "type": "string",
          "description": "Gets or sets the library identifier.",
          "format": "uuid"
        },
        "type": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "description": "Gets or sets the server type (MCPG-1511). SkillLink rows are\nstripped from IReadOnlyList<ResolvedMcpServerResponse> EffectiveToolSurfaceResponse.McpServers\nwhen the tenant has at least one SkillLink server.",
              "$ref": "#/$defs/McpServerType"
            }
          ]
        },
        "name": {
          "type": "string",
          "description": "Gets or sets the display name."
        },
        "provider": {
          "description": "Gets or sets the provider name.",
          "$ref": "#/$defs/KnownMcpProvider"
        },
        "category": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets the category."
        },
        "iconUrl": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets the icon URL."
        },
        "description": {
          "type": [
            "null",
            "string"
          ],
          "description": "Gets or sets the description."
        },
        "status": {
          "description": "Gets or sets the catalog status (e.g. `Custom` for a tenant-owned server).",
          "$ref": "#/$defs/McpServerStatus"
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Gets or sets the OAuth scopes the server declares (catalog metadata for the connect flow)."
        },
        "authType": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/McpServerAuthType"
          },
          "description": "Gets or sets the auth types the server supports (catalog metadata for the connect flow)."
        },
        "currentAuthType": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "description": "Gets or sets the auth type currently configured for this tenant, or null when none is configured.",
              "$ref": "#/$defs/McpServerAuthType"
            }
          ]
        },
        "adminAssigned": {
          "type": "boolean",
          "description": "Gets or sets a value indicating whether this library is assigned by admin policy."
        },
        "adminDefaultEnabled": {
          "type": "boolean",
          "description": "Gets or sets a value indicating whether admin policy enables this library by default."
        },
        "userEnabledOverride": {
          "type": [
            "null",
            "boolean"
          ],
          "description": "Gets or sets the nullable app-level preference."
        },
        "effectiveUserEnabled": {
          "type": "boolean",
          "description": "Gets or sets a value indicating whether the user wants this library enabled."
        },
        "connectionState": {
          "description": "Gets or sets the runtime connection state (outcome + the orthogonal admin-disabled flag). Runnability\nis read from this plus bool ResolvedMcpServerResponse.EffectiveUserEnabled — there is no separate flattened status.",
          "$ref": "#/$defs/McpConnectionState"
        },
        "toolPreference": {
          "description": "Gets or sets the tool preference.",
          "$ref": "#/$defs/DynamicGatewayToolPreferenceResponse"
        },
        "toolCounts": {
          "description": "Gets or sets the tool counts.",
          "$ref": "#/$defs/DynamicGatewayToolCountsResponse"
        },
        "toolkitIds": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Gets or sets the identifiers of the toolkits that reference this library (MCPG-1130). Empty when the\nlibrary is in no user toolkit (drives the self-service \"Not in a toolkit\" chip). User-toolkit ids only."
        },
        "assignedToolkitIds": {
          "type": [
            "null",
            "array"
          ],
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "description": "Gets or sets the identifiers of admin-assigned toolkits that reference this library (MCPG-1672).\nNull (omitted on the wire) when empty so flag-off summaries stay byte-identical. Admin ids are never\nmixed into IReadOnlyList<Guid> ResolvedMcpServerResponse.ToolkitIds."
        },
        "approval": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "description": "Gets or sets the calling user's approval classification for this library (MCPG-1550). Null (omitted\non the wire) unless `self-service-dashboard` is on, so SSD-off summaries stay byte-identical.",
              "$ref": "#/$defs/ApprovalClassificationResponse"
            }
          ]
        },
        "reachability": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "description": "Gets or sets the self-service reachability classification (MCPG-1550, PRD D5): approved,\nreachable-only through a shared surface, or unreachable. Computed at the `/me/summary`\nprojection, never on the cached surface. Null (omitted on the wire) whenever\nApprovalClassificationResponse? ResolvedMcpServerResponse.Approval is null. The server only classifies; drawing or withholding the connect\ncontrol is the consuming surface's, and the row is listed whatever the class.",
              "$ref": "#/$defs/ReachabilityClassification"
            }
          ]
        }
      },
      "description": "Dynamic gateway self-service summary row for one library."
    },
    "SkillsToolkitServerGroupResponse": {
      "type": "object",
      "properties": {
        "libraryId": {
          "type": "string",
          "description": "Gets or sets the library identifier.",
          "format": "uuid"
        },
        "name": {
          "type": "string",
          "description": "Gets or sets the display name."
        },
        "skillRepoUrl": {
          "type": "string",
          "description": "Gets or sets the GitHub repository URL."
        },
        "enabled": {
          "type": "boolean",
          "description": "Gets or sets a value indicating whether the caller has opted this SkillLink\nsource into the served catalog (MCPG-1766)."
        }
      },
      "description": "Identity metadata for one SkillLink group on the summary. Credential status rides\nthe full-inventory editor read exclusively."
    },
    "SkillsToolkitSummaryResponse": {
      "type": "object",
      "properties": {
        "kind": {
          "type": "string",
          "description": "Gets or sets the kind discriminator. Always string SkillsToolkitIdentity.Kind."
        },
        "enabled": {
          "type": "boolean",
          "description": "Gets or sets a value indicating whether the caller's skills master switch is on."
        },
        "serverGroups": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SkillsToolkitServerGroupResponse"
          },
          "description": "Gets or sets the SkillLink server groups (identity metadata only)."
        }
      },
      "description": "Kind-discriminated virtual Skills toolkit on the dynamic-gateway summary (MCPG-1511).\nNot a member of IReadOnlyList<ToolkitSummaryResponse> EffectiveToolSurfaceResponse.Toolkits."
    },
    "ToolkitSummaryResponse": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Gets or sets the toolkit identifier.",
          "format": "uuid"
        },
        "name": {
          "type": "string",
          "description": "Gets or sets the toolkit name."
        },
        "enabled": {
          "type": "boolean",
          "description": "Gets or sets a value indicating whether the toolkit master switch is on."
        },
        "memberCount": {
          "pattern": "^-?(?:0|[1-9]\\d*)$",
          "type": [
            "integer",
            "string"
          ],
          "description": "Gets or sets the number of members in the toolkit.",
          "format": "int32"
        },
        "effectiveToolCount": {
          "pattern": "^-?(?:0|[1-9]\\d*)$",
          "type": [
            "integer",
            "string"
          ],
          "description": "Gets or sets the count of explicitly-selected tools across Selected-mode members. All-mode members'\nfull upstream tool set is resolved in Phase 2d and is not yet included here.",
          "format": "int32"
        },
        "allToolsMemberCount": {
          "pattern": "^-?(?:0|[1-9]\\d*)$",
          "type": [
            "integer",
            "string"
          ],
          "description": "Gets or sets the count of contributing All-mode members (MCPG-1715). Zero with\nint ToolkitSummaryResponse.EffectiveToolCount 0 is an empty Selected subset, not all-tools.",
          "format": "int32"
        },
        "connectionRollup": {
          "oneOf": [
            {
              "type": "null"
            },
            {
              "description": "Gets or sets the worst-of connection rollup across the toolkit's effective member libraries, or null\nwhen there is no effective member status to render.",
              "$ref": "#/$defs/McpConnectionState"
            }
          ]
        }
      },
      "description": "Dynamic gateway self-service summary rollup for one toolkit (MCPG-1130)."
    }
  }
}