openapi: 3.2.0 info: title: MCP Gateway App Instructions API description: API for MCP Gateway operations version: v1 servers: - url: https://dev.stormmcp.ai/ tags: - name: AppInstructions paths: /api/v1/admin/AppInstructions: get: tags: - AppInstructions summary: Gets the servers that have app instructions configured for the current tenant. responses: '200': description: OK content: text/plain: schema: $ref: '#/components/schemas/ConfiguredAppInstructionsResponse' application/json: schema: $ref: '#/components/schemas/ConfiguredAppInstructionsResponse' text/json: schema: $ref: '#/components/schemas/ConfiguredAppInstructionsResponse' text/csv: schema: $ref: '#/components/schemas/ConfiguredAppInstructionsResponse' application/csv: schema: $ref: '#/components/schemas/ConfiguredAppInstructionsResponse' '401': description: Unauthorized content: text/plain: schema: $ref: '#/components/schemas/ProblemDetails' application/json: schema: $ref: '#/components/schemas/ProblemDetails' text/json: schema: $ref: '#/components/schemas/ProblemDetails' text/csv: schema: $ref: '#/components/schemas/ProblemDetails' application/csv: schema: $ref: '#/components/schemas/ProblemDetails' '403': description: Forbidden content: text/plain: schema: $ref: '#/components/schemas/ProblemDetails' application/json: schema: $ref: '#/components/schemas/ProblemDetails' text/json: schema: $ref: '#/components/schemas/ProblemDetails' text/csv: schema: $ref: '#/components/schemas/ProblemDetails' application/csv: schema: $ref: '#/components/schemas/ProblemDetails' operationId: getApiV1AdminAppInstructions x-operation-id-source: derived /api/v1/admin/AppInstructions/{serverId}: get: tags: - AppInstructions summary: Gets the app instructions configured for a single server parameters: - name: serverId in: path description: The unified server identifier. required: true schema: type: string format: uuid responses: '200': description: OK content: text/plain: schema: $ref: '#/components/schemas/AppInstructionResponse' application/json: schema: $ref: '#/components/schemas/AppInstructionResponse' text/json: schema: $ref: '#/components/schemas/AppInstructionResponse' text/csv: schema: $ref: '#/components/schemas/AppInstructionResponse' application/csv: schema: $ref: '#/components/schemas/AppInstructionResponse' '401': description: Unauthorized content: text/plain: schema: $ref: '#/components/schemas/ProblemDetails' application/json: schema: $ref: '#/components/schemas/ProblemDetails' text/json: schema: $ref: '#/components/schemas/ProblemDetails' text/csv: schema: $ref: '#/components/schemas/ProblemDetails' application/csv: schema: $ref: '#/components/schemas/ProblemDetails' '403': description: Forbidden content: text/plain: schema: $ref: '#/components/schemas/ProblemDetails' application/json: schema: $ref: '#/components/schemas/ProblemDetails' text/json: schema: $ref: '#/components/schemas/ProblemDetails' text/csv: schema: $ref: '#/components/schemas/ProblemDetails' application/csv: schema: $ref: '#/components/schemas/ProblemDetails' '404': description: Not Found content: text/plain: schema: $ref: '#/components/schemas/ProblemDetails' application/json: schema: $ref: '#/components/schemas/ProblemDetails' text/json: schema: $ref: '#/components/schemas/ProblemDetails' text/csv: schema: $ref: '#/components/schemas/ProblemDetails' application/csv: schema: $ref: '#/components/schemas/ProblemDetails' operationId: getApiV1AdminAppInstructionsByServerId x-operation-id-source: derived put: tags: - AppInstructions summary: Creates or replaces the app instructions for a server. description: 'The `400` is produced by MVC''s automatic model-state filter, which `[ApiController]` runs before this action and the host does not suppress — so a blank `Instructions` or an over-length description is answered with `ValidationProblemDetails` and its field-level `errors` dictionary, which is more useful to a form than a single error code would be. Do not add a `ModelState.IsValid` check here; it can never be false.' parameters: - name: serverId in: path description: The unified server identifier. required: true schema: type: string format: uuid requestBody: description: The cancellation token. content: application/json: schema: $ref: '#/components/schemas/SaveAppInstructionRequest' text/json: schema: $ref: '#/components/schemas/SaveAppInstructionRequest' application/*+json: schema: $ref: '#/components/schemas/SaveAppInstructionRequest' required: true responses: '200': description: OK content: text/plain: schema: $ref: '#/components/schemas/AppInstructionResponse' application/json: schema: $ref: '#/components/schemas/AppInstructionResponse' text/json: schema: $ref: '#/components/schemas/AppInstructionResponse' text/csv: schema: $ref: '#/components/schemas/AppInstructionResponse' application/csv: schema: $ref: '#/components/schemas/AppInstructionResponse' '400': description: Bad Request content: text/plain: schema: $ref: '#/components/schemas/ProblemDetails' application/json: schema: $ref: '#/components/schemas/ProblemDetails' text/json: schema: $ref: '#/components/schemas/ProblemDetails' text/csv: schema: $ref: '#/components/schemas/ProblemDetails' application/csv: schema: $ref: '#/components/schemas/ProblemDetails' '401': description: Unauthorized content: text/plain: schema: $ref: '#/components/schemas/ProblemDetails' application/json: schema: $ref: '#/components/schemas/ProblemDetails' text/json: schema: $ref: '#/components/schemas/ProblemDetails' text/csv: schema: $ref: '#/components/schemas/ProblemDetails' application/csv: schema: $ref: '#/components/schemas/ProblemDetails' '403': description: Forbidden content: text/plain: schema: $ref: '#/components/schemas/ProblemDetails' application/json: schema: $ref: '#/components/schemas/ProblemDetails' text/json: schema: $ref: '#/components/schemas/ProblemDetails' text/csv: schema: $ref: '#/components/schemas/ProblemDetails' application/csv: schema: $ref: '#/components/schemas/ProblemDetails' '404': description: Not Found content: text/plain: schema: $ref: '#/components/schemas/ProblemDetails' application/json: schema: $ref: '#/components/schemas/ProblemDetails' text/json: schema: $ref: '#/components/schemas/ProblemDetails' text/csv: schema: $ref: '#/components/schemas/ProblemDetails' application/csv: schema: $ref: '#/components/schemas/ProblemDetails' operationId: putApiV1AdminAppInstructionsByServerId x-operation-id-source: derived delete: tags: - AppInstructions summary: Removes the app instructions for a server parameters: - name: serverId in: path description: The unified server identifier. required: true schema: type: string format: uuid responses: '204': description: No Content '401': description: Unauthorized content: text/plain: schema: $ref: '#/components/schemas/ProblemDetails' application/json: schema: $ref: '#/components/schemas/ProblemDetails' text/json: schema: $ref: '#/components/schemas/ProblemDetails' text/csv: schema: $ref: '#/components/schemas/ProblemDetails' application/csv: schema: $ref: '#/components/schemas/ProblemDetails' '403': description: Forbidden content: text/plain: schema: $ref: '#/components/schemas/ProblemDetails' application/json: schema: $ref: '#/components/schemas/ProblemDetails' text/json: schema: $ref: '#/components/schemas/ProblemDetails' text/csv: schema: $ref: '#/components/schemas/ProblemDetails' application/csv: schema: $ref: '#/components/schemas/ProblemDetails' '404': description: Not Found content: text/plain: schema: $ref: '#/components/schemas/ProblemDetails' application/json: schema: $ref: '#/components/schemas/ProblemDetails' text/json: schema: $ref: '#/components/schemas/ProblemDetails' text/csv: schema: $ref: '#/components/schemas/ProblemDetails' application/csv: schema: $ref: '#/components/schemas/ProblemDetails' operationId: deleteApiV1AdminAppInstructionsByServerId x-operation-id-source: derived components: schemas: ProblemDetails: type: object properties: type: type: - 'null' - string title: type: - 'null' - string status: pattern: ^-?(?:0|[1-9]\d*)$ type: - 'null' - integer - string format: int32 detail: type: - 'null' - string instance: type: - 'null' - string AppInstructionResponse: type: object properties: serverId: type: string description: Gets or sets the unified server identifier these instructions belong to. format: uuid serverName: type: string description: 'Gets or sets the display name of the server, resolved from the catalog or the tenant''s custom servers. Included so the admin UI can title the page without a second lookup.' instructions: type: string description: Gets or sets the markdown guidance returned by the synthesized instructions tool. instructionsToolDescription: type: - 'null' - string description: 'Gets or sets the description advertised to LLMs for this app''s instructions tool. Null means the generated default naming the app is used.' toolName: type: string description: 'Gets or sets the name of the native tool this configuration synthesizes, for example `jira__get_app_instructions`. Advisory only — the effective name is allocated per session so it can be disambiguated against other apps and deployments present there.' createdAt: type: string description: Gets or sets the creation timestamp. format: date-time updatedAt: type: string description: Gets or sets the last update timestamp. format: date-time description: The tenant-wide instructions configured for a single MCP server (MCPG-1296). ConfiguredAppInstructionsResponse: type: object properties: serverIds: type: array items: type: string format: uuid description: 'Gets or sets the server identifiers that have app instructions configured for this tenant. A server absent from this list shows "Configure"; a server present shows "Edit".' description: 'The batched existence check backing the Server Management grid''s Configure/Edit indicator (MCPG-1296): one call resolves the state of every visible row, rather than one call per row.' SaveAppInstructionRequest: required: - instructions type: object properties: instructions: type: string description: " Gets or sets the markdown guidance returned by the synthesized instructions tool.\n Deliberately uncapped: MCPG-1296 requires bodies longer than 8,192 characters to round-trip\nwithout validation failure or truncation. Content is still required — clearing instructions\nis an explicit DELETE, not an empty save, so the two intents stay distinguishable." instructionsToolDescription: maxLength: 500 type: - 'null' - string description: " Gets or sets the description advertised to LLMs for this app's instructions tool.\n An explicit null clears any stored description and restores the generated default\nnaming the app; the field is always applied on save, so an omitted value is treated as\nnull rather than \"leave unchanged\"." description: Request body for creating or replacing a server's tenant-wide app instructions (MCPG-1296).