{
  "components": {
    "headers": {
      "Cache-Control": {
        "description": "Always no-store.",
        "schema": {
          "type": "string"
        }
      },
      "ETag": {
        "description": "Quoted version of the returned resource, when it has one; send it in If-Match.",
        "schema": {
          "type": "string"
        }
      },
      "Retry-After": {
        "description": "Seconds to wait before retrying.",
        "schema": {
          "type": "integer"
        }
      },
      "X-Request-ID": {
        "description": "Request correlation id (also in the body).",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Invalid request: `error.fields` names the offending paths, or for analytics reports maps each offending query parameter to the reason (invalid_request, idempotency_key_required, invalid_configuration, ...).",
        "headers": {
          "X-Request-ID": {
            "$ref": "#/components/headers/X-Request-ID"
          }
        }
      },
      "BodyTimeout": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Timed out reading the request body (10 seconds).",
        "headers": {
          "X-Request-ID": {
            "$ref": "#/components/headers/X-Request-ID"
          }
        }
      },
      "BodyTooLarge": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Request body exceeds 1 MiB (body_too_large), or an OpenAPI document exceeds its limit (spec_too_large).",
        "headers": {
          "X-Request-ID": {
            "$ref": "#/components/headers/X-Request-ID"
          }
        }
      },
      "Busy": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Management concurrency limit reached (management_busy) or too many reports in progress (report_busy). Retry after Retry-After seconds.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          },
          "X-Request-ID": {
            "$ref": "#/components/headers/X-Request-ID"
          }
        }
      },
      "Conflict": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Name, state, dependency or idempotency conflict, or a list changed during pagination (collection_changed).",
        "headers": {
          "X-Request-ID": {
            "$ref": "#/components/headers/X-Request-ID"
          }
        }
      },
      "Forbidden": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Missing scope (insufficient_scope with required_scopes), management disabled for the tenant, wrong tenant, or an MCP provided by Quilr.",
        "headers": {
          "X-Request-ID": {
            "$ref": "#/components/headers/X-Request-ID"
          }
        }
      },
      "Gone": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "The connect link expired, or an OpenAPI preview token expired (preview_expired).",
        "headers": {
          "X-Request-ID": {
            "$ref": "#/components/headers/X-Request-ID"
          }
        }
      },
      "NotFound": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Resource not found (MCPs of other tenants included), or management is not available on this deployment.",
        "headers": {
          "X-Request-ID": {
            "$ref": "#/components/headers/X-Request-ID"
          }
        }
      },
      "PreconditionRequired": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "If-Match is required.",
        "headers": {
          "X-Request-ID": {
            "$ref": "#/components/headers/X-Request-ID"
          }
        }
      },
      "Unauthorized": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Missing, invalid, expired or revoked credential.",
        "headers": {
          "X-Request-ID": {
            "$ref": "#/components/headers/X-Request-ID"
          }
        }
      },
      "Unavailable": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Storage or analytics temporarily unavailable, a query timed out, or an operation is pending (retry the same Idempotency-Key). On deployments without an analytics store, analytics reports always answer data_unavailable: do not retry those.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          },
          "X-Request-ID": {
            "$ref": "#/components/headers/X-Request-ID"
          }
        }
      },
      "Unprocessable": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "More install input is required, a report would produce too many rows, or the selected OpenAPI operations produce too many tool definitions (tools_too_large).",
        "headers": {
          "X-Request-ID": {
            "$ref": "#/components/headers/X-Request-ID"
          }
        }
      },
      "UpstreamUnavailable": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "The upstream MCP server or OAuth provider could not be reached or rejected the request.",
        "headers": {
          "X-Request-ID": {
            "$ref": "#/components/headers/X-Request-ID"
          }
        }
      },
      "VersionConflict": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "If-Match does not match the current version; read again and retry.",
        "headers": {
          "X-Request-ID": {
            "$ref": "#/components/headers/X-Request-ID"
          }
        }
      }
    },
    "schemas": {
      "AccessControlSettings": {
        "additionalProperties": false,
        "description": "Which agents, smart groups and users may use this MCP. Users are checked in this order, first match wins: denied_users (blocked), allowed_users (allowed, even when a group of theirs is denied), denied_smart_groups (blocked), then allowed_smart_groups (when not empty, users in none of them are blocked). Otherwise allowed.",
        "properties": {
          "allowed_agents": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "allowed_smart_groups": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "allowed_users": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "denied_smart_groups": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "denied_users": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "Agent": {
        "additionalProperties": true,
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "custom": {
            "type": "boolean"
          },
          "display_name": {
            "type": "string"
          },
          "keyword": {
            "type": "string"
          }
        },
        "required": [
          "keyword",
          "display_name",
          "custom"
        ],
        "type": "object"
      },
      "AgentCreate": {
        "additionalProperties": false,
        "properties": {
          "display_name": {
            "maxLength": 200,
            "minLength": 1,
            "type": "string"
          },
          "keyword": {
            "description": "Matched against the client User-Agent (case-insensitive); stored lowercase.",
            "maxLength": 50,
            "minLength": 1,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9-]*$",
            "type": "string"
          }
        },
        "required": [
          "keyword",
          "display_name"
        ],
        "type": "object"
      },
      "AgentDeleted": {
        "additionalProperties": true,
        "properties": {
          "agent": {
            "additionalProperties": true,
            "properties": {
              "deleted": {
                "type": "boolean"
              },
              "keyword": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "agent",
          "request_id"
        ],
        "type": "object"
      },
      "AgentList": {
        "additionalProperties": true,
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/Agent"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "items",
          "next_cursor",
          "request_id"
        ],
        "type": "object"
      },
      "AgentResponse": {
        "additionalProperties": true,
        "properties": {
          "agent": {
            "additionalProperties": true,
            "properties": {
              "custom": {
                "type": "boolean"
              },
              "display_name": {
                "type": "string"
              },
              "keyword": {
                "type": "string"
              },
              "mcps": {
                "items": {
                  "additionalProperties": true,
                  "properties": {
                    "enabled": {
                      "type": "boolean"
                    },
                    "mcp_id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "agent",
          "request_id"
        ],
        "type": "object"
      },
      "ApiAccessDecision": {
        "additionalProperties": true,
        "properties": {
          "api_revision": {
            "type": "integer"
          },
          "decision": {
            "additionalProperties": true,
            "properties": {
              "allowed": {
                "type": "boolean"
              },
              "index": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "list": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "operation": {
                "type": [
                  "object",
                  "null"
                ]
              },
              "reason": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "allowed"
            ],
            "type": "object"
          },
          "mcp_id": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "decision",
          "request_id"
        ],
        "type": "object"
      },
      "ApiAccessPresets": {
        "additionalProperties": true,
        "properties": {
          "presets": {
            "additionalProperties": {
              "type": "object"
            },
            "description": "Access rules keyed by preset name.",
            "type": "object"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "presets",
          "request_id"
        ],
        "type": "object"
      },
      "ApiAccessRules": {
        "additionalProperties": false,
        "description": "Deny wins; a nonempty allow list must match; no rules allows everything.",
        "properties": {
          "allow": {
            "items": {
              "additionalProperties": false,
              "description": "One access rule; every field it sets must match.",
              "properties": {
                "keywords": {
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 32,
                  "type": "array"
                },
                "methods": {
                  "description": "HTTP methods, for example GET.",
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "path": {
                  "description": "Path glob, for example /invoices/*.",
                  "type": "string"
                },
                "tags": {
                  "description": "OpenAPI tags.",
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "type": "object"
            },
            "maxItems": 64,
            "type": "array"
          },
          "deny": {
            "items": {
              "additionalProperties": false,
              "description": "One access rule; every field it sets must match.",
              "properties": {
                "keywords": {
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 32,
                  "type": "array"
                },
                "methods": {
                  "description": "HTTP methods, for example GET.",
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "path": {
                  "description": "Path glob, for example /invoices/*.",
                  "type": "string"
                },
                "tags": {
                  "description": "OpenAPI tags.",
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "type": "object"
            },
            "maxItems": 64,
            "type": "array"
          }
        },
        "type": "object"
      },
      "ApiAccessTest": {
        "additionalProperties": false,
        "properties": {
          "method": {
            "description": "HTTP method.",
            "maxLength": 16,
            "minLength": 1,
            "type": "string"
          },
          "path": {
            "description": "Request path, for example /invoices/42.",
            "maxLength": 4096,
            "minLength": 1,
            "pattern": "^/",
            "type": "string"
          },
          "tags": {
            "description": "OpenAPI tags to test with; by default the matching operation's tags.",
            "items": {
              "type": "string"
            },
            "maxItems": 64,
            "type": "array"
          }
        },
        "required": [
          "method",
          "path"
        ],
        "type": "object"
      },
      "ApiConfig": {
        "additionalProperties": true,
        "properties": {
          "api_config": {
            "additionalProperties": true,
            "properties": {
              "access": {
                "type": "object"
              },
              "api_revision": {
                "type": "integer"
              },
              "base_url": {
                "description": "Origin and path; query string and user info removed.",
                "type": "string"
              },
              "base_url_has_credentials": {
                "type": "boolean"
              },
              "docs_text": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "extra_header_names": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "extra_query_param_names": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "max_response_bytes": {
                "type": "integer"
              },
              "mcp_id": {
                "type": "string"
              },
              "mode": {
                "enum": [
                  "openapi",
                  "generic"
                ],
                "type": "string"
              },
              "openapi": {
                "anyOf": [
                  {
                    "additionalProperties": true,
                    "properties": {
                      "enable_generic_fallback": {
                        "type": "boolean"
                      },
                      "info": {
                        "type": [
                          "object",
                          "null"
                        ]
                      },
                      "operations": {
                        "description": "With include_operations=true.",
                        "items": {
                          "additionalProperties": true,
                          "properties": {
                            "key": {
                              "type": "string"
                            },
                            "method": {
                              "type": "string"
                            },
                            "operation_id": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "path": {
                              "type": "string"
                            },
                            "selected": {
                              "type": "boolean"
                            },
                            "selection_reason": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "summary": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "supported": {
                              "type": "boolean"
                            },
                            "tags": {
                              "items": {
                                "type": "string"
                              },
                              "type": "array"
                            },
                            "tool_name": {
                              "type": [
                                "string",
                                "null"
                              ]
                            },
                            "warnings": {
                              "items": {},
                              "type": "array"
                            }
                          },
                          "required": [
                            "key",
                            "method",
                            "path"
                          ],
                          "type": "object"
                        },
                        "type": "array"
                      },
                      "overrides": {
                        "additionalProperties": {
                          "additionalProperties": true,
                          "properties": {
                            "description": {
                              "type": "string"
                            },
                            "enabled": {
                              "type": [
                                "boolean",
                                "null"
                              ]
                            },
                            "fixed_param_names": {
                              "description": "Names only; values are never returned.",
                              "items": {
                                "type": "string"
                              },
                              "type": "array"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "type": "object"
                        },
                        "type": "object"
                      },
                      "source_url": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "source_url_has_credentials": {
                        "type": "boolean"
                      },
                      "totals": {
                        "additionalProperties": true,
                        "properties": {
                          "operations": {
                            "type": "integer"
                          },
                          "selected": {
                            "type": "integer"
                          },
                          "supported": {
                            "type": "integer"
                          }
                        },
                        "type": "object"
                      }
                    },
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "remote_connector": {
                "type": [
                  "object",
                  "null"
                ]
              },
              "timeout_s": {
                "type": "number"
              },
              "tools": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "updated_at": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "mcp_id",
              "mode"
            ],
            "type": "object"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "tool_diff": {
            "description": "Tools `added`, `removed` and `changed` by the write.",
            "type": [
              "object",
              "null"
            ]
          },
          "version": {
            "description": "Opaque resource version. Send its quoted value in If-Match.",
            "type": "string"
          }
        },
        "required": [
          "api_config",
          "version",
          "request_id"
        ],
        "type": "object"
      },
      "ApiConfigPatch": {
        "additionalProperties": false,
        "description": "Fields to change; everything else keeps its saved value, including values this API never returns (fixed parameter values, URL query strings). `openapi: null` switches to one generic request tool.",
        "minProperties": 1,
        "properties": {
          "access": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ApiAccessRules"
              },
              {
                "type": "null"
              }
            ]
          },
          "base_url": {
            "description": "Base URL requests are sent to. Needs credentials:write: the saved credentials are sent there.",
            "format": "uri",
            "maxLength": 2048,
            "type": "string"
          },
          "docs_text": {
            "maxLength": 1048576,
            "type": [
              "string",
              "null"
            ]
          },
          "max_response_bytes": {
            "exclusiveMinimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "openapi": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ApiOpenApiPatch"
              },
              {
                "type": "null"
              }
            ]
          },
          "remote_connector_id": {
            "maxLength": 128,
            "type": [
              "string",
              "null"
            ]
          },
          "timeout_s": {
            "exclusiveMinimum": 0,
            "type": [
              "number",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "ApiMcpCreate": {
        "additionalProperties": false,
        "description": "A REST API exposed as MCP tools. With `openapi`, tools come from the OpenAPI operations; without it, one generic request tool is exposed.",
        "properties": {
          "access": {
            "$ref": "#/components/schemas/ApiAccessRules"
          },
          "auth_token": {
            "description": "Static API key or token sent upstream.",
            "maxLength": 8192,
            "minLength": 1,
            "type": "string",
            "writeOnly": true
          },
          "base_url": {
            "description": "Base URL requests are sent to.",
            "format": "uri",
            "maxLength": 2048,
            "type": "string"
          },
          "description": {
            "maxLength": 8000,
            "type": [
              "string",
              "null"
            ]
          },
          "docs_text": {
            "description": "Free-form API documentation for generic mode.",
            "maxLength": 1048576,
            "type": [
              "string",
              "null"
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "max_response_bytes": {
            "type": [
              "integer",
              "null"
            ]
          },
          "name": {
            "maxLength": 256,
            "minLength": 1,
            "type": "string"
          },
          "openapi": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ApiOpenApiSelection"
              },
              {
                "type": "null"
              }
            ]
          },
          "remote_connector_id": {
            "maxLength": 128,
            "type": [
              "string",
              "null"
            ]
          },
          "settings": {
            "$ref": "#/components/schemas/McpSettingsPatch"
          },
          "slug": {
            "maxLength": 128,
            "type": "string"
          },
          "timeout_s": {
            "description": "Upstream request timeout, seconds.",
            "type": [
              "number",
              "null"
            ]
          },
          "upstream_auth_extra_headers": {
            "additionalProperties": {
              "maxLength": 8192,
              "type": "string"
            },
            "description": "Extra headers sent upstream on every call.",
            "maxProperties": 64,
            "type": "object",
            "writeOnly": true
          },
          "upstream_auth_extra_query_params": {
            "additionalProperties": {
              "maxLength": 8192,
              "type": "string"
            },
            "description": "Extra query parameters sent upstream.",
            "maxProperties": 64,
            "type": "object",
            "writeOnly": true
          },
          "upstream_auth_header_name": {
            "maxLength": 128,
            "type": "string"
          },
          "upstream_auth_mode": {
            "description": "Credentials set through this API are always shared by all users of the tenant.",
            "enum": [
              "admin_shared"
            ],
            "type": "string"
          },
          "upstream_auth_query_param": {
            "maxLength": 128,
            "type": "string"
          },
          "upstream_auth_scheme": {
            "description": "Authorization scheme for bearer (default Bearer).",
            "maxLength": 128,
            "type": "string"
          },
          "upstream_auth_type": {
            "description": "How the token is sent: bearer (default), header or query.",
            "enum": [
              "bearer",
              "header",
              "query"
            ],
            "type": "string"
          }
        },
        "required": [
          "name",
          "base_url"
        ],
        "type": "object"
      },
      "ApiOpenApiPatch": {
        "additionalProperties": false,
        "description": "Send at most one new document source; without one the saved document is kept.",
        "properties": {
          "enable_generic_fallback": {
            "type": "boolean"
          },
          "overrides": {
            "additionalProperties": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/ApiOperationOverride"
                },
                {
                  "type": "null"
                }
              ]
            },
            "description": "Keyed by operation (`GET /pets`). An object merges into the saved override (a sent `fixed_params` replaces the saved map); null removes the override.",
            "maxProperties": 5000,
            "type": "object"
          },
          "preview_token": {
            "description": "A new document from POST /mcps/api:preview.",
            "maxLength": 128,
            "type": "string"
          },
          "source_url": {
            "description": "A new document URL, fetched now.",
            "format": "uri",
            "maxLength": 4096,
            "type": "string"
          },
          "spec_base64": {
            "description": "A new document, base64 encoded.",
            "type": "string"
          },
          "spec_text": {
            "description": "A new document as JSON or YAML text.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ApiOpenApiSelection": {
        "additionalProperties": false,
        "description": "OpenAPI mode: send one spec source.",
        "properties": {
          "enable_generic_fallback": {
            "default": false,
            "description": "Also expose a generic request tool.",
            "type": "boolean"
          },
          "overrides": {
            "additionalProperties": {
              "$ref": "#/components/schemas/ApiOperationOverride"
            },
            "maxProperties": 5000,
            "type": "object"
          },
          "preview_token": {
            "description": "Token from POST /mcps/api:preview (preferred: no re-fetch).",
            "maxLength": 128,
            "type": "string"
          },
          "source_url": {
            "description": "URL of the OpenAPI document, fetched now.",
            "format": "uri",
            "maxLength": 4096,
            "type": "string"
          },
          "spec_base64": {
            "description": "OpenAPI document, base64 encoded.",
            "type": "string"
          },
          "spec_text": {
            "description": "OpenAPI document as JSON or YAML text.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ApiOperationOverride": {
        "additionalProperties": false,
        "description": "Per-operation override, keyed by OpenAPI operation id.",
        "properties": {
          "description": {
            "maxLength": 8000,
            "type": "string"
          },
          "enabled": {
            "description": "Force the operation on or off; null lets the access rules decide.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "fixed_params": {
            "description": "Parameter values always sent upstream (hidden from the model). Nonempty values need credentials:write.",
            "type": "object"
          },
          "name": {
            "description": "Tool name to publish.",
            "maxLength": 128,
            "type": "string"
          }
        },
        "type": "object"
      },
      "ApiPreview": {
        "additionalProperties": false,
        "description": "Send one spec source: preview_token, source_url, spec_text or spec_base64.",
        "properties": {
          "access": {
            "$ref": "#/components/schemas/ApiAccessRules"
          },
          "fetch_headers": {
            "additionalProperties": {
              "maxLength": 8192,
              "type": "string"
            },
            "description": "Headers for downloading a protected spec; used once, never stored.",
            "maxProperties": 64,
            "type": "object",
            "writeOnly": true
          },
          "overrides": {
            "additionalProperties": {
              "$ref": "#/components/schemas/ApiOperationOverride"
            },
            "type": "object"
          },
          "preview_token": {
            "description": "Token from POST /mcps/api:preview (preferred: no re-fetch).",
            "maxLength": 128,
            "type": "string"
          },
          "remote_connector_id": {
            "maxLength": 128,
            "type": "string"
          },
          "source_url": {
            "description": "URL of the OpenAPI document, fetched now.",
            "format": "uri",
            "maxLength": 4096,
            "type": "string"
          },
          "spec_base64": {
            "description": "OpenAPI document, base64 encoded.",
            "type": "string"
          },
          "spec_text": {
            "description": "OpenAPI document as JSON or YAML text.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ApiPreviewResult": {
        "additionalProperties": true,
        "properties": {
          "preview": {
            "additionalProperties": true,
            "properties": {
              "info": {
                "type": "object"
              },
              "operations": {
                "type": "array"
              },
              "preview_expires_in_seconds": {
                "type": "integer"
              },
              "preview_token": {
                "type": "string"
              },
              "servers": {
                "type": "array"
              },
              "totals": {
                "type": "object"
              },
              "warnings": {
                "type": "array"
              }
            },
            "type": "object"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "preview",
          "request_id"
        ],
        "type": "object"
      },
      "ApiResync": {
        "additionalProperties": false,
        "properties": {
          "fetch_headers": {
            "additionalProperties": {
              "maxLength": 8192,
              "type": "string"
            },
            "description": "Headers for downloading a protected document; used once, never stored. Needs credentials:write.",
            "maxProperties": 64,
            "type": "object",
            "writeOnly": true
          }
        },
        "type": "object"
      },
      "ApiResyncResult": {
        "additionalProperties": true,
        "properties": {
          "api_revision": {
            "type": "integer"
          },
          "applied": {
            "type": "boolean"
          },
          "error": {
            "description": "Dry run only: why applying would fail.",
            "type": [
              "object",
              "null"
            ]
          },
          "mcp_id": {
            "type": "string"
          },
          "new_operations": {
            "description": "Added upstream; saved turned off.",
            "items": {
              "additionalProperties": true,
              "properties": {
                "key": {
                  "type": "string"
                },
                "method": {
                  "type": "string"
                },
                "operation_id": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "path": {
                  "type": "string"
                },
                "selected": {
                  "type": "boolean"
                },
                "selection_reason": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "summary": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "supported": {
                  "type": "boolean"
                },
                "tags": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "tool_name": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "warnings": {
                  "items": {},
                  "type": "array"
                }
              },
              "required": [
                "key",
                "method",
                "path"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "removed_operations": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "tool_diff": {
            "description": "Tools `added`, `removed` and `changed` by the write.",
            "type": [
              "object",
              "null"
            ]
          },
          "totals": {
            "additionalProperties": true,
            "properties": {
              "operations": {
                "type": "integer"
              },
              "selected": {
                "type": "integer"
              },
              "supported": {
                "type": "integer"
              }
            },
            "type": "object"
          },
          "version": {
            "description": "Opaque resource version. Send its quoted value in If-Match.",
            "type": "string"
          },
          "warnings": {
            "items": {},
            "type": "array"
          }
        },
        "required": [
          "applied",
          "request_id"
        ],
        "type": "object"
      },
      "ApiRuleTest": {
        "additionalProperties": false,
        "properties": {
          "access": {
            "$ref": "#/components/schemas/ApiAccessRules"
          },
          "method": {
            "description": "HTTP method.",
            "maxLength": 16,
            "minLength": 1,
            "type": "string"
          },
          "path": {
            "description": "Request path, for example /invoices/42.",
            "maxLength": 4096,
            "minLength": 1,
            "pattern": "^/",
            "type": "string"
          },
          "tags": {
            "description": "OpenAPI tags to test with; by default the matching operation's tags.",
            "items": {
              "type": "string"
            },
            "maxItems": 64,
            "type": "array"
          }
        },
        "required": [
          "method",
          "path"
        ],
        "type": "object"
      },
      "ApiSelectionPreview": {
        "additionalProperties": false,
        "description": "Candidate rules and override changes, applied like the PATCH would. Omitted fields use the saved values.",
        "properties": {
          "access": {
            "$ref": "#/components/schemas/ApiAccessRules"
          },
          "overrides": {
            "additionalProperties": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/ApiOperationOverride"
                },
                {
                  "type": "null"
                }
              ]
            },
            "description": "Keyed by operation (`GET /pets`). An object merges into the saved override (a sent `fixed_params` replaces the saved map); null removes the override.",
            "maxProperties": 5000,
            "type": "object"
          }
        },
        "type": "object"
      },
      "ApiSelectionPreviewResult": {
        "additionalProperties": true,
        "properties": {
          "api_revision": {
            "type": "integer"
          },
          "mcp_id": {
            "type": "string"
          },
          "operations": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "key": {
                  "type": "string"
                },
                "method": {
                  "type": "string"
                },
                "operation_id": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "path": {
                  "type": "string"
                },
                "selected": {
                  "type": "boolean"
                },
                "selection_reason": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "summary": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "supported": {
                  "type": "boolean"
                },
                "tags": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "tool_name": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "warnings": {
                  "items": {},
                  "type": "array"
                }
              },
              "required": [
                "key",
                "method",
                "path"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "totals": {
            "additionalProperties": true,
            "properties": {
              "operations": {
                "type": "integer"
              },
              "selected": {
                "type": "integer"
              },
              "supported": {
                "type": "integer"
              }
            },
            "type": "object"
          }
        },
        "required": [
          "operations",
          "totals",
          "request_id"
        ],
        "type": "object"
      },
      "AuditEvent": {
        "additionalProperties": true,
        "description": "One audit event. Never includes before or after values.",
        "properties": {
          "action": {
            "type": "string"
          },
          "actor_email": {
            "type": [
              "string",
              "null"
            ]
          },
          "actor_role": {
            "type": [
              "string",
              "null"
            ]
          },
          "changed_fields": {
            "description": "Names of the fields or sections changed, when recorded.",
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "event_id": {
            "type": "string"
          },
          "management_key_id": {
            "description": "Key used, for via management_api.",
            "type": [
              "string",
              "null"
            ]
          },
          "operation_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "resource_id": {
            "type": "string"
          },
          "resource_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "resource_type": {
            "type": "string"
          },
          "result": {
            "type": [
              "string",
              "null"
            ]
          },
          "via": {
            "enum": [
              "ui",
              "management_api"
            ],
            "type": "string"
          }
        },
        "required": [
          "event_id",
          "created_at",
          "via",
          "action",
          "resource_type",
          "resource_id"
        ],
        "type": "object"
      },
      "AuditList": {
        "additionalProperties": true,
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/AuditEvent"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "items",
          "next_cursor",
          "request_id"
        ],
        "type": "object"
      },
      "Capabilities": {
        "additionalProperties": true,
        "properties": {
          "analytics": {
            "type": "object"
          },
          "api_version": {
            "type": "string"
          },
          "auth_types": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "caller": {
            "additionalProperties": true,
            "properties": {
              "key_id": {
                "type": "string"
              },
              "scopes": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            },
            "required": [
              "key_id",
              "scopes"
            ],
            "type": "object"
          },
          "connection_states": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "limits": {
            "type": "object"
          },
          "mcp_create": {
            "type": "object"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "scopes": {
            "description": "Every scope a key can carry.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "settings_sections": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "api_version",
          "tenant_id",
          "scopes",
          "caller",
          "request_id"
        ],
        "type": "object"
      },
      "CatalogEntry": {
        "additionalProperties": true,
        "properties": {
          "auth_type": {
            "type": "string"
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "custom_oauth_credentials_required": {
            "type": "boolean"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "icon": {
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "type": "string"
          },
          "install_requirements": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "installed": {
            "type": "boolean"
          },
          "is_custom": {
            "type": "boolean"
          },
          "mcp_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "mcp_status": {
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": "string"
          },
          "oauth_with_login": {
            "type": "boolean"
          },
          "requires_configuration": {
            "type": "boolean"
          },
          "transport": {
            "type": [
              "string",
              "null"
            ]
          },
          "upstream_auth": {
            "type": [
              "object",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "installed"
        ],
        "type": "object"
      },
      "CatalogEntryResponse": {
        "additionalProperties": true,
        "properties": {
          "catalog_entry": {
            "$ref": "#/components/schemas/CatalogEntry"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "catalog_entry",
          "request_id"
        ],
        "type": "object"
      },
      "CatalogInstall": {
        "additionalProperties": false,
        "description": "Install inputs. `GET /catalog/{catalog_id}` lists `install_requirements`; missing required values answer 422 `install_input_required` with `missing_fields`.",
        "properties": {
          "auth_token": {
            "description": "Static API key or token sent upstream.",
            "maxLength": 8192,
            "minLength": 1,
            "type": "string",
            "writeOnly": true
          },
          "oauth_callback_mode": {
            "maxLength": 128,
            "type": "string"
          },
          "oauth_client_id": {
            "description": "Your OAuth client id, for catalog MCPs that need one.",
            "maxLength": 8192,
            "minLength": 1,
            "type": "string",
            "writeOnly": true
          },
          "oauth_client_secret": {
            "description": "Your OAuth client secret; \"-\" for a public client (no secret).",
            "maxLength": 8192,
            "minLength": 1,
            "type": "string",
            "writeOnly": true
          },
          "transport_values": {
            "additionalProperties": {
              "maxLength": 8192,
              "type": "string"
            },
            "description": "Values for placeholders in the catalog URL template.",
            "maxProperties": 64,
            "type": "object",
            "writeOnly": true
          },
          "upstream_auth_extra_headers": {
            "additionalProperties": {
              "maxLength": 8192,
              "type": "string"
            },
            "description": "Extra headers sent upstream on every call.",
            "maxProperties": 64,
            "type": "object",
            "writeOnly": true
          },
          "upstream_auth_extra_query_params": {
            "additionalProperties": {
              "maxLength": 8192,
              "type": "string"
            },
            "description": "Extra query parameters sent upstream.",
            "maxProperties": 64,
            "type": "object",
            "writeOnly": true
          },
          "upstream_auth_header_name": {
            "maxLength": 128,
            "type": "string"
          },
          "upstream_auth_mode": {
            "description": "Credentials set through this API are always shared by all users of the tenant.",
            "enum": [
              "admin_shared"
            ],
            "type": "string"
          },
          "upstream_auth_query_param": {
            "maxLength": 128,
            "type": "string"
          },
          "upstream_auth_scheme": {
            "description": "Authorization scheme for bearer (default Bearer).",
            "maxLength": 128,
            "type": "string"
          },
          "upstream_auth_type": {
            "description": "How the token is sent: bearer (default), header or query.",
            "enum": [
              "bearer",
              "header",
              "query"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "CatalogList": {
        "additionalProperties": true,
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/CatalogEntry"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "items",
          "next_cursor",
          "request_id"
        ],
        "type": "object"
      },
      "ClientSetup": {
        "additionalProperties": true,
        "properties": {
          "allowed_agents": {
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "api_token": {
            "description": "How to send an MCP API token, when the MCP accepts them.",
            "type": [
              "object",
              "null"
            ]
          },
          "auth_type": {
            "type": "string"
          },
          "direct": {
            "additionalProperties": true,
            "properties": {
              "auth_methods": {
                "items": {
                  "enum": [
                    "sign_in",
                    "api_token",
                    "upstream_oauth"
                  ],
                  "type": "string"
                },
                "type": "array"
              },
              "templates": {
                "additionalProperties": true,
                "description": "Client configuration with placeholders, never secrets.",
                "properties": {
                  "claude_code": {
                    "description": "Claude Code command line.",
                    "type": "string"
                  },
                  "mcp_json": {
                    "description": "`mcpServers` block used by many MCP clients.",
                    "type": "object"
                  },
                  "vscode": {
                    "description": "`servers` block for VS Code.",
                    "type": "object"
                  }
                },
                "type": "object"
              },
              "token_templates": {
                "anyOf": [
                  {
                    "additionalProperties": true,
                    "description": "Client configuration with placeholders, never secrets.",
                    "properties": {
                      "claude_code": {
                        "description": "Claude Code command line.",
                        "type": "string"
                      },
                      "mcp_json": {
                        "description": "`mcpServers` block used by many MCP clients.",
                        "type": "object"
                      },
                      "vscode": {
                        "description": "`servers` block for VS Code.",
                        "type": "object"
                      }
                    },
                    "type": "object"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "url": {
                "format": "uri",
                "type": "string"
              }
            },
            "required": [
              "url",
              "auth_methods"
            ],
            "type": "object"
          },
          "enabled": {
            "type": "boolean"
          },
          "mcp_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "oauth_mode": {
            "type": [
              "string",
              "null"
            ]
          },
          "onemcp": {
            "additionalProperties": true,
            "properties": {
              "auth_methods": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "included": {
                "type": "boolean"
              },
              "templates": {
                "additionalProperties": true,
                "description": "Client configuration with placeholders, never secrets.",
                "properties": {
                  "claude_code": {
                    "description": "Claude Code command line.",
                    "type": "string"
                  },
                  "mcp_json": {
                    "description": "`mcpServers` block used by many MCP clients.",
                    "type": "object"
                  },
                  "vscode": {
                    "description": "`servers` block for VS Code.",
                    "type": "object"
                  }
                },
                "type": "object"
              },
              "url": {
                "format": "uri",
                "type": "string"
              }
            },
            "required": [
              "url",
              "included"
            ],
            "type": "object"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "sign_in_link": {
            "$ref": "#/components/schemas/SignInLinkInfo"
          },
          "slug": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "mcp_id",
          "direct",
          "onemcp",
          "request_id"
        ],
        "type": "object"
      },
      "ConnectLink": {
        "additionalProperties": true,
        "properties": {
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "url": {
            "description": "Single-use, self-authorizing link (15 minutes): whoever opens it signs in with the provider and the connection is saved for the key's administrator. Share it only with the person who should connect. The token is in the URL fragment.",
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "url",
          "expires_at"
        ],
        "type": "object"
      },
      "ConnectLinkCreated": {
        "additionalProperties": true,
        "properties": {
          "connect": {
            "$ref": "#/components/schemas/ConnectLink"
          },
          "mcp_id": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "mcp_id",
          "connect",
          "request_id"
        ],
        "type": "object"
      },
      "Connection": {
        "additionalProperties": true,
        "properties": {
          "auth_type": {
            "type": "string"
          },
          "connected_admins": {
            "description": "Emails of tenant administrators with an OAuth connection.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "connection_state": {
            "enum": [
              "fetch_failed",
              "pending_connection",
              "pending_first_client",
              "ready"
            ],
            "type": "string"
          },
          "last_fetch_errors": {
            "additionalProperties": {
              "additionalProperties": true,
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "code",
                "message"
              ],
              "type": "object"
            },
            "description": "Last tool-fetch failure per section (tools, resources, prompts, transport, capabilities) as a fixed code and message: auth_failed, timeout, tls_error, unreachable, protocol_error, no_capabilities or unknown.",
            "type": [
              "object",
              "null"
            ]
          },
          "mcp_id": {
            "type": "string"
          },
          "oauth_mode": {
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "tool_count": {
            "type": "integer"
          }
        },
        "required": [
          "mcp_id",
          "connection_state",
          "tool_count",
          "request_id"
        ],
        "type": "object"
      },
      "ConnectionRevoked": {
        "additionalProperties": true,
        "properties": {
          "email": {
            "type": "string"
          },
          "mcp_id": {
            "type": "string"
          },
          "removed": {
            "additionalProperties": true,
            "properties": {
              "gateway_token": {
                "type": "boolean"
              },
              "oauth_token": {
                "type": "boolean"
              },
              "upstream_credential": {
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "revoked": {
            "description": "false when nothing was stored.",
            "type": "boolean"
          }
        },
        "required": [
          "mcp_id",
          "email",
          "revoked",
          "request_id"
        ],
        "type": "object"
      },
      "CustomTool": {
        "additionalProperties": true,
        "properties": {
          "custom_tool": {
            "additionalProperties": true,
            "properties": {
              "annotations": {
                "type": "object"
              },
              "code": {
                "type": "string"
              },
              "created_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "created_by": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "defaults": {
                "type": "object"
              },
              "description": {
                "type": "string"
              },
              "enabled": {
                "type": "boolean"
              },
              "fixed_args": {
                "type": "object"
              },
              "input_schema": {
                "type": "object"
              },
              "limits": {
                "additionalProperties": true,
                "properties": {
                  "max_tool_calls": {
                    "type": "integer"
                  },
                  "timeout_s": {
                    "type": "integer"
                  }
                },
                "type": "object"
              },
              "listed_as": {
                "description": "The tool definition clients receive.",
                "type": "object"
              },
              "name": {
                "type": "string"
              },
              "output_schema": {
                "type": [
                  "object",
                  "null"
                ]
              },
              "status": {
                "description": "shadowed: the MCP itself now has a tool with this name, which wins.",
                "enum": [
                  "active",
                  "disabled",
                  "shadowed"
                ],
                "type": "string"
              },
              "tool_version": {
                "description": "Grows by one on every save.",
                "type": "integer"
              },
              "updated_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "updated_by": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "uses_tools": {
                "description": "Tools of the MCP the script calls.",
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "warnings": {
                "description": "Names the script calls that are not tools of the MCP or are waiting for tool review, checked against the MCP's current tools on every read (so a tool the MCP dropped shows up here). Tools turned off or hidden from users are tools of the MCP and are not listed here.",
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            },
            "required": [
              "name",
              "description",
              "input_schema",
              "code",
              "enabled",
              "status"
            ],
            "type": "object"
          },
          "mcp_id": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "version": {
            "description": "Opaque resource version. Send its quoted value in If-Match.",
            "type": "string"
          }
        },
        "required": [
          "mcp_id",
          "custom_tool",
          "version",
          "request_id"
        ],
        "type": "object"
      },
      "CustomToolDefinition": {
        "additionalProperties": false,
        "description": "The whole tool. Omitted optional fields take their defaults.",
        "properties": {
          "annotations": {
            "description": "Tool hints for clients: `title` and the booleans `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. `title` is at most 200 characters.",
            "type": "object"
          },
          "code": {
            "description": "Python script, at most 65536 bytes as UTF-8 (`maxLength` counts characters, so a script with non-ASCII text can be refused below it). `args` holds the arguments (defaults plus what the caller sent). Each tool of the MCP is an async function (`await list_messages(folder=\"inbox\")`), and `await call_tool(\"<tool name>\", {...})` calls any of them by name. This includes tools turned off for users (in the MCP's settings or by a policy) and tools hidden from tool lists. These calls skip the called tool's own enabled setting, policies, quotas, DLP and approvals; the custom tool's own call carries those checks. Tools waiting for tool review, tools the MCP no longer offers, other MCPs' tools and other custom tools cannot be called. The value of the last top-level expression is the tool's result (assign a value computed inside an `if` or loop and end with it). `asyncio`, `datetime`, `json`, `math`, `re` and `time` are already imported. No files, network, environment or imports beyond the sandbox's standard modules. A script that reads a name it never defines or imports is refused on save (400 with the `line`).",
            "maxLength": 65536,
            "minLength": 1,
            "type": "string"
          },
          "defaults": {
            "description": "Default argument values, at most 16 KiB. Clients see them as `default` and do not have to send them; values a call sends replace them.",
            "type": "object"
          },
          "description": {
            "description": "What the tool does and when to use it; models read this to pick the tool.",
            "maxLength": 2000,
            "minLength": 1,
            "type": "string"
          },
          "enabled": {
            "description": "false hides the tool from clients (default true).",
            "type": "boolean"
          },
          "fixed_args": {
            "description": "Values the script always gets in `args`, hidden from clients and never replaced by what a caller sends (for example a fixed project id). Names must not be input_schema properties. At most 16 KiB. Not for secrets: they are returned by reads; keep credentials in the MCP's upstream credentials.",
            "type": "object"
          },
          "input_schema": {
            "description": "JSON Schema of the arguments: `type: object` with typed top-level `properties` (string, number, integer, boolean, array, object), `required` and `additionalProperties` (default false). Allowed top-level keys: `type`, `properties`, `required`, `additionalProperties`, `description`, `$schema` and `title` (the last two are dropped on save). Property names are identifiers (letters, digits and _, at most 64 characters) and every property needs a `type`. At most 50 properties and 16 KiB. No `$ref`, `$id`, `$anchor`, `$dynamicRef`, `$dynamicAnchor` or `$recursiveRef`; `$schema` only at the top level; `unevaluatedProperties` is refused when `patternProperties` appears anywhere in the schema. Each `pattern` or `patternProperties` key is at most 512 characters. When a call is checked, a regex match that takes over 1 s, or a check that takes over 5 s, fails the call. Call arguments are limited to 32 MB and 64 levels of nesting.",
            "type": "object"
          },
          "limits": {
            "description": "`timeout_s` (1 to 60, default 60) and `max_tool_calls` (1 to 50, default 50) per run.",
            "type": "object"
          },
          "output_schema": {
            "description": "Optional JSON Schema (`type: object`) of the result. Clients receive it as the tool's outputSchema and the result as structured content; a result that does not match is returned as an error. At most 16 KiB. The same rules as `input_schema` apply to references, `$schema`, `unevaluatedProperties`, pattern length and match time.",
            "type": [
              "object",
              "null"
            ]
          }
        },
        "required": [
          "description",
          "code"
        ],
        "type": "object"
      },
      "CustomToolDeleted": {
        "additionalProperties": true,
        "properties": {
          "deleted": {
            "type": "boolean"
          },
          "mcp_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "version": {
            "description": "Opaque resource version. Send its quoted value in If-Match.",
            "type": "string"
          }
        },
        "required": [
          "mcp_id",
          "name",
          "deleted",
          "request_id"
        ],
        "type": "object"
      },
      "CustomToolFunctions": {
        "additionalProperties": true,
        "properties": {
          "functions": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "function": {
                  "type": "string"
                },
                "hidden_from_clients": {
                  "description": "true when the tool is turned off in the MCP's settings for everyone: users cannot list or call it, custom tools can. Tools turned off only for some users or groups, or hidden by a policy, show false.",
                  "type": "boolean"
                },
                "input_schema": {
                  "type": "object"
                },
                "signature": {
                  "type": "string"
                },
                "summary": {
                  "type": "string"
                },
                "tool": {
                  "type": "string"
                }
              },
              "required": [
                "tool",
                "function",
                "signature"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "globals": {
            "type": "object"
          },
          "limits": {
            "type": "object"
          },
          "mcp_id": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "functions",
          "request_id"
        ],
        "type": "object"
      },
      "CustomToolList": {
        "additionalProperties": true,
        "properties": {
          "custom_tools": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "annotations": {
                  "type": "object"
                },
                "code": {
                  "type": "string"
                },
                "created_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "created_by": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "defaults": {
                  "type": "object"
                },
                "description": {
                  "type": "string"
                },
                "enabled": {
                  "type": "boolean"
                },
                "fixed_args": {
                  "type": "object"
                },
                "input_schema": {
                  "type": "object"
                },
                "limits": {
                  "additionalProperties": true,
                  "properties": {
                    "max_tool_calls": {
                      "type": "integer"
                    },
                    "timeout_s": {
                      "type": "integer"
                    }
                  },
                  "type": "object"
                },
                "listed_as": {
                  "description": "The tool definition clients receive.",
                  "type": "object"
                },
                "name": {
                  "type": "string"
                },
                "output_schema": {
                  "type": [
                    "object",
                    "null"
                  ]
                },
                "status": {
                  "description": "shadowed: the MCP itself now has a tool with this name, which wins.",
                  "enum": [
                    "active",
                    "disabled",
                    "shadowed"
                  ],
                  "type": "string"
                },
                "tool_version": {
                  "description": "Grows by one on every save.",
                  "type": "integer"
                },
                "updated_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "updated_by": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "uses_tools": {
                  "description": "Tools of the MCP the script calls.",
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "warnings": {
                  "description": "Names the script calls that are not tools of the MCP or are waiting for tool review, checked against the MCP's current tools on every read (so a tool the MCP dropped shows up here). Tools turned off or hidden from users are tools of the MCP and are not listed here.",
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "required": [
                "name",
                "description",
                "input_schema",
                "code",
                "enabled",
                "status"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "limit": {
            "description": "Most custom tools an MCP can have.",
            "type": "integer"
          },
          "mcp_id": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "version": {
            "description": "Opaque resource version. Send its quoted value in If-Match.",
            "type": "string"
          }
        },
        "required": [
          "mcp_id",
          "custom_tools",
          "version",
          "request_id"
        ],
        "type": "object"
      },
      "CustomToolPatch": {
        "additionalProperties": false,
        "description": "Fields to change; the rest keep their saved values.",
        "minProperties": 1,
        "properties": {
          "annotations": {
            "description": "Tool hints for clients: `title` and the booleans `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. `title` is at most 200 characters.",
            "type": "object"
          },
          "code": {
            "description": "Python script, at most 65536 bytes as UTF-8 (`maxLength` counts characters, so a script with non-ASCII text can be refused below it). `args` holds the arguments (defaults plus what the caller sent). Each tool of the MCP is an async function (`await list_messages(folder=\"inbox\")`), and `await call_tool(\"<tool name>\", {...})` calls any of them by name. This includes tools turned off for users (in the MCP's settings or by a policy) and tools hidden from tool lists. These calls skip the called tool's own enabled setting, policies, quotas, DLP and approvals; the custom tool's own call carries those checks. Tools waiting for tool review, tools the MCP no longer offers, other MCPs' tools and other custom tools cannot be called. The value of the last top-level expression is the tool's result (assign a value computed inside an `if` or loop and end with it). `asyncio`, `datetime`, `json`, `math`, `re` and `time` are already imported. No files, network, environment or imports beyond the sandbox's standard modules. A script that reads a name it never defines or imports is refused on save (400 with the `line`).",
            "maxLength": 65536,
            "minLength": 1,
            "type": "string"
          },
          "defaults": {
            "description": "Default argument values, at most 16 KiB. Clients see them as `default` and do not have to send them; values a call sends replace them.",
            "type": "object"
          },
          "description": {
            "description": "What the tool does and when to use it; models read this to pick the tool.",
            "maxLength": 2000,
            "minLength": 1,
            "type": "string"
          },
          "enabled": {
            "description": "false hides the tool from clients (default true).",
            "type": "boolean"
          },
          "fixed_args": {
            "description": "Values the script always gets in `args`, hidden from clients and never replaced by what a caller sends (for example a fixed project id). Names must not be input_schema properties. At most 16 KiB. Not for secrets: they are returned by reads; keep credentials in the MCP's upstream credentials.",
            "type": "object"
          },
          "input_schema": {
            "description": "JSON Schema of the arguments: `type: object` with typed top-level `properties` (string, number, integer, boolean, array, object), `required` and `additionalProperties` (default false). Allowed top-level keys: `type`, `properties`, `required`, `additionalProperties`, `description`, `$schema` and `title` (the last two are dropped on save). Property names are identifiers (letters, digits and _, at most 64 characters) and every property needs a `type`. At most 50 properties and 16 KiB. No `$ref`, `$id`, `$anchor`, `$dynamicRef`, `$dynamicAnchor` or `$recursiveRef`; `$schema` only at the top level; `unevaluatedProperties` is refused when `patternProperties` appears anywhere in the schema. Each `pattern` or `patternProperties` key is at most 512 characters. When a call is checked, a regex match that takes over 1 s, or a check that takes over 5 s, fails the call. Call arguments are limited to 32 MB and 64 levels of nesting.",
            "type": "object"
          },
          "limits": {
            "description": "`timeout_s` (1 to 60, default 60) and `max_tool_calls` (1 to 50, default 50) per run.",
            "type": "object"
          },
          "output_schema": {
            "description": "Optional JSON Schema (`type: object`) of the result. Clients receive it as the tool's outputSchema and the result as structured content; a result that does not match is returned as an error. At most 16 KiB. The same rules as `input_schema` apply to references, `$schema`, `unevaluatedProperties`, pattern length and match time.",
            "type": [
              "object",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "CustomToolRestore": {
        "additionalProperties": false,
        "properties": {
          "version": {
            "description": "A `tool_version` from the history.",
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "version"
        ],
        "type": "object"
      },
      "CustomToolTest": {
        "additionalProperties": false,
        "properties": {
          "arguments": {
            "description": "Arguments, as a client would send them.",
            "type": "object"
          },
          "draft": {
            "additionalProperties": false,
            "description": "Unsaved changes to try: merged over the saved tool, or a whole new tool when none is saved under `name`.",
            "properties": {
              "annotations": {
                "description": "Tool hints for clients: `title` and the booleans `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. `title` is at most 200 characters.",
                "type": "object"
              },
              "code": {
                "description": "Python script, at most 65536 bytes as UTF-8 (`maxLength` counts characters, so a script with non-ASCII text can be refused below it). `args` holds the arguments (defaults plus what the caller sent). Each tool of the MCP is an async function (`await list_messages(folder=\"inbox\")`), and `await call_tool(\"<tool name>\", {...})` calls any of them by name. This includes tools turned off for users (in the MCP's settings or by a policy) and tools hidden from tool lists. These calls skip the called tool's own enabled setting, policies, quotas, DLP and approvals; the custom tool's own call carries those checks. Tools waiting for tool review, tools the MCP no longer offers, other MCPs' tools and other custom tools cannot be called. The value of the last top-level expression is the tool's result (assign a value computed inside an `if` or loop and end with it). `asyncio`, `datetime`, `json`, `math`, `re` and `time` are already imported. No files, network, environment or imports beyond the sandbox's standard modules. A script that reads a name it never defines or imports is refused on save (400 with the `line`).",
                "maxLength": 65536,
                "minLength": 1,
                "type": "string"
              },
              "defaults": {
                "description": "Default argument values, at most 16 KiB. Clients see them as `default` and do not have to send them; values a call sends replace them.",
                "type": "object"
              },
              "description": {
                "description": "What the tool does and when to use it; models read this to pick the tool.",
                "maxLength": 2000,
                "minLength": 1,
                "type": "string"
              },
              "enabled": {
                "description": "false hides the tool from clients (default true).",
                "type": "boolean"
              },
              "fixed_args": {
                "description": "Values the script always gets in `args`, hidden from clients and never replaced by what a caller sends (for example a fixed project id). Names must not be input_schema properties. At most 16 KiB. Not for secrets: they are returned by reads; keep credentials in the MCP's upstream credentials.",
                "type": "object"
              },
              "input_schema": {
                "description": "JSON Schema of the arguments: `type: object` with typed top-level `properties` (string, number, integer, boolean, array, object), `required` and `additionalProperties` (default false). Allowed top-level keys: `type`, `properties`, `required`, `additionalProperties`, `description`, `$schema` and `title` (the last two are dropped on save). Property names are identifiers (letters, digits and _, at most 64 characters) and every property needs a `type`. At most 50 properties and 16 KiB. No `$ref`, `$id`, `$anchor`, `$dynamicRef`, `$dynamicAnchor` or `$recursiveRef`; `$schema` only at the top level; `unevaluatedProperties` is refused when `patternProperties` appears anywhere in the schema. Each `pattern` or `patternProperties` key is at most 512 characters. When a call is checked, a regex match that takes over 1 s, or a check that takes over 5 s, fails the call. Call arguments are limited to 32 MB and 64 levels of nesting.",
                "type": "object"
              },
              "limits": {
                "description": "`timeout_s` (1 to 60, default 60) and `max_tool_calls` (1 to 50, default 50) per run.",
                "type": "object"
              },
              "output_schema": {
                "description": "Optional JSON Schema (`type: object`) of the result. Clients receive it as the tool's outputSchema and the result as structured content; a result that does not match is returned as an error. At most 16 KiB. The same rules as `input_schema` apply to references, `$schema`, `unevaluatedProperties`, pattern length and match time.",
                "type": [
                  "object",
                  "null"
                ]
              }
            },
            "type": "object"
          },
          "mocks": {
            "description": "Exact tool name (the `tool` field of custom-tools:functions) to result: these tools are not called, the script gets the given value instead. Use it to try a script that changes data without changing it. A name the MCP does not offer is refused with 400 before anything runs.",
            "maxProperties": 50,
            "type": "object"
          },
          "name": {
            "maxLength": 64,
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "CustomToolTestResult": {
        "additionalProperties": true,
        "properties": {
          "client_result": {
            "description": "The MCP result a client would get.",
            "type": [
              "object",
              "null"
            ]
          },
          "draft": {
            "type": "boolean"
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "mcp_id": {
            "type": "string"
          },
          "mocked_tools": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "name": {
            "type": "string"
          },
          "ok": {
            "type": "boolean"
          },
          "outcome": {
            "description": "refused: the tool did not run (hidden from the key owner, a policy, no connection, invalid arguments, no free run slot after waiting up to 10 s).",
            "enum": [
              "ok",
              "error",
              "approval_required",
              "refused"
            ],
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "run": {
            "anyOf": [
              {
                "additionalProperties": true,
                "properties": {
                  "approval_required": {
                    "description": "The step that stopped the run for the user's approval.",
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "calls": {
                    "description": "Each tool call the script made, in order.",
                    "items": {
                      "additionalProperties": true,
                      "properties": {
                        "ms": {
                          "type": "integer"
                        },
                        "ok": {
                          "type": "boolean"
                        },
                        "tool": {
                          "type": "string"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "description": "script_error, timeout, memory, max_tool_calls, approval_required, result_too_large (over 80,000 characters), output_schema (the result does not match it) or runner_error. Invalid arguments and a busy run slot give outcome `refused` with `run` null.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "logs": {
                    "description": "print() output.",
                    "type": "string"
                  },
                  "ms": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "result": {
                    "description": "The script's result."
                  },
                  "run_id": {
                    "type": "string"
                  },
                  "unfinished_calls": {
                    "items": {
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "ok",
          "outcome",
          "request_id"
        ],
        "type": "object"
      },
      "CustomToolValidate": {
        "additionalProperties": false,
        "description": "A definition to check without saving.",
        "properties": {
          "annotations": {
            "description": "Tool hints for clients: `title` and the booleans `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. `title` is at most 200 characters.",
            "type": "object"
          },
          "code": {
            "description": "Python script, at most 65536 bytes as UTF-8 (`maxLength` counts characters, so a script with non-ASCII text can be refused below it). `args` holds the arguments (defaults plus what the caller sent). Each tool of the MCP is an async function (`await list_messages(folder=\"inbox\")`), and `await call_tool(\"<tool name>\", {...})` calls any of them by name. This includes tools turned off for users (in the MCP's settings or by a policy) and tools hidden from tool lists. These calls skip the called tool's own enabled setting, policies, quotas, DLP and approvals; the custom tool's own call carries those checks. Tools waiting for tool review, tools the MCP no longer offers, other MCPs' tools and other custom tools cannot be called. The value of the last top-level expression is the tool's result (assign a value computed inside an `if` or loop and end with it). `asyncio`, `datetime`, `json`, `math`, `re` and `time` are already imported. No files, network, environment or imports beyond the sandbox's standard modules. A script that reads a name it never defines or imports is refused on save (400 with the `line`).",
            "maxLength": 65536,
            "minLength": 1,
            "type": "string"
          },
          "defaults": {
            "description": "Default argument values, at most 16 KiB. Clients see them as `default` and do not have to send them; values a call sends replace them.",
            "type": "object"
          },
          "description": {
            "description": "What the tool does and when to use it; models read this to pick the tool.",
            "maxLength": 2000,
            "minLength": 1,
            "type": "string"
          },
          "enabled": {
            "description": "false hides the tool from clients (default true).",
            "type": "boolean"
          },
          "fixed_args": {
            "description": "Values the script always gets in `args`, hidden from clients and never replaced by what a caller sends (for example a fixed project id). Names must not be input_schema properties. At most 16 KiB. Not for secrets: they are returned by reads; keep credentials in the MCP's upstream credentials.",
            "type": "object"
          },
          "input_schema": {
            "description": "JSON Schema of the arguments: `type: object` with typed top-level `properties` (string, number, integer, boolean, array, object), `required` and `additionalProperties` (default false). Allowed top-level keys: `type`, `properties`, `required`, `additionalProperties`, `description`, `$schema` and `title` (the last two are dropped on save). Property names are identifiers (letters, digits and _, at most 64 characters) and every property needs a `type`. At most 50 properties and 16 KiB. No `$ref`, `$id`, `$anchor`, `$dynamicRef`, `$dynamicAnchor` or `$recursiveRef`; `$schema` only at the top level; `unevaluatedProperties` is refused when `patternProperties` appears anywhere in the schema. Each `pattern` or `patternProperties` key is at most 512 characters. When a call is checked, a regex match that takes over 1 s, or a check that takes over 5 s, fails the call. Call arguments are limited to 32 MB and 64 levels of nesting.",
            "type": "object"
          },
          "limits": {
            "description": "`timeout_s` (1 to 60, default 60) and `max_tool_calls` (1 to 50, default 50) per run.",
            "type": "object"
          },
          "name": {
            "maxLength": 64,
            "type": "string"
          },
          "output_schema": {
            "description": "Optional JSON Schema (`type: object`) of the result. Clients receive it as the tool's outputSchema and the result as structured content; a result that does not match is returned as an error. At most 16 KiB. The same rules as `input_schema` apply to references, `$schema`, `unevaluatedProperties`, pattern length and match time.",
            "type": [
              "object",
              "null"
            ]
          }
        },
        "required": [
          "name",
          "description",
          "code"
        ],
        "type": "object"
      },
      "CustomToolValidation": {
        "additionalProperties": true,
        "properties": {
          "custom_tool": {
            "additionalProperties": true,
            "properties": {
              "annotations": {
                "type": "object"
              },
              "code": {
                "type": "string"
              },
              "created_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "created_by": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "defaults": {
                "type": "object"
              },
              "description": {
                "type": "string"
              },
              "enabled": {
                "type": "boolean"
              },
              "fixed_args": {
                "type": "object"
              },
              "input_schema": {
                "type": "object"
              },
              "limits": {
                "additionalProperties": true,
                "properties": {
                  "max_tool_calls": {
                    "type": "integer"
                  },
                  "timeout_s": {
                    "type": "integer"
                  }
                },
                "type": "object"
              },
              "listed_as": {
                "description": "The tool definition clients receive.",
                "type": "object"
              },
              "name": {
                "type": "string"
              },
              "output_schema": {
                "type": [
                  "object",
                  "null"
                ]
              },
              "status": {
                "description": "shadowed: the MCP itself now has a tool with this name, which wins.",
                "enum": [
                  "active",
                  "disabled",
                  "shadowed"
                ],
                "type": "string"
              },
              "tool_version": {
                "description": "Grows by one on every save.",
                "type": "integer"
              },
              "updated_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "updated_by": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "uses_tools": {
                "description": "Tools of the MCP the script calls.",
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "warnings": {
                "description": "Names the script calls that are not tools of the MCP or are waiting for tool review, checked against the MCP's current tools on every read (so a tool the MCP dropped shows up here). Tools turned off or hidden from users are tools of the MCP and are not listed here.",
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            },
            "required": [
              "name",
              "description",
              "input_schema",
              "code",
              "enabled",
              "status"
            ],
            "type": "object"
          },
          "mcp_id": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "valid": {
            "type": "boolean"
          }
        },
        "required": [
          "valid",
          "custom_tool",
          "request_id"
        ],
        "type": "object"
      },
      "CustomToolVersions": {
        "additionalProperties": true,
        "properties": {
          "mcp_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "versions": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "code_sha256": {
                  "type": "string"
                },
                "definition": {
                  "type": "object"
                },
                "saved_at": {
                  "type": "string"
                },
                "saved_by": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "tool_version": {
                  "type": "integer"
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "versions",
          "request_id"
        ],
        "type": "object"
      },
      "DlpReport": {
        "additionalProperties": true,
        "properties": {
          "categories": {
            "description": "Per-category counts; never summed into totals.",
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "categories_truncated": {
            "type": "boolean"
          },
          "data_through": {
            "description": "End of the data the report covers.",
            "format": "date-time",
            "type": "string"
          },
          "directions": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "from": {
            "format": "date-time",
            "type": "string"
          },
          "generated_at": {
            "format": "date-time",
            "type": "string"
          },
          "granularity": {
            "type": "string"
          },
          "group_by": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "mcp_id": {
            "description": "Present on GET /mcps/{mcp_id}/usage.",
            "type": "string"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "row_count": {
            "description": "Rows across all pages.",
            "type": "integer"
          },
          "rows": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "timezone": {
            "enum": [
              "UTC"
            ],
            "type": "string"
          },
          "to": {
            "format": "date-time",
            "type": "string"
          },
          "totals": {
            "additionalProperties": true,
            "properties": {
              "blocked": {
                "type": "integer"
              },
              "flagged": {
                "type": "integer"
              },
              "input": {
                "additionalProperties": true,
                "properties": {
                  "blocked": {
                    "type": "integer"
                  },
                  "flagged": {
                    "type": "integer"
                  },
                  "scanned": {
                    "type": "integer"
                  }
                },
                "type": "object"
              },
              "output": {
                "additionalProperties": true,
                "properties": {
                  "blocked": {
                    "type": "integer"
                  },
                  "flagged": {
                    "type": "integer"
                  },
                  "scanned": {
                    "type": "integer"
                  }
                },
                "type": "object"
              },
              "requests": {
                "type": "integer"
              }
            },
            "type": "object"
          }
        },
        "required": [
          "from",
          "totals",
          "rows",
          "categories",
          "next_cursor",
          "request_id"
        ],
        "type": "object"
      },
      "DlpSettings": {
        "additionalProperties": false,
        "description": "Data loss prevention actions and enabled risk categories for this MCP.",
        "properties": {
          "data_risk_action": {
            "type": "string"
          },
          "data_risk_request_action": {
            "type": "string"
          },
          "data_risk_response_action": {
            "type": "string"
          },
          "enabled_oob_adversarial_risk_categories": {
            "additionalProperties": {
              "type": "boolean"
            },
            "type": "object"
          },
          "enabled_oob_data_risk_categories": {
            "additionalProperties": {
              "type": "boolean"
            },
            "type": "object"
          },
          "enabled_oob_edm_sub_categories": {
            "additionalProperties": {
              "type": "boolean"
            },
            "type": "object"
          },
          "oob_adversarial_risk_category_request_actions": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object"
          },
          "oob_adversarial_risk_category_response_actions": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object"
          },
          "oob_data_risk_category_request_actions": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object"
          },
          "oob_data_risk_category_response_actions": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object"
          },
          "oob_edm_sub_category_request_actions": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object"
          },
          "oob_edm_sub_category_response_actions": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object"
          }
        },
        "type": "object"
      },
      "Empty": {
        "additionalProperties": false,
        "description": "No body, or an empty JSON object.",
        "properties": {},
        "type": "object"
      },
      "Error": {
        "additionalProperties": true,
        "properties": {
          "error": {
            "additionalProperties": true,
            "properties": {
              "code": {
                "description": "Stable machine-readable code.",
                "type": "string"
              },
              "current_version": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "fields": {
                "anyOf": [
                  {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  {
                    "additionalProperties": {
                      "type": "string"
                    },
                    "type": "object"
                  }
                ],
                "description": "Offending request paths (body.x, query.y, path.z) as a list; analytics reports instead return an object keyed by query parameter name with the reason, for example {\"from\": \"must be before to\"}."
              },
              "may_have_run": {
                "description": "test_run_failed only: true when the tool may have run before the failure, false when it did not run.",
                "type": "boolean"
              },
              "message": {
                "description": "Fixed, human-readable text.",
                "type": "string"
              },
              "missing_fields": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "operation_id": {
                "type": "string"
              },
              "required_scopes": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "tool_changes": {
                "description": "Tool-change apply and dismiss 412 only: the current change, to review again.",
                "type": "object"
              }
            },
            "required": [
              "code",
              "message"
            ],
            "type": "object"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "error",
          "request_id"
        ],
        "type": "object"
      },
      "LatencyReport": {
        "additionalProperties": true,
        "properties": {
          "data_through": {
            "description": "End of the data the report covers.",
            "format": "date-time",
            "type": "string"
          },
          "from": {
            "format": "date-time",
            "type": "string"
          },
          "generated_at": {
            "format": "date-time",
            "type": "string"
          },
          "granularity": {
            "type": "string"
          },
          "group_by": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "histogram_edges_ms": {
            "items": {
              "type": "integer"
            },
            "type": "array"
          },
          "mcp_id": {
            "description": "Present on GET /mcps/{mcp_id}/usage.",
            "type": "string"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "row_count": {
            "description": "Rows across all pages.",
            "type": "integer"
          },
          "rows": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "avg_ms": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "count": {
                  "description": "Calls with a duration.",
                  "type": "integer"
                },
                "histogram": {
                  "description": "Counts per bucket of histogram_edges_ms; the last bucket is open.",
                  "items": {
                    "type": "integer"
                  },
                  "type": "array"
                },
                "max_ms": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "p50_ms": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "p90_ms": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "p95_ms": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "p99_ms": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "requests": {
                  "type": "integer"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "timezone": {
            "enum": [
              "UTC"
            ],
            "type": "string"
          },
          "to": {
            "format": "date-time",
            "type": "string"
          },
          "totals": {
            "additionalProperties": true,
            "properties": {
              "avg_ms": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "count": {
                "description": "Calls with a duration.",
                "type": "integer"
              },
              "histogram": {
                "description": "Counts per bucket of histogram_edges_ms; the last bucket is open.",
                "items": {
                  "type": "integer"
                },
                "type": "array"
              },
              "max_ms": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "p50_ms": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "p90_ms": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "p95_ms": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "p99_ms": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "requests": {
                "type": "integer"
              }
            },
            "type": "object"
          }
        },
        "required": [
          "from",
          "totals",
          "rows",
          "next_cursor",
          "request_id"
        ],
        "type": "object"
      },
      "ManagementKey": {
        "additionalProperties": true,
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "expires_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "fingerprint": {
            "description": "Display identifier; not the secret.",
            "type": "string"
          },
          "key_id": {
            "type": "string"
          },
          "last_used_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": "string"
          },
          "owner_user_id": {
            "description": "Administrator the key acts as.",
            "type": "string"
          },
          "revoked_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "scopes": {
            "items": {
              "enum": [
                "agents:write",
                "connections:write",
                "credentials:write",
                "mcps:write",
                "read",
                "settings:write",
                "tenant_settings:write",
                "tokens:write",
                "tool_reviews:write",
                "tools:write"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "status": {
            "enum": [
              "active",
              "expired",
              "revoked"
            ],
            "type": "string"
          },
          "version": {
            "description": "Opaque resource version. Send its quoted value in If-Match.",
            "type": "string"
          }
        },
        "required": [
          "key_id",
          "name",
          "scopes",
          "status",
          "version"
        ],
        "type": "object"
      },
      "ManagementKeyCreate": {
        "additionalProperties": false,
        "properties": {
          "expires_at": {
            "description": "Future RFC 3339 time with a timezone; null never expires.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "description": "Display name.",
            "maxLength": 200,
            "minLength": 1,
            "type": "string"
          },
          "scopes": {
            "items": {
              "enum": [
                "agents:write",
                "connections:write",
                "credentials:write",
                "mcps:write",
                "read",
                "settings:write",
                "tenant_settings:write",
                "tokens:write",
                "tool_reviews:write",
                "tools:write"
              ],
              "type": "string"
            },
            "minItems": 1,
            "type": "array",
            "uniqueItems": true
          }
        },
        "required": [
          "name",
          "scopes"
        ],
        "type": "object"
      },
      "ManagementKeyCreated": {
        "additionalProperties": true,
        "properties": {
          "key": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ManagementKey"
              }
            ],
            "properties": {
              "secret": {
                "description": "Shown once; store it securely.",
                "type": "string"
              }
            },
            "required": [
              "secret"
            ],
            "type": "object"
          },
          "operation_id": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "key",
          "operation_id",
          "request_id"
        ],
        "type": "object"
      },
      "ManagementKeyList": {
        "additionalProperties": true,
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/ManagementKey"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "items",
          "next_cursor",
          "request_id"
        ],
        "type": "object"
      },
      "ManagementKeyPatch": {
        "additionalProperties": false,
        "properties": {
          "expires_at": {
            "description": "Future RFC 3339 time with a timezone; null never expires.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "description": "Display name.",
            "maxLength": 200,
            "minLength": 1,
            "type": "string"
          },
          "scopes": {
            "items": {
              "enum": [
                "agents:write",
                "connections:write",
                "credentials:write",
                "mcps:write",
                "read",
                "settings:write",
                "tenant_settings:write",
                "tokens:write",
                "tool_reviews:write",
                "tools:write"
              ],
              "type": "string"
            },
            "minItems": 1,
            "type": "array",
            "uniqueItems": true
          }
        },
        "type": "object"
      },
      "ManagementKeyResponse": {
        "additionalProperties": true,
        "properties": {
          "key": {
            "$ref": "#/components/schemas/ManagementKey"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "key",
          "request_id"
        ],
        "type": "object"
      },
      "Mcp": {
        "additionalProperties": true,
        "description": "An MCP. Never includes upstream credentials, URL query strings or extra header values.",
        "properties": {
          "auth_type": {
            "enum": [
              "api_key",
              "no_auth",
              "oauth",
              "oauth_passthrough"
            ],
            "type": "string"
          },
          "catalog_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "connection_state": {
            "enum": [
              "fetch_failed",
              "pending_connection",
              "pending_first_client",
              "ready",
              null
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "endpoint_urls": {
            "additionalProperties": true,
            "properties": {
              "mcp": {
                "description": "URL MCP clients connect to.",
                "format": "uri",
                "type": "string"
              }
            },
            "type": "object"
          },
          "execution_type": {
            "enum": [
              "remote",
              "api",
              "local_package"
            ],
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "last_fetch_errors": {
            "additionalProperties": {
              "additionalProperties": true,
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "code",
                "message"
              ],
              "type": "object"
            },
            "description": "Last tool-fetch failure per section (tools, resources, prompts, transport, capabilities) as a fixed code and message: auth_failed, timeout, tls_error, unreachable, protocol_error, no_capabilities or unknown.",
            "type": [
              "object",
              "null"
            ]
          },
          "name": {
            "type": "string"
          },
          "oauth_mode": {
            "enum": [
              "dcr",
              "login",
              "passthrough",
              null
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "remote_connector": {
            "anyOf": [
              {
                "additionalProperties": true,
                "properties": {
                  "connected": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "slug": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "enum": [
              "api",
              "catalog",
              "custom",
              "system"
            ],
            "type": "string"
          },
          "tool_count": {
            "type": [
              "integer",
              "null"
            ]
          },
          "transport_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "upstream_host": {
            "description": "Scheme and host of the upstream server; never its path or query.",
            "type": [
              "string",
              "null"
            ]
          },
          "version": {
            "description": "Opaque resource version. Send its quoted value in If-Match.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "enabled",
          "auth_type",
          "source",
          "version"
        ],
        "type": "object"
      },
      "McpAgentAccess": {
        "additionalProperties": false,
        "properties": {
          "enabled": {
            "description": "true allows the agent.",
            "type": "boolean"
          }
        },
        "required": [
          "enabled"
        ],
        "type": "object"
      },
      "McpAgents": {
        "additionalProperties": true,
        "properties": {
          "agents": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "custom": {
                  "type": "boolean"
                },
                "display_name": {
                  "type": "string"
                },
                "enabled": {
                  "type": "boolean"
                },
                "keyword": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "allowed_agents": {
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "mcp_id": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "version": {
            "description": "Opaque resource version. Send its quoted value in If-Match.",
            "type": "string"
          }
        },
        "required": [
          "mcp_id",
          "agents",
          "version",
          "request_id"
        ],
        "type": "object"
      },
      "McpAuth": {
        "additionalProperties": false,
        "description": "Upstream authentication. Credentials are always shared by all users of the tenant.",
        "properties": {
          "client_id": {
            "description": "oauth_dcr / oauth_login: your OAuth client id (with client_secret). oauth_dcr with a client skips registration and is saved as oauth_login.",
            "maxLength": 8192,
            "minLength": 1,
            "type": "string",
            "writeOnly": true
          },
          "client_secret": {
            "description": "oauth_dcr / oauth_login: your OAuth client secret (with client_id). For a public client (no secret) send \"-\".",
            "maxLength": 8192,
            "minLength": 1,
            "type": "string",
            "writeOnly": true
          },
          "extra_headers": {
            "additionalProperties": {
              "maxLength": 8192,
              "type": "string"
            },
            "description": "Extra headers sent upstream on every call.",
            "maxProperties": 64,
            "type": "object",
            "writeOnly": true
          },
          "extra_query_params": {
            "additionalProperties": {
              "maxLength": 8192,
              "type": "string"
            },
            "description": "Extra query parameters sent upstream.",
            "maxProperties": 64,
            "type": "object",
            "writeOnly": true
          },
          "header_name": {
            "description": "static only: send the token in this header.",
            "maxLength": 256,
            "minLength": 1,
            "type": "string"
          },
          "query_param": {
            "description": "static only: send the token in this query parameter.",
            "maxLength": 256,
            "minLength": 1,
            "type": "string"
          },
          "scheme": {
            "description": "static only: authorization scheme (default Bearer).",
            "maxLength": 64,
            "type": "string"
          },
          "token": {
            "description": "static only: the API key or token.",
            "maxLength": 8192,
            "minLength": 1,
            "type": "string",
            "writeOnly": true
          },
          "type": {
            "description": "none; static (token); oauth_dcr (dynamic client registration); oauth_login (OAuth with a registered or provider-issued client); oauth_passthrough (each MCP client brings its own OAuth token).",
            "enum": [
              "none",
              "static",
              "oauth_dcr",
              "oauth_login",
              "oauth_passthrough"
            ],
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "type": "object"
      },
      "McpCreate": {
        "additionalProperties": false,
        "properties": {
          "auth": {
            "$ref": "#/components/schemas/McpAuth"
          },
          "description": {
            "maxLength": 8000,
            "type": [
              "string",
              "null"
            ]
          },
          "enabled": {
            "description": "false creates the MCP disabled.",
            "type": "boolean"
          },
          "name": {
            "maxLength": 200,
            "minLength": 1,
            "type": "string"
          },
          "remote_connector_id": {
            "description": "Reach a private-network server through this Remote Connector.",
            "maxLength": 128,
            "minLength": 1,
            "type": "string"
          },
          "settings": {
            "$ref": "#/components/schemas/McpSettingsPatch"
          },
          "slug": {
            "description": "URL slug of the MCP endpoint; default derived from the name.",
            "maxLength": 128,
            "minLength": 1,
            "type": "string"
          },
          "transport": {
            "description": "The upstream MCP server URL (Streamable HTTP or SSE).",
            "format": "uri",
            "maxLength": 4096,
            "type": "string"
          }
        },
        "required": [
          "name",
          "transport"
        ],
        "type": "object"
      },
      "McpCreated": {
        "additionalProperties": true,
        "properties": {
          "connect": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ConnectLink"
              },
              {
                "type": "null"
              }
            ],
            "description": "OAuth MCPs only: a single-use connect link; whoever opens it connects the upstream account for the key owner."
          },
          "connection": {
            "additionalProperties": true,
            "properties": {
              "auth_type": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "oauth_mode": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "state": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "tool_count": {
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          },
          "mcp": {
            "$ref": "#/components/schemas/Mcp"
          },
          "operation_id": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "warnings": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "code",
                "message"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "mcp",
          "warnings",
          "operation_id",
          "request_id"
        ],
        "type": "object"
      },
      "McpDeleted": {
        "additionalProperties": true,
        "properties": {
          "deleted": {
            "type": "boolean"
          },
          "mcp_id": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "deleted",
          "mcp_id",
          "request_id"
        ],
        "type": "object"
      },
      "McpList": {
        "additionalProperties": true,
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/Mcp"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "items",
          "next_cursor",
          "request_id"
        ],
        "type": "object"
      },
      "McpPatch": {
        "additionalProperties": false,
        "minProperties": 1,
        "properties": {
          "description": {
            "description": "null or an empty string clears it.",
            "maxLength": 2000,
            "type": [
              "string",
              "null"
            ]
          },
          "enabled": {
            "description": "false stops serving the MCP to every client.",
            "type": "boolean"
          },
          "name": {
            "maxLength": 200,
            "minLength": 1,
            "type": "string"
          }
        },
        "type": "object"
      },
      "McpProbe": {
        "additionalProperties": false,
        "properties": {
          "extra_headers": {
            "additionalProperties": {
              "maxLength": 8192,
              "type": "string"
            },
            "maxProperties": 64,
            "type": "object",
            "writeOnly": true
          },
          "extra_query_params": {
            "additionalProperties": {
              "maxLength": 8192,
              "type": "string"
            },
            "maxProperties": 64,
            "type": "object",
            "writeOnly": true
          },
          "remote_connector_id": {
            "maxLength": 128,
            "minLength": 1,
            "type": "string"
          },
          "transport": {
            "description": "The upstream MCP server URL to check.",
            "format": "uri",
            "maxLength": 4096,
            "type": "string"
          }
        },
        "required": [
          "transport"
        ],
        "type": "object"
      },
      "McpRequest": {
        "additionalProperties": true,
        "properties": {
          "catalog_id": {
            "type": "string"
          },
          "catalog_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "install_requirements": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "request_id": {
            "type": "string"
          },
          "requires_configuration": {
            "type": "boolean"
          },
          "resolved_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "enum": [
              "pending",
              "dismissed",
              "installed"
            ],
            "type": "string"
          },
          "user_email": {
            "type": "string"
          }
        },
        "required": [
          "request_id",
          "catalog_id",
          "user_email",
          "status"
        ],
        "type": "object"
      },
      "McpRequestList": {
        "additionalProperties": true,
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/McpRequest"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "items",
          "next_cursor",
          "request_id"
        ],
        "type": "object"
      },
      "McpRequestResponse": {
        "additionalProperties": true,
        "properties": {
          "request": {
            "$ref": "#/components/schemas/McpRequest"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "request",
          "request_id"
        ],
        "type": "object"
      },
      "McpResponse": {
        "additionalProperties": true,
        "properties": {
          "mcp": {
            "$ref": "#/components/schemas/Mcp"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "mcp",
          "request_id"
        ],
        "type": "object"
      },
      "McpSettings": {
        "additionalProperties": true,
        "properties": {
          "mcp_id": {
            "type": "string"
          },
          "policy_authority": {
            "additionalProperties": true,
            "properties": {
              "mode": {
                "description": "quilrql: QuilrQL policies are authoritative and stored settings are not enforced.",
                "enum": [
                  "legacy",
                  "quilrql"
                ],
                "type": "string"
              }
            },
            "required": [
              "mode"
            ],
            "type": "object"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "settings": {
            "description": "Every settings section with defaults filled in.",
            "type": "object"
          },
          "version": {
            "description": "Opaque resource version. Send its quoted value in If-Match.",
            "type": "string"
          },
          "warnings": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "code",
                "message"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "mcp_id",
          "settings",
          "version",
          "request_id"
        ],
        "type": "object"
      },
      "McpSettingsPatch": {
        "additionalProperties": false,
        "description": "Sectioned MCP settings patch. Unknown fields at any depth are refused. tools, dlp, token_saving, access_control, tool_sync, tool_exposure and onemcp merge by key into the stored settings; web_search_policy and oauth_scopes replace the stored value; oauth_scopes: null and upstream_session_max_concurrency: null clear it.",
        "minProperties": 1,
        "properties": {
          "access_control": {
            "$ref": "#/components/schemas/AccessControlSettings"
          },
          "dlp": {
            "$ref": "#/components/schemas/DlpSettings"
          },
          "oauth_scopes": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ]
          },
          "onemcp": {
            "$ref": "#/components/schemas/OneMcpSettings"
          },
          "send_user_claims_header": {
            "type": "boolean"
          },
          "token_saving": {
            "$ref": "#/components/schemas/TokenSavingSettings"
          },
          "tool_exposure": {
            "$ref": "#/components/schemas/ToolExposureSettings"
          },
          "tool_sync": {
            "$ref": "#/components/schemas/ToolSyncSettings"
          },
          "tools": {
            "additionalProperties": {
              "$ref": "#/components/schemas/ToolSettings"
            },
            "type": "object"
          },
          "upstream_session_max_concurrency": {
            "anyOf": [
              {
                "maximum": 256,
                "minimum": 1,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "web_search_policy": {
            "$ref": "#/components/schemas/WebSearchPolicySettings"
          }
        },
        "type": "object"
      },
      "McpToken": {
        "additionalProperties": true,
        "description": "MCP API token metadata. The secret is only returned by the create call.",
        "properties": {
          "agent": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "created_by": {
            "type": [
              "string",
              "null"
            ]
          },
          "last_used_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "mcp_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "token_id": {
            "type": "string"
          }
        },
        "required": [
          "token_id",
          "mcp_id",
          "name",
          "agent"
        ],
        "type": "object"
      },
      "McpTokenCreate": {
        "additionalProperties": false,
        "properties": {
          "agent": {
            "description": "Agent keyword from GET /agents. The token only works for clients whose User-Agent matches this agent.",
            "maxLength": 50,
            "minLength": 1,
            "type": "string"
          },
          "name": {
            "description": "Display name.",
            "maxLength": 200,
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "name",
          "agent"
        ],
        "type": "object"
      },
      "McpTokenCreated": {
        "additionalProperties": true,
        "properties": {
          "operation_id": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "token": {
            "allOf": [
              {
                "$ref": "#/components/schemas/McpToken"
              },
              {
                "additionalProperties": true,
                "properties": {
                  "secret": {
                    "description": "Shown once. Starts with sk-quilr-mcp-.",
                    "type": "string"
                  }
                },
                "required": [
                  "secret"
                ],
                "type": "object"
              }
            ]
          }
        },
        "required": [
          "token",
          "operation_id",
          "request_id"
        ],
        "type": "object"
      },
      "McpTokenList": {
        "additionalProperties": true,
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/McpToken"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "items",
          "next_cursor",
          "request_id"
        ],
        "type": "object"
      },
      "McpTokenRevoked": {
        "additionalProperties": true,
        "properties": {
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "token": {
            "additionalProperties": true,
            "properties": {
              "revoked": {
                "type": "boolean"
              },
              "token_id": {
                "type": "string"
              }
            },
            "type": "object"
          }
        },
        "required": [
          "token",
          "request_id"
        ],
        "type": "object"
      },
      "McpTools": {
        "additionalProperties": true,
        "properties": {
          "mcp_id": {
            "type": "string"
          },
          "policy_authority": {
            "additionalProperties": true,
            "properties": {
              "mode": {
                "description": "quilrql: QuilrQL policies are authoritative and stored settings are not enforced.",
                "enum": [
                  "legacy",
                  "quilrql"
                ],
                "type": "string"
              }
            },
            "required": [
              "mode"
            ],
            "type": "object"
          },
          "prompts": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "resources": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "tools": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "annotations": {},
                "call_count": {
                  "description": "All-time calls; null when usage data is unavailable (see warnings).",
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "enabled": {
                  "type": "boolean"
                },
                "enforce_confirmation": {
                  "type": "boolean"
                },
                "input_schema": {},
                "name": {
                  "type": "string"
                },
                "require_justification": {
                  "type": "boolean"
                },
                "review_state": {
                  "enum": [
                    "held",
                    "rejected",
                    null
                  ],
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "title": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "name"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "warnings": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "code",
                "message"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "mcp_id",
          "tools",
          "resources",
          "prompts",
          "request_id"
        ],
        "type": "object"
      },
      "McpUsers": {
        "additionalProperties": true,
        "properties": {
          "generated_at": {
            "format": "date-time",
            "type": "string"
          },
          "items": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "access_allowed": {
                  "type": "boolean"
                },
                "can_renew": {
                  "type": [
                    "boolean",
                    "null"
                  ]
                },
                "email": {
                  "type": "string"
                },
                "preference_enabled": {
                  "type": "boolean"
                },
                "set_up_at": {
                  "format": "date-time",
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "signed_in_until": {
                  "format": "date-time",
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "state": {
                  "enum": [
                    "signed_in",
                    "available",
                    "needs_sign_in",
                    "sign_in_not_finished",
                    "not_signed_in_yet",
                    "turned_off_by_user",
                    "blocked_by_access_rules",
                    "mcp_turned_off"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "email",
                "state"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "mcp_id": {
            "type": "string"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "renews_automatically": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "sign_in_required": {
            "type": [
              "boolean",
              "null"
            ]
          }
        },
        "required": [
          "items",
          "next_cursor",
          "mcp_id",
          "request_id"
        ],
        "type": "object"
      },
      "OAuthClient": {
        "additionalProperties": true,
        "properties": {
          "mcp_id": {
            "type": "string"
          },
          "oauth_client": {
            "additionalProperties": true,
            "properties": {
              "client_id_hint": {
                "description": "Last characters of the client id.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "configured": {
                "type": "boolean"
              },
              "custom": {
                "description": "Supplied by an administrator (rotatable).",
                "type": "boolean"
              },
              "oauth": {
                "type": "boolean"
              },
              "registered_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "rotatable": {
                "type": "boolean"
              }
            },
            "required": [
              "oauth",
              "rotatable"
            ],
            "type": "object"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "rotation": {
            "additionalProperties": true,
            "properties": {
              "client_id_changed": {
                "type": "boolean"
              },
              "connections_dropped": {
                "type": "integer"
              },
              "reconnect_users": {
                "type": [
                  "boolean",
                  "null"
                ]
              }
            },
            "type": "object"
          },
          "version": {
            "description": "Opaque resource version. Send its quoted value in If-Match.",
            "type": "string"
          }
        },
        "required": [
          "mcp_id",
          "oauth_client",
          "version",
          "request_id"
        ],
        "type": "object"
      },
      "OAuthClientRotate": {
        "additionalProperties": false,
        "properties": {
          "client_id": {
            "description": "A new client id; omit to keep the current one.",
            "maxLength": 8192,
            "minLength": 1,
            "type": "string"
          },
          "client_secret": {
            "description": "The client secret. Required on every rotation; \"-\" for a public client (no secret).",
            "maxLength": 8192,
            "minLength": 1,
            "type": "string",
            "writeOnly": true
          },
          "reconnect_users": {
            "description": "Required when client_id changes. true deletes every user's connection (each user signs in again); false keeps them working with the previous client until it stops working at the provider.",
            "type": "boolean"
          }
        },
        "required": [
          "client_secret"
        ],
        "type": "object"
      },
      "OAuthScopeOptions": {
        "additionalProperties": true,
        "properties": {
          "always_available_tools": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "available": {
            "type": "boolean"
          },
          "cross_area_tools": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "mcp_id": {
            "type": "string"
          },
          "options": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "selected": {
            "description": "The stored selection (settings oauth_scopes).",
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          }
        },
        "required": [
          "mcp_id",
          "available",
          "options",
          "request_id"
        ],
        "type": "object"
      },
      "OneMcpSettings": {
        "additionalProperties": false,
        "description": "How this MCP takes part in OneMCP; hidden makes it reachable only at its own endpoint.",
        "properties": {
          "hidden": {
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "OpenApiDocument": {
        "additionalProperties": true,
        "description": "This document. The response has no request_id field.",
        "properties": {
          "components": {
            "type": "object"
          },
          "info": {
            "type": "object"
          },
          "openapi": {
            "type": "string"
          },
          "paths": {
            "type": "object"
          }
        },
        "required": [
          "openapi",
          "info",
          "paths"
        ],
        "type": "object"
      },
      "Operation": {
        "additionalProperties": true,
        "properties": {
          "operation": {
            "additionalProperties": true,
            "properties": {
              "completed_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "operation": {
                "type": "string"
              },
              "operation_id": {
                "type": "string"
              },
              "resource_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "stages": {
                "items": {
                  "additionalProperties": true,
                  "properties": {
                    "at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "stage": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                },
                "type": "array"
              },
              "state": {
                "enum": [
                  "pending",
                  "done",
                  "failed",
                  "expired"
                ],
                "type": "string"
              },
              "status_code": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "updated_at": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "operation_id",
              "state"
            ],
            "type": "object"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "operation",
          "request_id"
        ],
        "type": "object"
      },
      "ProbeResult": {
        "additionalProperties": true,
        "properties": {
          "probe": {
            "additionalProperties": true,
            "description": "What the URL requires: transport, OAuth discovery and whether a credential is needed. URLs are returned without query strings.",
            "properties": {},
            "type": "object"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "probe",
          "request_id"
        ],
        "type": "object"
      },
      "RefreshResult": {
        "additionalProperties": true,
        "properties": {
          "fetch_errors": {
            "additionalProperties": {
              "additionalProperties": true,
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "code",
                "message"
              ],
              "type": "object"
            },
            "description": "Last tool-fetch failure per section (tools, resources, prompts, transport, capabilities) as a fixed code and message: auth_failed, timeout, tls_error, unreachable, protocol_error, no_capabilities or unknown.",
            "type": [
              "object",
              "null"
            ]
          },
          "held_tools": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "mcp": {
            "$ref": "#/components/schemas/Mcp"
          },
          "prompts_count": {
            "type": "integer"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "resources_count": {
            "type": "integer"
          },
          "tools_count": {
            "type": "integer"
          }
        },
        "required": [
          "mcp",
          "tools_count",
          "request_id"
        ],
        "type": "object"
      },
      "RequestsReport": {
        "additionalProperties": true,
        "properties": {
          "data_through": {
            "description": "End of the data the report covers.",
            "format": "date-time",
            "type": "string"
          },
          "from": {
            "format": "date-time",
            "type": "string"
          },
          "generated_at": {
            "format": "date-time",
            "type": "string"
          },
          "mcp_id": {
            "description": "Present on GET /mcps/{mcp_id}/usage.",
            "type": "string"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "rows": {
            "items": {
              "additionalProperties": true,
              "description": "Call metadata only: never tool arguments, responses, error text, headers or tokens.",
              "properties": {
                "agent": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "auth_mode": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "blocked": {
                  "type": "boolean"
                },
                "called_via": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "completed_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "dlp": {
                  "type": "object"
                },
                "duration_ms": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "error": {
                  "type": "boolean"
                },
                "mcp": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "mcp_name": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "outcome": {
                  "enum": [
                    "success",
                    "error",
                    "blocked",
                    null
                  ],
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "request_id": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "started_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "tool": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "transport": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "user": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "timezone": {
            "enum": [
              "UTC"
            ],
            "type": "string"
          },
          "to": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "from",
          "rows",
          "next_cursor",
          "request_id"
        ],
        "type": "object"
      },
      "ScopedDlpSettingsPatch": {
        "additionalProperties": false,
        "properties": {
          "data_risk_action": {
            "anyOf": [
              {
                "enum": [
                  "monitor",
                  "partial-redact",
                  "redact",
                  "block"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "data_risk_request_action": {
            "anyOf": [
              {
                "enum": [
                  "monitor",
                  "partial-redact",
                  "redact",
                  "block"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "data_risk_response_action": {
            "anyOf": [
              {
                "enum": [
                  "monitor",
                  "partial-redact",
                  "redact",
                  "block"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "enabled_oob_adversarial_risk_categories": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "boolean"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "enabled_oob_data_risk_categories": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "boolean"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "enabled_oob_edm_sub_categories": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "boolean"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "oob_adversarial_risk_category_request_actions": {
            "anyOf": [
              {
                "additionalProperties": {
                  "enum": [
                    "default",
                    "monitor",
                    "partial-redact",
                    "redact",
                    "block"
                  ],
                  "type": "string"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "oob_adversarial_risk_category_response_actions": {
            "anyOf": [
              {
                "additionalProperties": {
                  "enum": [
                    "default",
                    "monitor",
                    "partial-redact",
                    "redact",
                    "block"
                  ],
                  "type": "string"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "oob_data_risk_category_request_actions": {
            "anyOf": [
              {
                "additionalProperties": {
                  "enum": [
                    "default",
                    "monitor",
                    "partial-redact",
                    "redact",
                    "block"
                  ],
                  "type": "string"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "oob_data_risk_category_response_actions": {
            "anyOf": [
              {
                "additionalProperties": {
                  "enum": [
                    "default",
                    "monitor",
                    "partial-redact",
                    "redact",
                    "block"
                  ],
                  "type": "string"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "oob_edm_sub_category_request_actions": {
            "anyOf": [
              {
                "additionalProperties": {
                  "enum": [
                    "default",
                    "monitor",
                    "partial-redact",
                    "redact",
                    "block"
                  ],
                  "type": "string"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "oob_edm_sub_category_response_actions": {
            "anyOf": [
              {
                "additionalProperties": {
                  "enum": [
                    "default",
                    "monitor",
                    "partial-redact",
                    "redact",
                    "block"
                  ],
                  "type": "string"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object"
      },
      "ScopedSettingResult": {
        "additionalProperties": true,
        "properties": {
          "deleted": {
            "type": "boolean"
          },
          "mcp_id": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "scope_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "scope_value": {
            "type": [
              "string",
              "null"
            ]
          },
          "scoped_setting": {
            "anyOf": [
              {
                "additionalProperties": true,
                "properties": {
                  "created_at": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "enabled": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "scope_type": {
                    "enum": [
                      "smart_group",
                      "user"
                    ],
                    "type": "string"
                  },
                  "scope_value": {
                    "type": "string"
                  },
                  "settings": {
                    "type": "object"
                  },
                  "updated_at": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "updated_by": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "version": {
            "description": "Opaque resource version. Send its quoted value in If-Match.",
            "type": "string"
          },
          "warnings": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "code",
                "message"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "mcp_id",
          "version",
          "request_id"
        ],
        "type": "object"
      },
      "ScopedSettingsList": {
        "additionalProperties": true,
        "properties": {
          "mcp_id": {
            "type": "string"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "scoped_settings": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "created_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "enabled": {
                  "type": [
                    "boolean",
                    "null"
                  ]
                },
                "scope_type": {
                  "enum": [
                    "smart_group",
                    "user"
                  ],
                  "type": "string"
                },
                "scope_value": {
                  "type": "string"
                },
                "settings": {
                  "type": "object"
                },
                "updated_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "updated_by": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "version": {
            "description": "Opaque resource version. Send its quoted value in If-Match.",
            "type": "string"
          }
        },
        "required": [
          "mcp_id",
          "scoped_settings",
          "next_cursor",
          "version",
          "request_id"
        ],
        "type": "object"
      },
      "ScopedSettingsPatch": {
        "additionalProperties": false,
        "description": "Per-user or per-smart-group override of tools, dlp and token_saving (at least one section).",
        "minProperties": 1,
        "properties": {
          "dlp": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ScopedDlpSettingsPatch"
              },
              {
                "type": "null"
              }
            ]
          },
          "token_saving": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ScopedTokenSavingSettingsPatch"
              },
              {
                "type": "null"
              }
            ]
          },
          "tools": {
            "anyOf": [
              {
                "additionalProperties": {
                  "$ref": "#/components/schemas/ScopedToolSettingsPatch"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object"
      },
      "ScopedSettingsPut": {
        "additionalProperties": false,
        "properties": {
          "enabled": {
            "description": "false keeps the override stored but inactive.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "settings": {
            "$ref": "#/components/schemas/ScopedSettingsPatch"
          }
        },
        "required": [
          "settings"
        ],
        "type": "object"
      },
      "ScopedTokenSavingSettingsPatch": {
        "additionalProperties": false,
        "properties": {
          "html_to_text": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ]
          },
          "markdown_to_text": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ]
          },
          "smart_json_compression": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ]
          },
          "strip_base64": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "Replaces detected base64 content with a byte-count placeholder. Removed content is unavailable to the model."
          },
          "text_compression": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object"
      },
      "ScopedToolSettingsPatch": {
        "additionalProperties": false,
        "properties": {
          "enabled": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ]
          },
          "enforce_confirmation": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ]
          },
          "require_justification": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object"
      },
      "SignInLink": {
        "additionalProperties": true,
        "properties": {
          "connection": {
            "description": "What the user does after signing in: oauth (sign in to the provider), user_key (save their own key) or null (nothing).",
            "enum": [
              "oauth",
              "user_key",
              null
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "mcp_id": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "requires_user_action": {
            "type": "boolean"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "mcp_id",
          "url",
          "connection",
          "request_id"
        ],
        "type": "object"
      },
      "SignInLinkInfo": {
        "additionalProperties": true,
        "description": "Hand this to users; it carries no credential.",
        "properties": {
          "connection": {
            "description": "What the user does after signing in: oauth (sign in to the provider), user_key (save their own key) or null (nothing).",
            "enum": [
              "oauth",
              "user_key",
              null
            ],
            "type": [
              "string",
              "null"
            ]
          },
          "requires_user_action": {
            "type": "boolean"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "url",
          "connection"
        ],
        "type": "object"
      },
      "TenantConfig": {
        "additionalProperties": true,
        "properties": {
          "data_retention": {
            "additionalProperties": true,
            "description": "Read only: managed in the Quilr console.",
            "properties": {
              "managed_by": {
                "type": "string"
              },
              "stored_revision": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "updated_at": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "type": "object"
          },
          "memories": {
            "anyOf": [
              {
                "additionalProperties": true,
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "updated_at": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "updated_by": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "policy_authority": {
            "additionalProperties": true,
            "properties": {
              "mode": {
                "enum": [
                  "legacy",
                  "quilrql"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "smart_mode": {
            "anyOf": [
              {
                "additionalProperties": true,
                "properties": {
                  "mode": {
                    "enum": [
                      "user_preference",
                      "force_enabled",
                      "force_disabled"
                    ],
                    "type": "string"
                  },
                  "updated_at": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "updated_by": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ]
          },
          "tenant_id": {
            "type": "string"
          },
          "tool_review": {
            "anyOf": [
              {
                "additionalProperties": true,
                "properties": {
                  "hold_new_tools": {
                    "type": "boolean"
                  },
                  "updated_at": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "updated_by": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "null when new-tool review is not available."
          },
          "version": {
            "description": "Opaque resource version. Send its quoted value in If-Match.",
            "type": "string"
          },
          "warnings": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "code": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "tenant_id",
          "version",
          "request_id"
        ],
        "type": "object"
      },
      "TenantConfigPatch": {
        "additionalProperties": false,
        "description": "Send at least one section.",
        "properties": {
          "memories": {
            "additionalProperties": false,
            "description": "Memories for users and OneMCP.",
            "properties": {
              "enabled": {
                "type": "boolean"
              }
            },
            "required": [
              "enabled"
            ],
            "type": "object"
          },
          "smart_mode": {
            "additionalProperties": false,
            "description": "Dynamic Tool Calling for OneMCP: follow each user's preference, or force it on or off.",
            "properties": {
              "mode": {
                "enum": [
                  "user_preference",
                  "force_enabled",
                  "force_disabled"
                ],
                "type": "string"
              }
            },
            "required": [
              "mode"
            ],
            "type": "object"
          },
          "tool_review": {
            "additionalProperties": false,
            "description": "Hold new upstream tools for review on every MCP that inherits the tenant default.",
            "properties": {
              "hold_new_tools": {
                "type": "boolean"
              }
            },
            "required": [
              "hold_new_tools"
            ],
            "type": "object"
          }
        },
        "type": "object"
      },
      "TenantSettings": {
        "additionalProperties": true,
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "version": {
            "description": "Opaque resource version. Send its quoted value in If-Match.",
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "enabled",
          "version",
          "request_id"
        ],
        "type": "object"
      },
      "TenantSettingsPatch": {
        "additionalProperties": false,
        "properties": {
          "enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "enabled"
        ],
        "type": "object"
      },
      "TokenSavingSettings": {
        "additionalProperties": false,
        "description": "Output transforms that reduce tokens sent to the model.",
        "properties": {
          "html_to_text": {
            "type": "boolean"
          },
          "markdown_to_text": {
            "type": "boolean"
          },
          "smart_json_compression": {
            "type": "boolean"
          },
          "strip_base64": {
            "description": "Replaces detected base64 content with a byte-count placeholder. Removed content is unavailable to the model.",
            "type": "boolean"
          },
          "text_compression": {
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "ToolArgAlias": {
        "additionalProperties": true,
        "properties": {
          "active": {
            "description": "Enabled and valid against the tool's current schema.",
            "type": "boolean"
          },
          "alias_id": {
            "type": "string"
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "kind": {
            "type": "string"
          },
          "mcp_id": {
            "type": "string"
          },
          "note": {
            "type": [
              "string",
              "null"
            ]
          },
          "schema_verified": {
            "type": "boolean"
          },
          "source": {
            "type": [
              "string",
              "null"
            ]
          },
          "spec": {
            "type": "object"
          },
          "tool_name": {
            "type": "string"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "alias_id",
          "mcp_id",
          "tool_name",
          "kind",
          "enabled"
        ],
        "type": "object"
      },
      "ToolArgAliasCreate": {
        "additionalProperties": false,
        "properties": {
          "enabled": {
            "default": true,
            "type": "boolean"
          },
          "mcp_id": {
            "description": "MCP whose tool the alias applies to.",
            "type": "string"
          },
          "note": {
            "maxLength": 2000,
            "type": [
              "string",
              "null"
            ]
          },
          "spec": {
            "$ref": "#/components/schemas/ToolArgAliasSpec"
          }
        },
        "required": [
          "mcp_id",
          "spec"
        ],
        "type": "object"
      },
      "ToolArgAliasDeleted": {
        "additionalProperties": true,
        "properties": {
          "alias": {
            "additionalProperties": true,
            "properties": {
              "alias_id": {
                "type": "string"
              },
              "deleted": {
                "type": "boolean"
              },
              "mcp_id": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "alias",
          "request_id"
        ],
        "type": "object"
      },
      "ToolArgAliasList": {
        "additionalProperties": true,
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/ToolArgAlias"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "items",
          "next_cursor",
          "request_id"
        ],
        "type": "object"
      },
      "ToolArgAliasPatch": {
        "additionalProperties": false,
        "description": "Send at least one field.",
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "note": {
            "maxLength": 2000,
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "ToolArgAliasPut": {
        "additionalProperties": false,
        "description": "Creates the alias with this id, or replaces it (spec included).",
        "properties": {
          "enabled": {
            "default": true,
            "type": "boolean"
          },
          "mcp_id": {
            "description": "MCP whose tool the alias applies to.",
            "type": "string"
          },
          "note": {
            "maxLength": 2000,
            "type": [
              "string",
              "null"
            ]
          },
          "spec": {
            "$ref": "#/components/schemas/ToolArgAliasSpec"
          }
        },
        "required": [
          "mcp_id",
          "spec"
        ],
        "type": "object"
      },
      "ToolArgAliasResponse": {
        "additionalProperties": true,
        "properties": {
          "alias": {
            "$ref": "#/components/schemas/ToolArgAlias"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "alias",
          "request_id"
        ],
        "type": "object"
      },
      "ToolArgAliasSpec": {
        "description": "Alias specification for one tool, checked against its input schema.",
        "oneOf": [
          {
            "properties": {
              "action": {
                "description": "Action name for tools that dispatch on an action argument; null otherwise.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "from": {
                "description": "Name clients send.",
                "minLength": 1,
                "type": "string"
              },
              "kind": {
                "const": "param_alias"
              },
              "path": {
                "default": [],
                "description": "Path of nested objects the rule applies inside; [] is the top level.",
                "items": {
                  "minLength": 1,
                  "type": "string"
                },
                "type": "array"
              },
              "to": {
                "description": "Name the tool expects.",
                "minLength": 1,
                "type": "string"
              },
              "tool_name": {
                "minLength": 1,
                "type": "string"
              },
              "version": {
                "enum": [
                  1
                ],
                "type": "integer"
              }
            },
            "required": [
              "version",
              "kind",
              "tool_name",
              "from",
              "to"
            ],
            "title": "Parameter alias",
            "type": "object"
          },
          {
            "properties": {
              "action": {
                "description": "Action name for tools that dispatch on an action argument; null otherwise.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "from_values": {
                "items": {
                  "type": "string"
                },
                "minItems": 1,
                "type": "array"
              },
              "kind": {
                "const": "value_normalization"
              },
              "match": {
                "description": "normalized ignores case, spaces and punctuation.",
                "enum": [
                  "exact",
                  "normalized"
                ],
                "type": "string"
              },
              "param": {
                "minLength": 1,
                "type": "string"
              },
              "path": {
                "default": [],
                "description": "Path of nested objects the rule applies inside; [] is the top level.",
                "items": {
                  "minLength": 1,
                  "type": "string"
                },
                "type": "array"
              },
              "to_value": {
                "minLength": 1,
                "type": "string"
              },
              "tool_name": {
                "minLength": 1,
                "type": "string"
              },
              "version": {
                "enum": [
                  1
                ],
                "type": "integer"
              }
            },
            "required": [
              "version",
              "kind",
              "tool_name",
              "param",
              "match",
              "from_values",
              "to_value"
            ],
            "title": "Value normalization",
            "type": "object"
          },
          {
            "properties": {
              "action": {
                "description": "Action name for tools that dispatch on an action argument; null otherwise.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "kind": {
                "enum": [
                  "envelope_wrap",
                  "envelope_unwrap"
                ],
                "type": "string"
              },
              "path": {
                "default": [],
                "description": "Path of nested objects the rule applies inside; [] is the top level.",
                "items": {
                  "minLength": 1,
                  "type": "string"
                },
                "type": "array"
              },
              "tool_name": {
                "minLength": 1,
                "type": "string"
              },
              "version": {
                "enum": [
                  1
                ],
                "type": "integer"
              }
            },
            "required": [
              "version",
              "kind",
              "tool_name"
            ],
            "title": "Envelope wrap or unwrap",
            "type": "object"
          }
        ]
      },
      "ToolChange": {
        "additionalProperties": true,
        "properties": {
          "added": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "change_count": {
            "type": "integer"
          },
          "checked_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "detected_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "mcp_id": {
            "type": "string"
          },
          "mode": {
            "description": "The MCP's tool_sync mode: notify, auto or off.",
            "type": "string"
          },
          "modified": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "name": {
            "type": "string"
          },
          "reason_code": {
            "description": "Why the last check failed or was skipped, as a fixed code (auth_failed, timeout, unreachable, ...).",
            "type": [
              "string",
              "null"
            ]
          },
          "removed": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "resolved_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "resolved_by": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "description": "off, unchecked, clean, pending, applied, dismissed, skipped or error.",
            "type": "string"
          },
          "version": {
            "description": "Version of the change awaiting review, derived from the exact difference shown; send it quoted in If-Match to apply or dismiss. null when nothing is pending.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "mcp_id",
          "status",
          "change_count"
        ],
        "type": "object"
      },
      "ToolChangeList": {
        "additionalProperties": true,
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/ToolChange"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "items",
          "next_cursor",
          "request_id"
        ],
        "type": "object"
      },
      "ToolChangeResponse": {
        "additionalProperties": true,
        "properties": {
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "tool_changes": {
            "$ref": "#/components/schemas/ToolChange"
          }
        },
        "required": [
          "tool_changes",
          "request_id"
        ],
        "type": "object"
      },
      "ToolExposureSettings": {
        "additionalProperties": false,
        "description": "Smart tool lists: list only the most-used tools plus a tool search, or expose a code tool. Both are off by default.",
        "properties": {
          "code": {
            "type": "boolean"
          },
          "pinned": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "top_tools": {
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "ToolReviewDecision": {
        "additionalProperties": false,
        "properties": {
          "tools": {
            "description": "Names of tools awaiting review.",
            "items": {
              "maxLength": 500,
              "minLength": 1,
              "type": "string"
            },
            "maxItems": 500,
            "minItems": 1,
            "type": "array",
            "uniqueItems": true
          }
        },
        "required": [
          "tools"
        ],
        "type": "object"
      },
      "ToolReviews": {
        "additionalProperties": true,
        "properties": {
          "hold_new_tools": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "mcp_id": {
            "type": "string"
          },
          "mode": {
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "tenant_hold_new_tools": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "tools": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "description": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "detected_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "input_schema": {},
                "name": {
                  "type": "string"
                },
                "resolved_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "resolved_by": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "source": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "status": {
                  "type": "string"
                },
                "updated_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "mcp_id",
          "tools",
          "request_id"
        ],
        "type": "object"
      },
      "ToolSettings": {
        "additionalProperties": false,
        "description": "Settings of one tool, keyed by tool name.",
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "enforce_confirmation": {
            "type": "boolean"
          },
          "require_justification": {
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "ToolSyncSettings": {
        "additionalProperties": false,
        "description": "What happens when the upstream tool list changes: notify (record the change for review), auto (refresh the tool list) or off.",
        "properties": {
          "mode": {
            "enum": [
              "notify",
              "auto",
              "off"
            ],
            "type": "string"
          },
          "new_tools": {
            "enum": [
              "inherit",
              "hold",
              "allow"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "UpstreamAuth": {
        "additionalProperties": true,
        "properties": {
          "mcp_id": {
            "type": "string"
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "upstream_auth": {
            "additionalProperties": true,
            "description": "Credential metadata only; secrets are never returned.",
            "properties": {
              "configured": {
                "type": "boolean"
              },
              "credential_editable": {
                "type": "boolean"
              },
              "extra_header_names": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "extra_query_param_names": {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "header_name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "mode": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "oauth_mode": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "query_param": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "scheme": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "secret_configured": {
                "type": "boolean"
              },
              "type": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "updated_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "user_credentials_saved": {
                "description": "Users who saved their own key (used in mode user_required; kept, unused, in admin_shared).",
                "type": "integer"
              }
            },
            "required": [
              "configured"
            ],
            "type": "object"
          },
          "version": {
            "description": "Opaque resource version. Send its quoted value in If-Match.",
            "type": "string"
          }
        },
        "required": [
          "mcp_id",
          "upstream_auth",
          "version",
          "request_id"
        ],
        "type": "object"
      },
      "UpstreamAuthPut": {
        "additionalProperties": false,
        "description": "Static credential and extras: one shared key, or the shape of a key each user brings (`mode`). OAuth MCPs take only `extra_headers` and `extra_query_params`; a static credential (type, token, header_name, query_param, scheme, mode) is refused.",
        "minProperties": 1,
        "properties": {
          "extra_headers": {
            "additionalProperties": {
              "maxLength": 8192,
              "type": "string"
            },
            "description": "Replaces the extra headers; {} clears them; omit to keep.",
            "maxProperties": 50,
            "type": "object",
            "writeOnly": true
          },
          "extra_query_params": {
            "additionalProperties": {
              "maxLength": 8192,
              "type": "string"
            },
            "description": "Replaces the extra query parameters; {} clears them; omit to keep.",
            "maxProperties": 50,
            "type": "object",
            "writeOnly": true
          },
          "header_name": {
            "description": "Header for type header.",
            "maxLength": 8192,
            "type": "string"
          },
          "mode": {
            "description": "admin_shared: one key for every user (`token` required). user_required: each user saves their own key from the user dashboard; send the shape only, never `token`. Switching to user_required deletes the shared key; switching back needs a new `token` and keeps users' saved keys unused. Omit to keep the current mode.",
            "enum": [
              "admin_shared",
              "user_required"
            ],
            "type": "string"
          },
          "query_param": {
            "description": "Parameter for type query.",
            "maxLength": 8192,
            "type": "string"
          },
          "scheme": {
            "description": "Scheme for type bearer.",
            "maxLength": 8192,
            "type": "string"
          },
          "token": {
            "description": "Static API key or token. Rotates the stored one (admin_shared only).",
            "maxLength": 8192,
            "minLength": 1,
            "type": "string",
            "writeOnly": true
          },
          "type": {
            "description": "How the token is sent: bearer, header or query.",
            "enum": [
              "bearer",
              "header",
              "query"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "UsageReport": {
        "additionalProperties": true,
        "properties": {
          "data_through": {
            "description": "End of the data the report covers.",
            "format": "date-time",
            "type": "string"
          },
          "from": {
            "format": "date-time",
            "type": "string"
          },
          "generated_at": {
            "format": "date-time",
            "type": "string"
          },
          "granularity": {
            "type": "string"
          },
          "group_by": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "mcp_id": {
            "description": "Present on GET /mcps/{mcp_id}/usage.",
            "type": "string"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "row_count": {
            "description": "Rows across all pages.",
            "type": "integer"
          },
          "rows": {
            "items": {
              "additionalProperties": true,
              "description": "Rows also carry period_start (unless granularity is total) and one field per group_by dimension (mcp rows add mcp_name).",
              "properties": {
                "avg_duration_ms": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "blocked": {
                  "type": "integer"
                },
                "errors": {
                  "type": "integer"
                },
                "p95_duration_ms": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "requests": {
                  "type": "integer"
                },
                "response_chars": {
                  "type": "integer"
                },
                "success": {
                  "type": "integer"
                },
                "tool_argument_chars": {
                  "type": "integer"
                },
                "unique_tools": {
                  "type": "integer"
                },
                "unique_users": {
                  "type": "integer"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "timezone": {
            "enum": [
              "UTC"
            ],
            "type": "string"
          },
          "to": {
            "format": "date-time",
            "type": "string"
          },
          "totals": {
            "additionalProperties": true,
            "description": "Rows also carry period_start (unless granularity is total) and one field per group_by dimension (mcp rows add mcp_name).",
            "properties": {
              "avg_duration_ms": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "blocked": {
                "type": "integer"
              },
              "errors": {
                "type": "integer"
              },
              "p95_duration_ms": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "requests": {
                "type": "integer"
              },
              "response_chars": {
                "type": "integer"
              },
              "success": {
                "type": "integer"
              },
              "tool_argument_chars": {
                "type": "integer"
              },
              "unique_tools": {
                "type": "integer"
              },
              "unique_users": {
                "type": "integer"
              }
            },
            "type": "object"
          }
        },
        "required": [
          "from",
          "totals",
          "rows",
          "next_cursor",
          "request_id"
        ],
        "type": "object"
      },
      "UserConnections": {
        "additionalProperties": true,
        "properties": {
          "generated_at": {
            "format": "date-time",
            "type": "string"
          },
          "items": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "email": {
                  "type": "string"
                },
                "mcp_states": {
                  "additionalProperties": {
                    "type": "integer"
                  },
                  "description": "Number of MCPs in each state.",
                  "type": "object"
                },
                "registered_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "user_types": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "required": [
                "email",
                "mcp_states"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "items",
          "next_cursor",
          "request_id"
        ],
        "type": "object"
      },
      "UserMcpConnections": {
        "additionalProperties": true,
        "properties": {
          "email": {
            "type": "string"
          },
          "generated_at": {
            "format": "date-time",
            "type": "string"
          },
          "items": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "access_allowed": {
                  "type": "boolean"
                },
                "can_renew": {
                  "type": [
                    "boolean",
                    "null"
                  ]
                },
                "mcp_id": {
                  "type": "string"
                },
                "name": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "preference_enabled": {
                  "type": "boolean"
                },
                "set_up_at": {
                  "format": "date-time",
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "signed_in_until": {
                  "format": "date-time",
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "slug": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "state": {
                  "enum": [
                    "signed_in",
                    "available",
                    "needs_sign_in",
                    "sign_in_not_finished",
                    "not_signed_in_yet",
                    "turned_off_by_user",
                    "blocked_by_access_rules",
                    "mcp_turned_off"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "mcp_id",
                "state"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          }
        },
        "required": [
          "items",
          "next_cursor",
          "email",
          "request_id"
        ],
        "type": "object"
      },
      "UsersReport": {
        "additionalProperties": true,
        "properties": {
          "data_through": {
            "description": "End of the data the report covers.",
            "format": "date-time",
            "type": "string"
          },
          "from": {
            "format": "date-time",
            "type": "string"
          },
          "generated_at": {
            "format": "date-time",
            "type": "string"
          },
          "mcp_id": {
            "description": "Present on GET /mcps/{mcp_id}/usage.",
            "type": "string"
          },
          "next_cursor": {
            "description": "Pass as cursor for the next page; null on the last page.",
            "type": [
              "string",
              "null"
            ]
          },
          "request_id": {
            "description": "Request correlation id (also in X-Request-ID).",
            "type": "string"
          },
          "row_count": {
            "type": "integer"
          },
          "rows": {
            "items": {
              "additionalProperties": true,
              "properties": {
                "blocked": {
                  "type": "integer"
                },
                "calls": {
                  "type": "integer"
                },
                "errors": {
                  "type": "integer"
                },
                "first_seen": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "last_seen": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "mcps_used": {
                  "type": "integer"
                },
                "success": {
                  "type": "integer"
                },
                "tools_used": {
                  "type": "integer"
                },
                "user": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "timezone": {
            "enum": [
              "UTC"
            ],
            "type": "string"
          },
          "to": {
            "format": "date-time",
            "type": "string"
          },
          "totals": {
            "type": "object"
          }
        },
        "required": [
          "from",
          "totals",
          "rows",
          "next_cursor",
          "request_id"
        ],
        "type": "object"
      },
      "WebSearchPolicySettings": {
        "additionalProperties": false,
        "description": "Web search policy of the Quilr web search MCP: per smart group domain exclusions and URL category overrides.",
        "properties": {
          "group_excluded_domains": {
            "additionalProperties": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "type": "object"
          },
          "zia_check_timeout_seconds": {
            "maximum": 30.0,
            "minimum": 1.0,
            "type": "number"
          },
          "zia_url_overrides": {
            "items": {
              "$ref": "#/components/schemas/ZiaUrlOverrideRule"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "ZiaUrlOverrideRule": {
        "additionalProperties": false,
        "description": "One URL category override rule for specific domains.",
        "properties": {
          "action": {
            "enum": [
              "allow",
              "block"
            ],
            "type": "string"
          },
          "domain_patterns": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "scope_name": {
            "type": "string"
          },
          "scope_names": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "scope_type": {
            "enum": [
              "global",
              "zia_group",
              "zia_department"
            ],
            "type": "string"
          }
        },
        "required": [
          "scope_type",
          "action"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "ManagementKey": {
        "bearerFormat": "qmcpmgmt_",
        "description": "Management key issued by a tenant administrator (secrets start with `qmcpmgmt_`). A key belongs to one tenant and carries scopes; each operation lists the scopes it needs in x-scopes. Writes run as the administrator who issued the key.",
        "scheme": "bearer",
        "type": "http"
      },
      "TenantAdminJWT": {
        "bearerFormat": "JWT",
        "description": "Tenant administrator token (the Quilr console session). The tenant in the path must be the administrator's tenant. Management keys are not accepted here.",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Manage the MCPs of a Quilr MCP Gateway tenant programmatically: inventory, creation and removal, settings, upstream credentials, tool reviews, OAuth connections and analytics.\n\n**Authentication.** A tenant administrator enables management for the tenant and issues management keys in the Quilr console (MCP Gateway, Management API tab) or with the Administration endpoints (tenant administrator token). Every other endpoint takes a management key as `Authorization: Bearer qmcpmgmt_...`. Each operation lists the scopes it always requires in `x-scopes`; `x-conditional-scopes` lists scopes that are added when the request body carries credentials or settings. An empty `x-scopes` on an Administration operation means a tenant administrator token.\n\n**Writes.** Changes to an existing MCP configuration require `If-Match` with the quoted `version` (ETag) from the latest read (`428` when missing, `412` when stale). Creates take an `Idempotency-Key`; retrying with the same key within 24 hours returns the original result instead of creating twice.\n\n**Responses.** Every JSON response carries `request_id` (also in `X-Request-ID`) and `Cache-Control: no-store`. Errors use `{\"error\": {\"code\", \"message\", ...}, \"request_id\"}`; `error.fields` names the offending request paths (analytics reports: an object keyed by query parameter) and never echoes submitted values. Lists are paginated with `limit` and an opaque `cursor` (`next_cursor` is null on the last page). Timestamps are UTC RFC 3339 (`...Z`).\n\n**Policy.** When QuilrQL policies govern the tenant, stored MCP settings are saved but not enforced until the policy engine is turned off; responses flag this with an `inactive_under_quilrql` warning.",
    "title": "MCP Gateway Management API",
    "version": "1.0.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/mcpgateway/management-admin/v1/tenants/{tenant_id}/keys": {
      "get": {
        "description": "Every management key of the tenant (active, expired and revoked), without secrets.",
        "operationId": "List_management_keys",
        "parameters": [
          {
            "description": "Your tenant id; must be the administrator's tenant.",
            "example": "tenant-123",
            "in": "path",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Page size, 1 to 200 (default 50).",
            "example": 50,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "items": [
                    {
                      "created_at": "2026-11-14T09:00:00Z",
                      "expires_at": "2027-01-01T00:00:00Z",
                      "fingerprint": "9c1e5a77b0d24f13",
                      "key_id": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
                      "last_used_at": null,
                      "name": "CI automation",
                      "owner_user_id": "42",
                      "revoked_at": null,
                      "scopes": [
                        "mcps:write",
                        "read",
                        "settings:write"
                      ],
                      "status": "active",
                      "version": "k3f1c0a9e5b7d2c4e6a8b0c1d2e3f4a5b"
                    }
                  ],
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ManagementKeyList"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "TenantAdminJWT": []
          }
        ],
        "summary": "List management keys",
        "tags": [
          "Administration"
        ],
        "x-scopes": []
      },
      "post": {
        "description": "Issues a key owned by the calling administrator; writes made with the key act as that administrator. The secret is returned once in `key.secret`. Requires management to be enabled for the tenant. Requires an Idempotency-Key; retrying with the same key and body within 24 hours returns the original response, a different body under the same key is 409 `idempotency_conflict`.",
        "operationId": "Issue_a_management_key",
        "parameters": [
          {
            "description": "Your tenant id; must be the administrator's tenant.",
            "example": "tenant-123",
            "in": "path",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Client-chosen token (1 to 200 characters) that makes retries safe: the same token and body within 24 hours returns the original response.",
            "example": "create-files-mcp-2026-11-14",
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "maxLength": 200,
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "expires_at": "2027-01-01T00:00:00Z",
                "name": "CI automation",
                "scopes": [
                  "read",
                  "mcps:write",
                  "settings:write"
                ]
              },
              "schema": {
                "$ref": "#/components/schemas/ManagementKeyCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "example": {
                  "key": {
                    "created_at": "2026-11-14T09:00:00Z",
                    "expires_at": "2027-01-01T00:00:00Z",
                    "fingerprint": "9c1e5a77b0d24f13",
                    "key_id": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
                    "last_used_at": null,
                    "name": "CI automation",
                    "owner_user_id": "42",
                    "revoked_at": null,
                    "scopes": [
                      "mcps:write",
                      "read",
                      "settings:write"
                    ],
                    "secret": "qmcpmgmt_<secret>",
                    "status": "active",
                    "version": "k3f1c0a9e5b7d2c4e6a8b0c1d2e3f4a5b"
                  },
                  "operation_id": "8e4a5b6c-7d8e-9f0a-1b2c-3d4e5f607182",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ManagementKeyCreated"
                }
              }
            },
            "description": "Created",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "TenantAdminJWT": []
          }
        ],
        "summary": "Issue a management key",
        "tags": [
          "Administration"
        ],
        "x-scopes": []
      }
    },
    "/mcpgateway/management-admin/v1/tenants/{tenant_id}/keys/{key_id}": {
      "delete": {
        "description": "Revokes the key immediately and permanently. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Revoke_a_management_key",
        "parameters": [
          {
            "description": "Your tenant id; must be the administrator's tenant.",
            "example": "tenant-123",
            "in": "path",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Management key id.",
            "example": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
            "in": "path",
            "name": "key_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Empty"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "key": {
                    "created_at": "2026-11-14T09:00:00Z",
                    "expires_at": "2027-01-01T00:00:00Z",
                    "fingerprint": "9c1e5a77b0d24f13",
                    "key_id": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
                    "last_used_at": null,
                    "name": "CI automation",
                    "owner_user_id": "42",
                    "revoked_at": "2026-11-14T10:00:00Z",
                    "scopes": [
                      "mcps:write",
                      "read",
                      "settings:write"
                    ],
                    "status": "revoked",
                    "version": "k3f1c0a9e5b7d2c4e6a8b0c1d2e3f4a5b"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ManagementKeyResponse"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "TenantAdminJWT": []
          }
        ],
        "summary": "Revoke a management key",
        "tags": [
          "Administration"
        ],
        "x-scopes": []
      },
      "get": {
        "description": "Key metadata, never the secret.",
        "operationId": "Read_a_management_key",
        "parameters": [
          {
            "description": "Your tenant id; must be the administrator's tenant.",
            "example": "tenant-123",
            "in": "path",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Management key id.",
            "example": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
            "in": "path",
            "name": "key_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "key": {
                    "created_at": "2026-11-14T09:00:00Z",
                    "expires_at": "2027-01-01T00:00:00Z",
                    "fingerprint": "9c1e5a77b0d24f13",
                    "key_id": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
                    "last_used_at": null,
                    "name": "CI automation",
                    "owner_user_id": "42",
                    "revoked_at": null,
                    "scopes": [
                      "mcps:write",
                      "read",
                      "settings:write"
                    ],
                    "status": "active",
                    "version": "k3f1c0a9e5b7d2c4e6a8b0c1d2e3f4a5b"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ManagementKeyResponse"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "TenantAdminJWT": []
          }
        ],
        "summary": "Read a management key",
        "tags": [
          "Administration"
        ],
        "x-scopes": []
      },
      "patch": {
        "description": "Changes the name, scopes or expiry of an active key. Narrowed scopes apply to requests already waiting. Revoked and expired keys cannot be changed (409 `terminal_key_state`). Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Update_a_management_key",
        "parameters": [
          {
            "description": "Your tenant id; must be the administrator's tenant.",
            "example": "tenant-123",
            "in": "path",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Management key id.",
            "example": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
            "in": "path",
            "name": "key_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "scopes": [
                  "read"
                ]
              },
              "schema": {
                "$ref": "#/components/schemas/ManagementKeyPatch"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "key": {
                    "created_at": "2026-11-14T09:00:00Z",
                    "expires_at": "2027-01-01T00:00:00Z",
                    "fingerprint": "9c1e5a77b0d24f13",
                    "key_id": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
                    "last_used_at": null,
                    "name": "CI automation",
                    "owner_user_id": "42",
                    "revoked_at": null,
                    "scopes": [
                      "read"
                    ],
                    "status": "active",
                    "version": "k3f1c0a9e5b7d2c4e6a8b0c1d2e3f4a5b"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ManagementKeyResponse"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "TenantAdminJWT": []
          }
        ],
        "summary": "Update a management key",
        "tags": [
          "Administration"
        ],
        "x-scopes": []
      }
    },
    "/mcpgateway/management-admin/v1/tenants/{tenant_id}/settings": {
      "get": {
        "description": "Whether management keys may be used for this tenant.",
        "operationId": "Read_tenant_management_settings",
        "parameters": [
          {
            "description": "Your tenant id; must be the administrator's tenant.",
            "example": "tenant-123",
            "in": "path",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "enabled": false,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "tenant_id": "tenant-123",
                  "updated_at": null,
                  "version": "t0a1b2c3d4e5f60718293a4b5c6d7e8f9"
                },
                "schema": {
                  "$ref": "#/components/schemas/TenantSettings"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "TenantAdminJWT": []
          }
        ],
        "summary": "Read tenant management settings",
        "tags": [
          "Administration"
        ],
        "x-scopes": []
      },
      "patch": {
        "description": "Enables management for the tenant, or suspends it (every key then answers 403 `management_disabled_for_tenant` until it is enabled again). Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Enable_or_suspend_tenant_management",
        "parameters": [
          {
            "description": "Your tenant id; must be the administrator's tenant.",
            "example": "tenant-123",
            "in": "path",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "enabled": true
              },
              "schema": {
                "$ref": "#/components/schemas/TenantSettingsPatch"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "enabled": true,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "tenant_id": "tenant-123",
                  "updated_at": "2026-11-14T08:55:00Z",
                  "version": "t9f8e7d6c5b4a39281706f5e4d3c2b1a0"
                },
                "schema": {
                  "$ref": "#/components/schemas/TenantSettings"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "TenantAdminJWT": []
          }
        ],
        "summary": "Enable or suspend management",
        "tags": [
          "Administration"
        ],
        "x-scopes": []
      }
    },
    "/mcpgateway/management/v1/agents": {
      "get": {
        "description": "Built-in and custom agents. Each is matched against the client User-Agent.",
        "operationId": "List_agents",
        "parameters": [
          {
            "description": "Page size, 1 to 200 (default 50).",
            "example": 50,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "items": [
                    {
                      "created_at": null,
                      "custom": false,
                      "display_name": "Cursor",
                      "keyword": "cursor"
                    }
                  ],
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/AgentList"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List agents",
        "tags": [
          "Client access"
        ],
        "x-scopes": [
          "read"
        ]
      },
      "post": {
        "description": "Adds an agent for an in-house client. It is allowed on every MCP of the tenant. 409 `agent_exists` when the keyword is taken by a built-in or custom agent.",
        "operationId": "Create_a_custom_agent",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "display_name": "Acme Bot",
                "keyword": "acme-bot"
              },
              "schema": {
                "$ref": "#/components/schemas/AgentCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "example": {
                  "agent": {
                    "created_at": "2026-11-14T09:00:00Z",
                    "custom": true,
                    "display_name": "Acme Bot",
                    "keyword": "acme-bot"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "additionalProperties": true,
                  "properties": {
                    "agent": {
                      "$ref": "#/components/schemas/Agent"
                    },
                    "request_id": {
                      "description": "Request correlation id (also in X-Request-ID).",
                      "type": "string"
                    }
                  },
                  "required": [
                    "agent",
                    "request_id"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Created",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Create a custom agent",
        "tags": [
          "Client access"
        ],
        "x-scopes": [
          "agents:write"
        ]
      }
    },
    "/mcpgateway/management/v1/agents/{keyword}": {
      "delete": {
        "description": "Deletes the custom agent and removes it from every MCP. Built-in agents answer 409 `built_in_agent`.",
        "operationId": "Delete_a_custom_agent",
        "parameters": [
          {
            "description": "Agent keyword from `GET /agents`.",
            "example": "acme-bot",
            "in": "path",
            "name": "keyword",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Empty"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agent": {
                    "deleted": true,
                    "keyword": "acme-bot"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/AgentDeleted"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Delete a custom agent",
        "tags": [
          "Client access"
        ],
        "x-scopes": [
          "agents:write"
        ]
      },
      "get": {
        "description": "The agent and, for every MCP, whether it may use it.",
        "operationId": "Read_an_agent",
        "parameters": [
          {
            "description": "Agent keyword from `GET /agents`.",
            "example": "acme-bot",
            "in": "path",
            "name": "keyword",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agent": {
                    "created_at": null,
                    "custom": false,
                    "display_name": "Cursor",
                    "keyword": "cursor",
                    "mcps": [
                      {
                        "enabled": true,
                        "mcp_id": "a1b2c3d4",
                        "name": "Files"
                      }
                    ]
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/AgentResponse"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read an agent",
        "tags": [
          "Client access"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/api-access/presets": {
      "get": {
        "description": "Named starting points for access rules, such as read only.",
        "operationId": "List_access_presets",
        "parameters": [],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "presets": {
                    "everything": {
                      "allow": [],
                      "deny": []
                    },
                    "no_deletes": {
                      "allow": [],
                      "deny": [
                        {
                          "methods": [
                            "DELETE"
                          ]
                        }
                      ]
                    },
                    "read_only": {
                      "allow": [
                        {
                          "methods": [
                            "GET",
                            "HEAD"
                          ]
                        }
                      ],
                      "deny": []
                    }
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiAccessPresets"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List access rule presets",
        "tags": [
          "REST API MCPs"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/api-access/test": {
      "post": {
        "description": "Evaluates rules you have not saved against one request.",
        "operationId": "Test_access_rules",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "access": {
                  "deny": [
                    {
                      "methods": [
                        "DELETE"
                      ]
                    }
                  ]
                },
                "method": "DELETE",
                "path": "/pets/1"
              },
              "schema": {
                "$ref": "#/components/schemas/ApiRuleTest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "decision": {
                    "allowed": false,
                    "index": 0,
                    "list": "deny",
                    "reason": "blocked by connector rule deny[0]: DELETE"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiAccessDecision"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Test candidate access rules",
        "tags": [
          "REST API MCPs"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/audit": {
      "get": {
        "description": "Configuration changes of your tenant, newest first, made in the Quilr console (`via` ui) or through this API (`via` management_api, with the key id). Events carry who, what and when, and the names of changed fields when recorded; never the before or after values. `action` and `resource_type` are the same identifiers the Quilr console audit page shows. Filters: `actor`, `action`, `resource_type`, `resource_id`, `via`, `since` and `until`. New events never invalidate a cursor.",
        "operationId": "List_audit_events",
        "parameters": [
          {
            "description": "Page size, 1 to 200 (default 50).",
            "example": 50,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exact actor email (case-insensitive).",
            "in": "query",
            "name": "actor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exact action as recorded, for example management_key_created.",
            "example": "management_key_created",
            "in": "query",
            "name": "action",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exact resource type as recorded.",
            "in": "query",
            "name": "resource_type",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exact resource id, for example an MCP id.",
            "in": "query",
            "name": "resource_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "ui: changes made in the Quilr console; management_api: changes made through this API.",
            "in": "query",
            "name": "via",
            "required": false,
            "schema": {
              "enum": [
                "ui",
                "management_api"
              ],
              "type": "string"
            }
          },
          {
            "description": "Inclusive start: RFC 3339 time with a timezone.",
            "in": "query",
            "name": "since",
            "required": false,
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "Exclusive end: RFC 3339 time with a timezone.",
            "in": "query",
            "name": "until",
            "required": false,
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "items": [
                    {
                      "action": "management_key_updated",
                      "actor_email": "admin@example.com",
                      "actor_role": "admin",
                      "changed_fields": null,
                      "created_at": "2026-11-14T09:05:12Z",
                      "event_id": "3c9a1f2e-7b6d-4e5f-8a9b-0c1d2e3f4a5b",
                      "management_key_id": null,
                      "operation_id": null,
                      "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                      "resource_id": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
                      "resource_name": "CI automation",
                      "resource_type": "management_key",
                      "result": null,
                      "via": "management_api"
                    }
                  ],
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/AuditList"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List audit events",
        "tags": [
          "Audit"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/capabilities": {
      "get": {
        "description": "What this deployment supports: every scope, the calling key's id and scopes (`caller`), limits, settings sections, authentication types, connection states, create options and analytics dimensions. Use it to build forms and to hide actions the caller cannot perform.",
        "operationId": "Read_capabilities",
        "parameters": [],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "api_version": "v1",
                  "auth_types": [
                    "api_key",
                    "no_auth",
                    "oauth",
                    "oauth_passthrough"
                  ],
                  "caller": {
                    "key_id": "0f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
                    "scopes": [
                      "read"
                    ]
                  },
                  "connection_states": [
                    "fetch_failed",
                    "pending_connection",
                    "pending_first_client",
                    "ready"
                  ],
                  "limits": {
                    "idempotency_replay_hours": 24,
                    "max_body_bytes": 1048576,
                    "page_limit_default": 50,
                    "page_limit_max": 200
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "scopes": [
                    "agents:write",
                    "connections:write",
                    "credentials:write",
                    "mcps:write",
                    "read",
                    "settings:write",
                    "tenant_settings:write",
                    "tokens:write",
                    "tool_reviews:write",
                    "tools:write"
                  ],
                  "tenant_id": "tenant-123"
                },
                "schema": {
                  "$ref": "#/components/schemas/Capabilities"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read capabilities",
        "tags": [
          "Reference"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/catalog": {
      "get": {
        "description": "Catalog MCPs with this tenant's install state. Filters: `query` (search), `install_status` and `auth_type`. `install_requirements` lists the values an install needs.",
        "operationId": "List_catalog",
        "parameters": [
          {
            "description": "Page size, 1 to 200 (default 50).",
            "example": 50,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search text matched against catalog names and descriptions (at most 256 characters).",
            "in": "query",
            "name": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "installed or not_installed for your tenant.",
            "in": "query",
            "name": "install_status",
            "required": false,
            "schema": {
              "enum": [
                "installed",
                "not_installed"
              ],
              "type": "string"
            }
          },
          {
            "description": "Catalog authentication kind.",
            "in": "query",
            "name": "auth_type",
            "required": false,
            "schema": {
              "enum": [
                "oauth",
                "api_key",
                "passthrough",
                "oauth_passthrough",
                "no_auth",
                "none"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "items": [
                    {
                      "auth_type": "oauth_dcr",
                      "category": "Developer tools",
                      "created_at": null,
                      "custom_oauth_credentials_required": false,
                      "description": "Repositories, issues and pull requests",
                      "icon": null,
                      "id": "github",
                      "install_requirements": [],
                      "installed": false,
                      "is_custom": false,
                      "mcp_id": null,
                      "mcp_status": null,
                      "name": "GitHub",
                      "oauth_with_login": false,
                      "requires_configuration": false,
                      "transport": "https://api.githubcopilot.com/mcp/",
                      "upstream_auth": null
                    }
                  ],
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/CatalogList"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List the MCP Library",
        "tags": [
          "Catalog"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/catalog/{catalog_id}": {
      "get": {
        "description": "One catalog MCP with its install requirements and this tenant's install state.",
        "operationId": "Read_catalog_entry",
        "parameters": [
          {
            "description": "Catalog entry id from `GET /catalog`.",
            "example": "github",
            "in": "path",
            "name": "catalog_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "catalog_entry": {
                    "auth_type": "oauth_dcr",
                    "category": "Developer tools",
                    "created_at": null,
                    "custom_oauth_credentials_required": false,
                    "description": "Repositories, issues and pull requests",
                    "icon": null,
                    "id": "github",
                    "install_requirements": [],
                    "installed": false,
                    "is_custom": false,
                    "mcp_id": null,
                    "mcp_status": null,
                    "name": "GitHub",
                    "oauth_with_login": false,
                    "requires_configuration": false,
                    "transport": "https://api.githubcopilot.com/mcp/",
                    "upstream_auth": null
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/CatalogEntryResponse"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read a catalog entry",
        "tags": [
          "Catalog"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/catalog/{catalog_id}/install": {
      "post": {
        "description": "Installs a catalog MCP for the tenant (once per tenant: 409 `already_installed`). Supply the values listed in `install_requirements`; missing ones answer 422 `install_input_required` with `missing_fields`. OAuth catalog MCPs return a `connect` link. Requires an Idempotency-Key; retrying with the same key and body within 24 hours returns the original response, a different body under the same key is 409 `idempotency_conflict`.",
        "operationId": "Install_catalog_mcp",
        "parameters": [
          {
            "description": "Catalog entry id from `GET /catalog`.",
            "example": "github",
            "in": "path",
            "name": "catalog_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Client-chosen token (1 to 200 characters) that makes retries safe: the same token and body within 24 hours returns the original response.",
            "example": "create-files-mcp-2026-11-14",
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "maxLength": 200,
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "examples": {
                "none": {
                  "summary": "No inputs needed",
                  "value": {}
                },
                "token": {
                  "summary": "Catalog MCP that needs an API key",
                  "value": {
                    "auth_token": "<token>"
                  }
                }
              },
              "schema": {
                "$ref": "#/components/schemas/CatalogInstall"
              }
            }
          },
          "required": false
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "example": {
                  "connect": {
                    "expires_at": "2026-11-14T10:15:00Z",
                    "url": "https://mcpgateway.example.com/mcpgateway/management-connect#t=<token>"
                  },
                  "connection": {
                    "auth_type": "oauth",
                    "oauth_mode": "dcr",
                    "state": "pending_connection",
                    "tool_count": 0
                  },
                  "mcp": {
                    "auth_type": "oauth",
                    "catalog_id": "github",
                    "connection_state": "pending_connection",
                    "created_at": "2026-11-02T09:15:00Z",
                    "description": null,
                    "enabled": true,
                    "endpoint_urls": {
                      "mcp": "https://mcpgateway.example.com/files/mcp"
                    },
                    "execution_type": "remote",
                    "id": "e5f6a7b8",
                    "name": "GitHub",
                    "oauth_mode": "dcr",
                    "remote_connector": null,
                    "slug": "quilr-ai-github",
                    "source": "catalog",
                    "tool_count": 0,
                    "transport_type": "http",
                    "upstream_host": "https://tracker.example.com",
                    "version": "r1"
                  },
                  "operation_id": "7d3f4a5b-6c7d-8e9f-0a1b-2c3d4e5f6071",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "warnings": []
                },
                "schema": {
                  "$ref": "#/components/schemas/McpCreated"
                }
              }
            },
            "description": "Created",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Install a catalog MCP",
        "tags": [
          "Catalog"
        ],
        "x-conditional-scopes": [
          {
            "scope": "credentials:write",
            "when": "The body carries `auth_token`, `oauth_client_id`, `oauth_client_secret`, `upstream_auth_extra_headers`, `upstream_auth_extra_query_params` or `transport_values`."
          }
        ],
        "x-scopes": [
          "mcps:write"
        ]
      }
    },
    "/mcpgateway/management/v1/dlp/summary": {
      "get": {
        "description": "Per-request DLP totals by direction (scanned, flagged, blocked) and, reported separately so they never inflate request totals, per-category detection counts.",
        "operationId": "Read_dlp_summary",
        "parameters": [
          {
            "description": "Inclusive start: RFC 3339 time with a timezone, or a date (UTC midnight). Default: UTC midnight 7 days before `to`. At most 92 days before `to`.",
            "example": "2026-11-01",
            "in": "query",
            "name": "from",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exclusive end: RFC 3339 time with a timezone, or a date (through the end of that UTC day). Default: now.",
            "example": "2026-11-08",
            "in": "query",
            "name": "to",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Period of each row: total (default), month, week, day or hour (hour covers at most 14 days). Periods start on UTC boundaries.",
            "example": "day",
            "in": "query",
            "name": "granularity",
            "required": false,
            "schema": {
              "enum": [
                "total",
                "month",
                "week",
                "day",
                "hour"
              ],
              "type": "string"
            }
          },
          {
            "description": "Up to two comma-separated dimensions: mcp, tool, user, category, direction.",
            "example": "mcp",
            "in": "query",
            "name": "group_by",
            "required": false,
            "schema": {
              "description": "Comma-separated, any of: mcp, tool, user, category, direction",
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. MCP ids.",
            "in": "query",
            "name": "mcp",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact tool values.",
            "in": "query",
            "name": "tool",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. User emails (case-insensitive).",
            "in": "query",
            "name": "user",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact category values.",
            "in": "query",
            "name": "category",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. input or output.",
            "in": "query",
            "name": "direction",
            "required": false,
            "schema": {
              "description": "Comma-separated, any of: input, output",
              "type": "string"
            }
          },
          {
            "description": "Row order: period, requests, flagged, blocked.",
            "in": "query",
            "name": "sort",
            "required": false,
            "schema": {
              "enum": [
                "period",
                "requests",
                "flagged",
                "blocked"
              ],
              "type": "string"
            }
          },
          {
            "description": "Rows per page, 1 to 5000 (default 500).",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 500,
              "maximum": 5000,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page of the same query. 409 `collection_changed` when the result was recomputed and differs.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "categories": [
                    {
                      "blocked": 0,
                      "category": "email_address",
                      "detections": 57,
                      "requests": 21
                    }
                  ],
                  "categories_truncated": false,
                  "data_through": "2026-11-14T00:00:00Z",
                  "directions": [
                    "input",
                    "output"
                  ],
                  "from": "2026-11-07T00:00:00Z",
                  "generated_at": "2026-11-14T09:00:02Z",
                  "granularity": "total",
                  "group_by": [],
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "row_count": 1,
                  "rows": [],
                  "timezone": "UTC",
                  "to": "2026-11-14T00:00:00Z",
                  "totals": {
                    "blocked": 8,
                    "flagged": 44,
                    "input": {
                      "blocked": 6,
                      "flagged": 30,
                      "scanned": 1840
                    },
                    "output": {
                      "blocked": 2,
                      "flagged": 14,
                      "scanned": 1790
                    },
                    "requests": 1840
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/DlpReport"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "DLP summary",
        "tags": [
          "Analytics"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/latency": {
      "get": {
        "description": "Call duration percentiles (p50, p90, p95, p99), average, maximum and a fixed-edge histogram per period and dimension.",
        "operationId": "Read_latency",
        "parameters": [
          {
            "description": "Inclusive start: RFC 3339 time with a timezone, or a date (UTC midnight). Default: UTC midnight 7 days before `to`. At most 92 days before `to`.",
            "example": "2026-11-01",
            "in": "query",
            "name": "from",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exclusive end: RFC 3339 time with a timezone, or a date (through the end of that UTC day). Default: now.",
            "example": "2026-11-08",
            "in": "query",
            "name": "to",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Period of each row: total (default), month, week, day or hour (hour covers at most 14 days). Periods start on UTC boundaries.",
            "example": "day",
            "in": "query",
            "name": "granularity",
            "required": false,
            "schema": {
              "enum": [
                "total",
                "month",
                "week",
                "day",
                "hour"
              ],
              "type": "string"
            }
          },
          {
            "description": "Up to two comma-separated dimensions: mcp, tool, transport, outcome.",
            "example": "mcp",
            "in": "query",
            "name": "group_by",
            "required": false,
            "schema": {
              "description": "Comma-separated, any of: mcp, tool, transport, outcome",
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. MCP ids.",
            "in": "query",
            "name": "mcp",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact tool values.",
            "in": "query",
            "name": "tool",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. User emails (case-insensitive).",
            "in": "query",
            "name": "user",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact agent values.",
            "in": "query",
            "name": "agent",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact called via values.",
            "in": "query",
            "name": "called_via",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact auth mode values.",
            "in": "query",
            "name": "auth_mode",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact transport values.",
            "in": "query",
            "name": "transport",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. One of success, error, blocked.",
            "in": "query",
            "name": "outcome",
            "required": false,
            "schema": {
              "description": "Comma-separated, any of: success, error, blocked",
              "type": "string"
            }
          },
          {
            "description": "Row order: period, requests, p50, p95, p99, avg.",
            "in": "query",
            "name": "sort",
            "required": false,
            "schema": {
              "enum": [
                "period",
                "requests",
                "p50",
                "p95",
                "p99",
                "avg"
              ],
              "type": "string"
            }
          },
          {
            "description": "Rows per page, 1 to 5000 (default 500).",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 500,
              "maximum": 5000,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page of the same query. 409 `collection_changed` when the result was recomputed and differs.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data_through": "2026-11-14T00:00:00Z",
                  "from": "2026-11-07T00:00:00Z",
                  "generated_at": "2026-11-14T09:00:02Z",
                  "granularity": "total",
                  "group_by": [],
                  "histogram_edges_ms": [
                    25,
                    50,
                    100,
                    250,
                    500,
                    1000,
                    2500,
                    5000,
                    10000,
                    30000,
                    60000
                  ],
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "row_count": 1,
                  "rows": [
                    {
                      "avg_ms": 412.5,
                      "count": 1838,
                      "histogram": [
                        80,
                        210,
                        390,
                        520,
                        300,
                        190,
                        100,
                        30,
                        12,
                        4,
                        2,
                        0
                      ],
                      "max_ms": 29011.0,
                      "p50_ms": 230.0,
                      "p90_ms": 980.0,
                      "p95_ms": 1630.0,
                      "p99_ms": 4100.0,
                      "requests": 1840
                    }
                  ],
                  "timezone": "UTC",
                  "to": "2026-11-14T00:00:00Z",
                  "totals": {
                    "avg_ms": 412.5,
                    "count": 1838,
                    "histogram": [
                      80,
                      210,
                      390,
                      520,
                      300,
                      190,
                      100,
                      30,
                      12,
                      4,
                      2,
                      0
                    ],
                    "max_ms": 29011.0,
                    "p50_ms": 230.0,
                    "p90_ms": 980.0,
                    "p95_ms": 1630.0,
                    "p99_ms": 4100.0,
                    "requests": 1840
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/LatencyReport"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Latency report",
        "tags": [
          "Analytics"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcp-requests": {
      "get": {
        "description": "Pending requests from users for MCP Library entries, newest first, with what installing each entry needs. Installing the entry (POST /catalog/{catalog_id}/install) resolves every pending request for it.",
        "operationId": "List_MCP_requests",
        "parameters": [
          {
            "description": "Page size, 1 to 200 (default 50).",
            "example": 50,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "items": [
                    {
                      "catalog_id": "github",
                      "catalog_name": "GitHub",
                      "created_at": "2026-11-13T16:00:00Z",
                      "install_requirements": [],
                      "request_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
                      "requires_configuration": false,
                      "resolved_at": null,
                      "status": "pending",
                      "user_email": "dana@example.com"
                    }
                  ],
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/McpRequestList"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List users' MCP requests",
        "tags": [
          "Tenant"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcp-requests/{request_id}/dismiss": {
      "post": {
        "description": "Dismisses one pending request. Dismissing twice is a no-op; a request already resolved by an install answers 409 `request_not_pending`.",
        "operationId": "Dismiss_an_MCP_request",
        "parameters": [
          {
            "description": "Request id (`request_id` from `GET /mcp-requests`).",
            "example": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
            "in": "path",
            "name": "request_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Empty"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "request": {
                    "catalog_id": "github",
                    "catalog_name": "GitHub",
                    "created_at": "2026-11-13T16:00:00Z",
                    "request_id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
                    "resolved_at": "2026-11-14T09:00:00Z",
                    "status": "dismissed",
                    "user_email": "dana@example.com"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/McpRequestResponse"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Dismiss an MCP request",
        "tags": [
          "Tenant"
        ],
        "x-scopes": [
          "tenant_settings:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps": {
      "get": {
        "description": "Enabled and disabled MCPs of the tenant, sorted by name. Filters: `name` (case-insensitive substring), `slug`, `enabled`, `auth_type`, `transport_type` and `source`. `tool_count` and `connection_state` are live values; they never invalidate a cursor.",
        "operationId": "List_mcps",
        "parameters": [
          {
            "description": "Page size, 1 to 200 (default 50).",
            "example": 50,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Case-insensitive substring of the MCP name.",
            "in": "query",
            "name": "name",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exact slug.",
            "in": "query",
            "name": "slug",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "true or false.",
            "in": "query",
            "name": "enabled",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "description": "Authentication the MCP uses upstream.",
            "in": "query",
            "name": "auth_type",
            "required": false,
            "schema": {
              "enum": [
                "api_key",
                "no_auth",
                "oauth",
                "oauth_passthrough"
              ],
              "type": "string"
            }
          },
          {
            "description": "Exact transport type: http or sse.",
            "in": "query",
            "name": "transport_type",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "How the MCP was added: custom, catalog (MCP Library), api (REST API) or system (provided by Quilr).",
            "in": "query",
            "name": "source",
            "required": false,
            "schema": {
              "enum": [
                "api",
                "catalog",
                "custom",
                "system"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "items": [
                    {
                      "auth_type": "api_key",
                      "catalog_id": null,
                      "connection_state": "ready",
                      "created_at": "2026-11-02T09:15:00Z",
                      "description": "Company file server",
                      "enabled": true,
                      "endpoint_urls": {
                        "mcp": "https://mcpgateway.example.com/files/mcp"
                      },
                      "execution_type": "remote",
                      "id": "a1b2c3d4",
                      "name": "Files",
                      "oauth_mode": null,
                      "remote_connector": null,
                      "slug": "files",
                      "source": "custom",
                      "tool_count": 12,
                      "transport_type": "http",
                      "upstream_host": "https://files.example.com",
                      "version": "r4"
                    }
                  ],
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/McpList"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List MCPs",
        "tags": [
          "MCPs"
        ],
        "x-scopes": [
          "read"
        ]
      },
      "post": {
        "description": "Registers a remote MCP server by URL and fetches its tools. `auth.type` selects upstream authentication; credentials are shared by all users of the tenant. OAuth MCPs are created with `connection_state` pending_connection and a single-use `connect` link that finishes the sign-in for the key owner when opened (no Quilr sign-in; share it only with the person who should connect) (oauth_passthrough MCPs need no link: each client brings its own token). `settings` (settings:write) and `enabled` apply before the MCP is returned. Requires an Idempotency-Key; retrying with the same key and body within 24 hours returns the original response, a different body under the same key is 409 `idempotency_conflict`.",
        "operationId": "Create_an_mcp",
        "parameters": [
          {
            "description": "Client-chosen token (1 to 200 characters) that makes retries safe: the same token and body within 24 hours returns the original response.",
            "example": "create-files-mcp-2026-11-14",
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "maxLength": 200,
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "examples": {
                "oauth": {
                  "summary": "OAuth with dynamic client registration",
                  "value": {
                    "auth": {
                      "type": "oauth_dcr"
                    },
                    "name": "Tracker",
                    "transport": "https://tracker.example.com/mcp"
                  }
                },
                "settings": {
                  "summary": "No auth, created disabled with settings",
                  "value": {
                    "enabled": false,
                    "name": "Docs",
                    "settings": {
                      "dlp": {
                        "data_risk_action": "redact"
                      }
                    },
                    "transport": "https://docs.example.com/mcp"
                  }
                },
                "static": {
                  "summary": "API key in a header",
                  "value": {
                    "auth": {
                      "header_name": "X-Api-Key",
                      "token": "<token>",
                      "type": "static"
                    },
                    "name": "Files",
                    "transport": "https://files.example.com/mcp"
                  }
                }
              },
              "schema": {
                "$ref": "#/components/schemas/McpCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "example": {
                  "connect": {
                    "expires_at": "2026-11-14T10:15:00Z",
                    "url": "https://mcpgateway.example.com/mcpgateway/management-connect#t=<token>"
                  },
                  "connection": {
                    "auth_type": "oauth",
                    "oauth_mode": "dcr",
                    "state": "pending_connection",
                    "tool_count": 0
                  },
                  "mcp": {
                    "auth_type": "oauth",
                    "catalog_id": null,
                    "connection_state": "pending_connection",
                    "created_at": "2026-11-02T09:15:00Z",
                    "description": null,
                    "enabled": true,
                    "endpoint_urls": {
                      "mcp": "https://mcpgateway.example.com/files/mcp"
                    },
                    "execution_type": "remote",
                    "id": "e5f6a7b8",
                    "name": "Tracker",
                    "oauth_mode": "dcr",
                    "remote_connector": null,
                    "slug": "tracker",
                    "source": "custom",
                    "tool_count": 0,
                    "transport_type": "http",
                    "upstream_host": "https://tracker.example.com",
                    "version": "r1"
                  },
                  "operation_id": "5b1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "warnings": []
                },
                "schema": {
                  "$ref": "#/components/schemas/McpCreated"
                }
              }
            },
            "description": "Created",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Add a remote MCP",
        "tags": [
          "MCPs"
        ],
        "x-conditional-scopes": [
          {
            "scope": "credentials:write",
            "when": "`auth` carries `token`, `client_id`, `client_secret`, `extra_headers` or `extra_query_params`, or `transport` is a URL with userinfo (`user:pass@`) or a query string."
          },
          {
            "scope": "settings:write",
            "when": "The body carries `settings`."
          }
        ],
        "x-scopes": [
          "mcps:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/api": {
      "post": {
        "description": "Exposes a REST API as MCP tools: one tool per selected OpenAPI operation (`openapi`), or a generic request tool restricted by `access` rules. Preview the spec first with POST /mcps/api:preview and pass its `preview_token`. Spec errors use the same codes on create, preview, configuration changes and resync: 400 `spec_missing`, `spec_invalid`, `unsupported_encoding`, `blocked_destination` (the URL points somewhere the gateway does not call), `invalid_operation_override` (with `unknown_operations`), `no_operations_selected`; 410 `preview_expired` (preview again); 413 `spec_too_large`; 422 `tools_too_large`; 502 `fetch_failed` (the document could not be downloaded). Requests are limited to 1 MiB, so an inline document (`spec_text` or `spec_base64`) over about 750 KB must be sent as `source_url` instead. Requires an Idempotency-Key; retrying with the same key and body within 24 hours returns the original response, a different body under the same key is 409 `idempotency_conflict`.",
        "operationId": "Create_an_api_mcp",
        "parameters": [
          {
            "description": "Client-chosen token (1 to 200 characters) that makes retries safe: the same token and body within 24 hours returns the original response.",
            "example": "create-files-mcp-2026-11-14",
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "maxLength": 200,
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "auth_token": "<token>",
                "base_url": "https://billing.example.com/v1",
                "name": "Billing API",
                "openapi": {
                  "preview_token": "<preview-token>"
                },
                "upstream_auth_type": "bearer"
              },
              "schema": {
                "$ref": "#/components/schemas/ApiMcpCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "example": {
                  "connection": {
                    "auth_type": "api_key",
                    "oauth_mode": null,
                    "state": "ready",
                    "tool_count": 12
                  },
                  "mcp": {
                    "auth_type": "api_key",
                    "catalog_id": null,
                    "connection_state": "ready",
                    "created_at": "2026-11-02T09:15:00Z",
                    "description": "Company file server",
                    "enabled": true,
                    "endpoint_urls": {
                      "mcp": "https://mcpgateway.example.com/files/mcp"
                    },
                    "execution_type": "api",
                    "id": "c9d8e7f6",
                    "name": "Billing API",
                    "oauth_mode": null,
                    "remote_connector": null,
                    "slug": "billing-api",
                    "source": "api",
                    "tool_count": 12,
                    "transport_type": "http",
                    "upstream_host": null,
                    "version": "r1"
                  },
                  "operation_id": "6c2e3f4a-5b6c-7d8e-9f0a-1b2c3d4e5f60",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "warnings": []
                },
                "schema": {
                  "$ref": "#/components/schemas/McpCreated"
                }
              }
            },
            "description": "Created",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "410": {
            "$ref": "#/components/responses/Gone"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Add a REST API as an MCP",
        "tags": [
          "MCPs"
        ],
        "x-conditional-scopes": [
          {
            "scope": "credentials:write",
            "when": "The body carries `auth_token` or any `upstream_auth_*` field, any `openapi.overrides.*.fixed_params` is nonempty, or `base_url` or `openapi.source_url` is a URL with userinfo (`user:pass@`) or a query string."
          },
          {
            "scope": "settings:write",
            "when": "The body carries `settings`."
          }
        ],
        "x-scopes": [
          "mcps:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/api:preview": {
      "post": {
        "description": "Fetches or parses an OpenAPI document without saving anything and lists its operations with the selection the given `access` rules and `overrides` produce. Returns a `preview_token` (reuse it to reselect or to create without re-fetching). Spec errors use the same codes on create, preview, configuration changes and resync: 400 `spec_missing`, `spec_invalid`, `unsupported_encoding`, `blocked_destination` (the URL points somewhere the gateway does not call), `invalid_operation_override` (with `unknown_operations`), `no_operations_selected`; 410 `preview_expired` (preview again); 413 `spec_too_large`; 422 `tools_too_large`; 502 `fetch_failed` (the document could not be downloaded). Requests are limited to 1 MiB, so an inline document (`spec_text` or `spec_base64`) over about 750 KB must be sent as `source_url` instead.",
        "operationId": "Preview_an_api_spec",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "source_url": "https://billing.example.com/openapi.json"
              },
              "schema": {
                "$ref": "#/components/schemas/ApiPreview"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "preview": {
                    "info": {
                      "title": "Billing",
                      "version": "1.2.0"
                    },
                    "operations": [],
                    "preview_expires_in_seconds": 900,
                    "preview_token": "<preview-token>",
                    "servers": [],
                    "totals": {
                      "operations": 0,
                      "selected": 0
                    },
                    "warnings": []
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiPreviewResult"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "410": {
            "$ref": "#/components/responses/Gone"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Preview a REST API spec",
        "tags": [
          "MCPs"
        ],
        "x-conditional-scopes": [
          {
            "scope": "credentials:write",
            "when": "The body carries `fetch_headers`, or `source_url` is a URL with userinfo (`user:pass@`) or a query string."
          }
        ],
        "x-scopes": [
          "mcps:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}": {
      "delete": {
        "description": "Removes a custom or REST API MCP, or uninstalls a catalog MCP, together with its stored credentials and settings. MCPs provided by Quilr cannot be removed (403 `system_mcp`; disable them instead). An MCP referenced by the active QuilrQL policy answers 409 `policy_dependency`. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Delete_an_mcp",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Empty"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "deleted": true,
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/McpDeleted"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Remove an MCP",
        "tags": [
          "MCPs"
        ],
        "x-scopes": [
          "mcps:write"
        ]
      },
      "get": {
        "description": "One MCP with its last tool-fetch errors (fixed codes, never upstream text). `version` is the ETag of the MCP configuration, shared by settings, overrides and upstream credentials. MCPs of other tenants answer 404.",
        "operationId": "Read_an_mcp",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "mcp": {
                    "auth_type": "api_key",
                    "catalog_id": null,
                    "connection_state": "ready",
                    "created_at": "2026-11-02T09:15:00Z",
                    "description": "Company file server",
                    "enabled": true,
                    "endpoint_urls": {
                      "mcp": "https://mcpgateway.example.com/files/mcp"
                    },
                    "execution_type": "remote",
                    "id": "a1b2c3d4",
                    "last_fetch_errors": null,
                    "name": "Files",
                    "oauth_mode": null,
                    "remote_connector": null,
                    "slug": "files",
                    "source": "custom",
                    "tool_count": 12,
                    "transport_type": "http",
                    "upstream_host": "https://files.example.com",
                    "version": "r4"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/McpResponse"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read an MCP",
        "tags": [
          "MCPs"
        ],
        "x-scopes": [
          "read"
        ]
      },
      "patch": {
        "description": "Changes `name`, `description` and/or `enabled`. Disabling stops serving the MCP to every client until it is enabled again. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Update_an_mcp",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "examples": {
                "disable": {
                  "summary": "Disable",
                  "value": {
                    "enabled": false
                  }
                },
                "rename": {
                  "summary": "Rename",
                  "value": {
                    "name": "Shared files"
                  }
                }
              },
              "schema": {
                "$ref": "#/components/schemas/McpPatch"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "mcp": {
                    "auth_type": "api_key",
                    "catalog_id": null,
                    "connection_state": "ready",
                    "created_at": "2026-11-02T09:15:00Z",
                    "description": "Company file server",
                    "enabled": false,
                    "endpoint_urls": {
                      "mcp": "https://mcpgateway.example.com/files/mcp"
                    },
                    "execution_type": "remote",
                    "id": "a1b2c3d4",
                    "name": "Files",
                    "oauth_mode": null,
                    "remote_connector": null,
                    "slug": "files",
                    "source": "custom",
                    "tool_count": 12,
                    "transport_type": "http",
                    "upstream_host": "https://files.example.com",
                    "version": "r5"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/McpResponse"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Rename, describe, enable or disable an MCP",
        "tags": [
          "MCPs"
        ],
        "x-scopes": [
          "mcps:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/agents": {
      "get": {
        "description": "Every agent of the tenant with whether it may use this MCP. `version` is the MCP configuration version used by the If-Match of the write.",
        "operationId": "Read_MCP_agents",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agents": [
                    {
                      "custom": false,
                      "display_name": "Claude",
                      "enabled": true,
                      "keyword": "claude"
                    }
                  ],
                  "allowed_agents": [
                    "claude",
                    "cursor"
                  ],
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "version": "r7"
                },
                "schema": {
                  "$ref": "#/components/schemas/McpAgents"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read which agents may use an MCP",
        "tags": [
          "Client access"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/agents/{agent}": {
      "put": {
        "description": "Adds the agent to, or removes it from, the MCP's allowed agents (settings `access_control.allowed_agents`). A request that changes nothing keeps the version. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Allow_or_block_an_agent",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Agent keyword from `GET /agents`.",
            "example": "cursor",
            "in": "path",
            "name": "agent",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "enabled": false
              },
              "schema": {
                "$ref": "#/components/schemas/McpAgentAccess"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agents": [
                    {
                      "custom": false,
                      "display_name": "Cursor",
                      "enabled": false,
                      "keyword": "cursor"
                    }
                  ],
                  "allowed_agents": [
                    "claude"
                  ],
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "version": "r8"
                },
                "schema": {
                  "$ref": "#/components/schemas/McpAgents"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Allow or block an agent on an MCP",
        "tags": [
          "Client access"
        ],
        "x-scopes": [
          "settings:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/api-config": {
      "get": {
        "description": "Base URL, limits, access rules and OpenAPI selection of an MCP created with POST /mcps/api. URLs keep origin and path; fixed parameter values are listed by name only. Other MCPs answer 409 `not_api_mcp`. MCPs of other tenants answer 404.",
        "operationId": "Read_REST_API_config",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "true adds every OpenAPI operation with whether it is selected.",
            "in": "query",
            "name": "include_operations",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "api_config": {
                    "access": {
                      "deny": [
                        {
                          "methods": [
                            "DELETE"
                          ]
                        }
                      ]
                    },
                    "api_revision": 3,
                    "base_url": "https://pets.example.com/v1",
                    "base_url_has_credentials": false,
                    "docs_text": null,
                    "extra_header_names": [],
                    "extra_query_param_names": [],
                    "max_response_bytes": 1048576,
                    "mcp_id": "a1b2c3d4",
                    "mode": "openapi",
                    "openapi": {
                      "enable_generic_fallback": false,
                      "info": {
                        "title": "Pets",
                        "version": "1"
                      },
                      "overrides": {
                        "GET /pets": {
                          "fixed_param_names": [
                            "limit"
                          ],
                          "name": "list_all_pets"
                        }
                      },
                      "source_url": "https://pets.example.com/openapi.json",
                      "source_url_has_credentials": false
                    },
                    "remote_connector": null,
                    "timeout_s": 30.0,
                    "tools": [
                      "list_all_pets",
                      "get_pet"
                    ],
                    "updated_at": "2026-11-14T09:00:00Z"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "version": "r9"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiConfig"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read a REST API MCP's configuration",
        "tags": [
          "REST API MCPs"
        ],
        "x-scopes": [
          "read"
        ]
      },
      "patch": {
        "description": "Merges the sent fields into the saved configuration and republishes the tools (`tool_diff`). Sending `base_url` or `remote_connector_id` (even unchanged), and nonempty `fixed_params`, need credentials:write. 400 `no_operations_selected` when nothing would be exposed, `invalid_operation_override` for unknown operations, `spec_missing` when switching to OpenAPI without a document. Spec errors use the same codes on create, preview, configuration changes and resync: 400 `spec_missing`, `spec_invalid`, `unsupported_encoding`, `blocked_destination` (the URL points somewhere the gateway does not call), `invalid_operation_override` (with `unknown_operations`), `no_operations_selected`; 410 `preview_expired` (preview again); 413 `spec_too_large`; 422 `tools_too_large`; 502 `fetch_failed` (the document could not be downloaded). Requests are limited to 1 MiB, so an inline document (`spec_text` or `spec_base64`) over about 750 KB must be sent as `source_url` instead. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Update_REST_API_config",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "openapi": {
                  "overrides": {
                    "GET /pets": {
                      "name": "list_all_pets"
                    }
                  }
                },
                "timeout_s": 20
              },
              "schema": {
                "$ref": "#/components/schemas/ApiConfigPatch"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "api_config": {
                    "access": {
                      "deny": [
                        {
                          "methods": [
                            "DELETE"
                          ]
                        }
                      ]
                    },
                    "api_revision": 3,
                    "base_url": "https://pets.example.com/v1",
                    "base_url_has_credentials": false,
                    "docs_text": null,
                    "extra_header_names": [],
                    "extra_query_param_names": [],
                    "max_response_bytes": 1048576,
                    "mcp_id": "a1b2c3d4",
                    "mode": "openapi",
                    "openapi": {
                      "enable_generic_fallback": false,
                      "info": {
                        "title": "Pets",
                        "version": "1"
                      },
                      "overrides": {
                        "GET /pets": {
                          "fixed_param_names": [
                            "limit"
                          ],
                          "name": "list_all_pets"
                        }
                      },
                      "source_url": "https://pets.example.com/openapi.json",
                      "source_url_has_credentials": false
                    },
                    "remote_connector": null,
                    "timeout_s": 30.0,
                    "tools": [
                      "list_all_pets",
                      "get_pet"
                    ],
                    "updated_at": "2026-11-14T09:00:00Z"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "tool_diff": {
                    "added": [
                      "list_all_pets"
                    ],
                    "changed": [],
                    "removed": [
                      "list_pets"
                    ]
                  },
                  "version": "r10"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiConfig"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "410": {
            "$ref": "#/components/responses/Gone"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Change a REST API MCP's configuration",
        "tags": [
          "REST API MCPs"
        ],
        "x-conditional-scopes": [
          {
            "scope": "credentials:write",
            "when": "The body sends `base_url` or `remote_connector_id`, even unchanged (saved credentials then go to that destination), any `openapi.overrides.*.fixed_params` is nonempty, or `openapi.source_url` has a query string or user info."
          }
        ],
        "x-scopes": [
          "mcps:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/api-config/access-test": {
      "post": {
        "description": "Whether the saved rules allow one request, which rule decided and, for OpenAPI MCPs, the operation the path maps to.",
        "operationId": "Test_REST_API_access",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "method": "GET",
                "path": "/pets/42"
              },
              "schema": {
                "$ref": "#/components/schemas/ApiAccessTest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "api_revision": 3,
                  "decision": {
                    "allowed": true,
                    "index": null,
                    "list": null,
                    "operation": {
                      "key": "GET /pets/{id}",
                      "selected": true,
                      "selection_reason": "no_rules",
                      "supported": true,
                      "tags": [
                        "read"
                      ],
                      "tool_name": "get_pet"
                    },
                    "reason": "no_rules"
                  },
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiAccessDecision"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Test the saved access rules",
        "tags": [
          "REST API MCPs"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/api-config/resync": {
      "post": {
        "description": "Downloads the document again from its source URL and reports added and removed operations. `apply=true` saves it: overrides of operations that still exist are kept and new operations are saved turned off. 409 `spec_uploaded` for an uploaded document, `not_openapi` for generic MCPs, `no_operations_selected` when `apply=true` would leave no operation selected (a report without `apply` returns it in `error`). `apply=true` needs If-Match with the quoted `version` from the latest read (428 when missing, 412 when stale); without `apply`, If-Match is optional. Spec errors use the same codes on create, preview, configuration changes and resync: 400 `spec_missing`, `spec_invalid`, `unsupported_encoding`, `blocked_destination` (the URL points somewhere the gateway does not call), `invalid_operation_override` (with `unknown_operations`), `no_operations_selected`; 410 `preview_expired` (preview again); 413 `spec_too_large`; 422 `tools_too_large`; 502 `fetch_failed` (the document could not be downloaded). Requests are limited to 1 MiB, so an inline document (`spec_text` or `spec_base64`) over about 750 KB must be sent as `source_url` instead.",
        "operationId": "Resync_REST_API",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "true saves the fetched document (needs If-Match); false or omitted only reports what would change.",
            "in": "query",
            "name": "apply",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApiResync"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "api_revision": 4,
                  "applied": true,
                  "mcp_id": "a1b2c3d4",
                  "new_operations": [
                    {
                      "key": "GET /owners",
                      "method": "GET",
                      "path": "/owners",
                      "summary": "List owners",
                      "supported": true,
                      "tags": [],
                      "tool_name": "list_owners"
                    }
                  ],
                  "removed_operations": [],
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "tool_diff": {
                    "added": [],
                    "changed": [],
                    "removed": []
                  },
                  "totals": {
                    "operations": 4,
                    "selected": 2,
                    "supported": 4
                  },
                  "version": "r11",
                  "warnings": []
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiResyncResult"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Resync the OpenAPI document",
        "tags": [
          "REST API MCPs"
        ],
        "x-conditional-scopes": [
          {
            "scope": "credentials:write",
            "when": "The body carries `fetch_headers`."
          }
        ],
        "x-scopes": [
          "mcps:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/api-config/selection-preview": {
      "post": {
        "description": "Applies candidate access rules and override changes to the saved document without saving.",
        "operationId": "Preview_REST_API_selection",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "access": {
                  "allow": [
                    {
                      "tags": [
                        "read"
                      ]
                    }
                  ]
                }
              },
              "schema": {
                "$ref": "#/components/schemas/ApiSelectionPreview"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "api_revision": 3,
                  "mcp_id": "a1b2c3d4",
                  "operations": [
                    {
                      "key": "GET /pets",
                      "method": "GET",
                      "operation_id": "listPets",
                      "path": "/pets",
                      "selected": true,
                      "selection_reason": "no_rules",
                      "summary": "List pets",
                      "supported": true,
                      "tags": [
                        "read"
                      ],
                      "tool_name": "list_pets",
                      "warnings": []
                    }
                  ],
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "totals": {
                    "operations": 3,
                    "selected": 2,
                    "supported": 3
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ApiSelectionPreviewResult"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Preview which operations would become tools",
        "tags": [
          "REST API MCPs"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/capabilities:refresh": {
      "post": {
        "description": "Fetches tools, resources and prompts from the upstream server now, as the administrator who owns the key, and replaces the cached lists (new tools may be held for review). A pending tool change proposing exactly the fetched tool list is closed as applied; a change to any other list stays pending. OAuth MCPs need that administrator's connection (409 `oauth_connection_required`); passthrough MCPs answer 409 `pending_first_client`.",
        "operationId": "Refresh_tools",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Empty"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "fetch_errors": null,
                  "held_tools": [],
                  "mcp": {
                    "auth_type": "api_key",
                    "catalog_id": null,
                    "connection_state": "ready",
                    "created_at": "2026-11-02T09:15:00Z",
                    "description": "Company file server",
                    "enabled": true,
                    "endpoint_urls": {
                      "mcp": "https://mcpgateway.example.com/files/mcp"
                    },
                    "execution_type": "remote",
                    "id": "a1b2c3d4",
                    "name": "Files",
                    "oauth_mode": null,
                    "remote_connector": null,
                    "slug": "files",
                    "source": "custom",
                    "tool_count": 12,
                    "transport_type": "http",
                    "upstream_host": "https://files.example.com",
                    "version": "r4"
                  },
                  "prompts_count": 0,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "resources_count": 0,
                  "tools_count": 12
                },
                "schema": {
                  "$ref": "#/components/schemas/RefreshResult"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Refresh tools",
        "tags": [
          "Connections"
        ],
        "x-scopes": [
          "mcps:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/client-setup": {
      "get": {
        "description": "The MCP's own endpoint and the tenant OneMCP endpoint, how clients authenticate (`sign_in`: the client signs the user in through the gateway; `api_token`: an MCP API token plus the user's email in the `mcpuser` header; `upstream_oauth`: the client brings the provider token), whether the MCP is included in OneMCP and ready-to-paste client configuration with placeholders. MCPs of other tenants answer 404.",
        "operationId": "Read_client_setup",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "allowed_agents": [
                    "claude",
                    "cursor"
                  ],
                  "api_token": {
                    "agent_bound": true,
                    "header": "Authorization",
                    "scheme": "Bearer",
                    "user_header": "mcpuser"
                  },
                  "auth_type": "no_auth",
                  "direct": {
                    "auth_methods": [
                      "sign_in",
                      "api_token"
                    ],
                    "templates": {
                      "claude_code": "claude mcp add --transport http files https://mcp.example.com/files/mcp",
                      "mcp_json": {
                        "mcpServers": {
                          "files": {
                            "url": "https://mcp.example.com/files/mcp"
                          }
                        }
                      },
                      "vscode": {
                        "servers": {
                          "files": {
                            "type": "http",
                            "url": "https://mcp.example.com/files/mcp"
                          }
                        }
                      }
                    },
                    "token_templates": null,
                    "url": "https://mcp.example.com/files/mcp"
                  },
                  "enabled": true,
                  "mcp_id": "a1b2c3d4",
                  "name": "Files",
                  "oauth_mode": null,
                  "onemcp": {
                    "auth_methods": [
                      "sign_in"
                    ],
                    "included": true,
                    "templates": {
                      "claude_code": "claude mcp add --transport http files https://mcp.example.com/files/mcp",
                      "mcp_json": {
                        "mcpServers": {
                          "files": {
                            "url": "https://mcp.example.com/files/mcp"
                          }
                        }
                      },
                      "vscode": {
                        "servers": {
                          "files": {
                            "type": "http",
                            "url": "https://mcp.example.com/files/mcp"
                          }
                        }
                      }
                    },
                    "url": "https://mcp.example.com/quilrone/tenant-123/mcp"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "sign_in_link": {
                    "connection": null,
                    "requires_user_action": false,
                    "url": "https://mcp.example.com/user/dashboard?connect=a1b2c3d4"
                  },
                  "slug": "files"
                },
                "schema": {
                  "$ref": "#/components/schemas/ClientSetup"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read client setup",
        "tags": [
          "Client access"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/connect-links": {
      "post": {
        "description": "A new single-use link (15 minutes) for an OAuth MCP whose sign-in the gateway manages. The link itself authorizes the connection: whoever opens it within 15 minutes, once, is sent to the provider's sign-in, and the connection they make is saved for the administrator who owns this management key (no console sign-in). Treat the URL as a short-lived credential and share it only with the person who should connect the account. The token is in the URL fragment; the landing page posts it to `POST /mcpgateway/management-connect/start` (`{\"token\": \"...\"}`, no authentication; answers `{mcp_id, mcp_name, authorization_url}`, or 404 `connect_link_not_found`, 409 `connect_link_used`, 410 `connect_link_expired` / `connect_link_revoked`, 409 `key_owner_unavailable`, 403 `management_disabled_for_tenant`, 429 `rate_limited`, 502 `oauth_initiation_failed`). 409 `oauth_not_applicable` for MCPs that do not use gateway-managed OAuth.",
        "operationId": "Create_connect_link",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Empty"
              }
            }
          },
          "required": false
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "example": {
                  "connect": {
                    "expires_at": "2026-11-14T10:15:00Z",
                    "url": "https://mcpgateway.example.com/mcpgateway/management-connect#t=<token>"
                  },
                  "mcp_id": "e5f6a7b8",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ConnectLinkCreated"
                }
              }
            },
            "description": "Created",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Issue an OAuth connect link",
        "tags": [
          "Connections"
        ],
        "x-scopes": [
          "mcps:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/connection": {
      "get": {
        "description": "`ready`: tools are cached. `pending_connection`: an OAuth MCP waiting for its upstream sign-in (issue a connect link, or connect from the Quilr console). `fetch_failed`: the last tool fetch failed (see `last_fetch_errors`). `pending_first_client`: an OAuth passthrough MCP whose tools appear when the first client connects.",
        "operationId": "Read_connection",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "auth_type": "oauth",
                  "connected_admins": [],
                  "connection_state": "pending_connection",
                  "last_fetch_errors": null,
                  "mcp_id": "e5f6a7b8",
                  "oauth_mode": "dcr",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "tool_count": 0
                },
                "schema": {
                  "$ref": "#/components/schemas/Connection"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read connection state",
        "tags": [
          "Connections"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/custom-tools": {
      "get": {
        "description": "Every custom tool of the MCP, enabled or not, with its script, the tools it calls and how clients see it. `version` is the If-Match value for changes. MCPs of other tenants answer 404.",
        "operationId": "List_custom_tools",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "custom_tools": [
                    {
                      "annotations": {
                        "readOnlyHint": true
                      },
                      "code": "msgs = await list_messages(folder=args[\"folder\"], top=args[\"limit\"])\nunread = [m for m in msgs[\"value\"] if not m[\"isRead\"]]\n{\"unread\": len(unread), \"items\": [{\"from\": m[\"from\"], \"subject\": m[\"subject\"]} for m in unread]}",
                      "created_at": "2026-11-14T09:00:00Z",
                      "created_by": "admin@example.com",
                      "defaults": {
                        "folder": "inbox",
                        "limit": 25
                      },
                      "description": "Unread emails in a folder: sender and subject only. Use to brief the user on new mail.",
                      "enabled": true,
                      "fixed_args": {},
                      "input_schema": {
                        "additionalProperties": false,
                        "properties": {
                          "folder": {
                            "type": "string"
                          },
                          "limit": {
                            "maximum": 50,
                            "minimum": 1,
                            "type": "integer"
                          }
                        },
                        "type": "object"
                      },
                      "limits": {
                        "max_tool_calls": 50,
                        "timeout_s": 60
                      },
                      "name": "recent_unread_summary",
                      "output_schema": null,
                      "status": "active",
                      "tool_version": 3,
                      "updated_at": "2026-11-14T10:00:00Z",
                      "updated_by": "admin@example.com",
                      "uses_tools": [
                        "list_messages"
                      ],
                      "warnings": []
                    }
                  ],
                  "limit": 50,
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "version": "r12"
                },
                "schema": {
                  "$ref": "#/components/schemas/CustomToolList"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List an MCP's custom tools",
        "tags": [
          "Custom tools"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/custom-tools/{name}": {
      "delete": {
        "description": "Removes the tool; clients stop seeing it within seconds. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Delete_custom_tool",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Custom tool name: a letter, then letters, digits, `_` or `-` (at most 64).",
            "example": "recent_unread_summary",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Empty"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "deleted": true,
                  "mcp_id": "a1b2c3d4",
                  "name": "recent_unread_summary",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "version": "r15"
                },
                "schema": {
                  "$ref": "#/components/schemas/CustomToolDeleted"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Delete a custom tool",
        "tags": [
          "Custom tools"
        ],
        "x-scopes": [
          "tools:write"
        ]
      },
      "get": {
        "description": "One custom tool. 404 `custom_tool_not_found`. MCPs of other tenants answer 404.",
        "operationId": "Read_custom_tool",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Custom tool name: a letter, then letters, digits, `_` or `-` (at most 64).",
            "example": "recent_unread_summary",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "custom_tool": {
                    "annotations": {
                      "readOnlyHint": true
                    },
                    "code": "msgs = await list_messages(folder=args[\"folder\"], top=args[\"limit\"])\nunread = [m for m in msgs[\"value\"] if not m[\"isRead\"]]\n{\"unread\": len(unread), \"items\": [{\"from\": m[\"from\"], \"subject\": m[\"subject\"]} for m in unread]}",
                    "created_at": "2026-11-14T09:00:00Z",
                    "created_by": "admin@example.com",
                    "defaults": {
                      "folder": "inbox",
                      "limit": 25
                    },
                    "description": "Unread emails in a folder: sender and subject only. Use to brief the user on new mail.",
                    "enabled": true,
                    "fixed_args": {},
                    "input_schema": {
                      "additionalProperties": false,
                      "properties": {
                        "folder": {
                          "type": "string"
                        },
                        "limit": {
                          "maximum": 50,
                          "minimum": 1,
                          "type": "integer"
                        }
                      },
                      "type": "object"
                    },
                    "limits": {
                      "max_tool_calls": 50,
                      "timeout_s": 60
                    },
                    "name": "recent_unread_summary",
                    "output_schema": null,
                    "status": "active",
                    "tool_version": 3,
                    "updated_at": "2026-11-14T10:00:00Z",
                    "updated_by": "admin@example.com",
                    "uses_tools": [
                      "list_messages"
                    ],
                    "warnings": []
                  },
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "version": "r12"
                },
                "schema": {
                  "$ref": "#/components/schemas/CustomTool"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read a custom tool",
        "tags": [
          "Custom tools"
        ],
        "x-scopes": [
          "read"
        ]
      },
      "patch": {
        "description": "Changes the sent fields and keeps the rest, for example `{\"enabled\": false}` to hide the tool. 404 `custom_tool_not_found`. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Update_custom_tool",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Custom tool name: a letter, then letters, digits, `_` or `-` (at most 64).",
            "example": "recent_unread_summary",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "enabled": false
              },
              "schema": {
                "$ref": "#/components/schemas/CustomToolPatch"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "custom_tool": {
                    "annotations": {
                      "readOnlyHint": true
                    },
                    "code": "msgs = await list_messages(folder=args[\"folder\"], top=args[\"limit\"])\nunread = [m for m in msgs[\"value\"] if not m[\"isRead\"]]\n{\"unread\": len(unread), \"items\": [{\"from\": m[\"from\"], \"subject\": m[\"subject\"]} for m in unread]}",
                    "created_at": "2026-11-14T09:00:00Z",
                    "created_by": "admin@example.com",
                    "defaults": {
                      "folder": "inbox",
                      "limit": 25
                    },
                    "description": "Unread emails in a folder: sender and subject only. Use to brief the user on new mail.",
                    "enabled": false,
                    "fixed_args": {},
                    "input_schema": {
                      "additionalProperties": false,
                      "properties": {
                        "folder": {
                          "type": "string"
                        },
                        "limit": {
                          "maximum": 50,
                          "minimum": 1,
                          "type": "integer"
                        }
                      },
                      "type": "object"
                    },
                    "limits": {
                      "max_tool_calls": 50,
                      "timeout_s": 60
                    },
                    "name": "recent_unread_summary",
                    "output_schema": null,
                    "status": "disabled",
                    "tool_version": 4,
                    "updated_at": "2026-11-14T10:00:00Z",
                    "updated_by": "admin@example.com",
                    "uses_tools": [
                      "list_messages"
                    ],
                    "warnings": []
                  },
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "version": "r14"
                },
                "schema": {
                  "$ref": "#/components/schemas/CustomTool"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Change a custom tool",
        "tags": [
          "Custom tools"
        ],
        "x-scopes": [
          "tools:write"
        ]
      },
      "put": {
        "description": "Saves the whole tool under `name` (201 when new). The name must not be one the MCP's own tools use (409 `tool_name_taken`) or a gateway tool name. The script is checked for syntax errors and for names it reads but never defines or imports (400 with the `line`); names it calls that are not tools of the MCP come back as `warnings`. An MCP can have up to 50 custom tools (409 `custom_tool_limit`). Clients see the change within seconds. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Save_custom_tool",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Custom tool name: a letter, then letters, digits, `_` or `-` (at most 64).",
            "example": "recent_unread_summary",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "annotations": {
                  "readOnlyHint": true
                },
                "code": "msgs = await list_messages(folder=args[\"folder\"], top=args[\"limit\"])\nunread = [m for m in msgs[\"value\"] if not m[\"isRead\"]]\n{\"unread\": len(unread), \"items\": [{\"from\": m[\"from\"], \"subject\": m[\"subject\"]} for m in unread]}",
                "defaults": {
                  "folder": "inbox",
                  "limit": 25
                },
                "description": "Unread emails in a folder: sender and subject only. Use to brief the user on new mail.",
                "input_schema": {
                  "additionalProperties": false,
                  "properties": {
                    "folder": {
                      "type": "string"
                    },
                    "limit": {
                      "maximum": 50,
                      "minimum": 1,
                      "type": "integer"
                    }
                  },
                  "type": "object"
                }
              },
              "schema": {
                "$ref": "#/components/schemas/CustomToolDefinition"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "custom_tool": {
                    "annotations": {
                      "readOnlyHint": true
                    },
                    "code": "msgs = await list_messages(folder=args[\"folder\"], top=args[\"limit\"])\nunread = [m for m in msgs[\"value\"] if not m[\"isRead\"]]\n{\"unread\": len(unread), \"items\": [{\"from\": m[\"from\"], \"subject\": m[\"subject\"]} for m in unread]}",
                    "created_at": "2026-11-14T09:00:00Z",
                    "created_by": "admin@example.com",
                    "defaults": {
                      "folder": "inbox",
                      "limit": 25
                    },
                    "description": "Unread emails in a folder: sender and subject only. Use to brief the user on new mail.",
                    "enabled": true,
                    "fixed_args": {},
                    "input_schema": {
                      "additionalProperties": false,
                      "properties": {
                        "folder": {
                          "type": "string"
                        },
                        "limit": {
                          "maximum": 50,
                          "minimum": 1,
                          "type": "integer"
                        }
                      },
                      "type": "object"
                    },
                    "limits": {
                      "max_tool_calls": 50,
                      "timeout_s": 60
                    },
                    "name": "recent_unread_summary",
                    "output_schema": null,
                    "status": "active",
                    "tool_version": 3,
                    "updated_at": "2026-11-14T10:00:00Z",
                    "updated_by": "admin@example.com",
                    "uses_tools": [
                      "list_messages"
                    ],
                    "warnings": []
                  },
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "version": "r13"
                },
                "schema": {
                  "$ref": "#/components/schemas/CustomTool"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Create or replace a custom tool",
        "tags": [
          "Custom tools"
        ],
        "x-scopes": [
          "tools:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/custom-tools/{name}/restore": {
      "post": {
        "description": "Saves an earlier definition from the history again, as a new version. 404 `custom_tool_version_not_found`. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Restore_custom_tool",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Custom tool name: a letter, then letters, digits, `_` or `-` (at most 64).",
            "example": "recent_unread_summary",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "version": 2
              },
              "schema": {
                "$ref": "#/components/schemas/CustomToolRestore"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "custom_tool": {
                    "annotations": {
                      "readOnlyHint": true
                    },
                    "code": "msgs = await list_messages(folder=args[\"folder\"], top=args[\"limit\"])\nunread = [m for m in msgs[\"value\"] if not m[\"isRead\"]]\n{\"unread\": len(unread), \"items\": [{\"from\": m[\"from\"], \"subject\": m[\"subject\"]} for m in unread]}",
                    "created_at": "2026-11-14T09:00:00Z",
                    "created_by": "admin@example.com",
                    "defaults": {
                      "folder": "inbox",
                      "limit": 25
                    },
                    "description": "Unread emails in a folder: sender and subject only. Use to brief the user on new mail.",
                    "enabled": true,
                    "fixed_args": {},
                    "input_schema": {
                      "additionalProperties": false,
                      "properties": {
                        "folder": {
                          "type": "string"
                        },
                        "limit": {
                          "maximum": 50,
                          "minimum": 1,
                          "type": "integer"
                        }
                      },
                      "type": "object"
                    },
                    "limits": {
                      "max_tool_calls": 50,
                      "timeout_s": 60
                    },
                    "name": "recent_unread_summary",
                    "output_schema": null,
                    "status": "active",
                    "tool_version": 3,
                    "updated_at": "2026-11-14T10:00:00Z",
                    "updated_by": "admin@example.com",
                    "uses_tools": [
                      "list_messages"
                    ],
                    "warnings": []
                  },
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "restored_from": 2,
                  "version": "r16"
                },
                "schema": {
                  "$ref": "#/components/schemas/CustomTool"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Restore an earlier version",
        "tags": [
          "Custom tools"
        ],
        "x-scopes": [
          "tools:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/custom-tools/{name}/versions": {
      "get": {
        "description": "The last 20 saved definitions of the tool, newest first, with who saved each and when.",
        "operationId": "List_custom_tool_versions",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Custom tool name: a letter, then letters, digits, `_` or `-` (at most 64).",
            "example": "recent_unread_summary",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "mcp_id": "a1b2c3d4",
                  "name": "recent_unread_summary",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "versions": [
                    {
                      "code_sha256": "9f2c000000000000000000000000000000000000000000000000000000000000",
                      "definition": {
                        "annotations": {
                          "readOnlyHint": true
                        },
                        "code": "msgs = await list_messages(folder=args[\"folder\"], top=args[\"limit\"])\nunread = [m for m in msgs[\"value\"] if not m[\"isRead\"]]\n{\"unread\": len(unread), \"items\": [{\"from\": m[\"from\"], \"subject\": m[\"subject\"]} for m in unread]}",
                        "defaults": {
                          "folder": "inbox",
                          "limit": 25
                        },
                        "description": "Unread emails in a folder: sender and subject only. Use to brief the user on new mail.",
                        "input_schema": {
                          "additionalProperties": false,
                          "properties": {
                            "folder": {
                              "type": "string"
                            },
                            "limit": {
                              "maximum": 50,
                              "minimum": 1,
                              "type": "integer"
                            }
                          },
                          "type": "object"
                        }
                      },
                      "saved_at": "2026-11-14T10:00:00Z",
                      "saved_by": "admin@example.com",
                      "tool_version": 3
                    }
                  ]
                },
                "schema": {
                  "$ref": "#/components/schemas/CustomToolVersions"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List a custom tool's saved versions",
        "tags": [
          "Custom tools"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/custom-tools:functions": {
      "get": {
        "description": "One async function per tool a script can call: every tool the MCP offers now, including tools turned off for users (`hidden_from_clients`), but not tools waiting for tool review. Each has a Python signature built from the tool's input schema. Also the globals every script has (`args`, `call_tool`, `ToolError`) and the run limits.",
        "operationId": "List_custom_tool_functions",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "functions": [
                    {
                      "function": "list_messages",
                      "hidden_from_clients": false,
                      "input_schema": {
                        "type": "object"
                      },
                      "signature": "async def list_messages(folder: str = None, top: int = None)",
                      "summary": "List messages in a mail folder",
                      "tool": "list_messages"
                    }
                  ],
                  "globals": {
                    "args": "dict: the tool's defaults overlaid by the call's arguments"
                  },
                  "limits": {
                    "max_code_bytes": 65536,
                    "max_tool_calls": 50,
                    "timeout_s": 60
                  },
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/CustomToolFunctions"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List the functions a script can call",
        "tags": [
          "Custom tools"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/custom-tools:test": {
      "post": {
        "description": "Runs the saved tool, or `draft` changes over it (or a new tool not saved yet), as the key owner with their own connection to the MCP, through the same path a client call takes. The tools it calls are real calls with real effects and are logged; the checks of the custom tool's own call (policies, approvals, DLP) apply as for a client call. Returns what a client would get plus each call made, print() output and the error. A disabled tool can be tested. 409 `test_run_unavailable` for MCPs where each user signs in with their own token (OAuth passthrough); 409 `mcp_disabled` when the MCP is disabled (nothing ran). `mocks` names must be tools the MCP offers (400 otherwise, before anything runs); `mocked_tools` lists the mocks the script actually called.\n\n**Ambiguous failures.** 502 `test_run_failed` with `error.may_have_run`: true means the run failed after the script started: the tool may have run, and its calls may have changed data. Check the MCP's logs before running it again. `may_have_run`: false means it failed before the script started; nothing ran.\n\n**Retries.** Send an `Idempotency-Key` to retry safely. When the script started (a result, a script error or the ambiguous 502), the same key and body within 24 hours return that stored answer instead of running again. When the tool certainly did not run (custom tools busy, invalid arguments, refused before the script, unknown tool or MCP, a failure before dispatch), nothing is stored and a retry with the same key runs. Requests with one key that arrive while it runs wait for its answer, or get 409 `test_run_in_progress` (retry after `Retry-After`); a run is never given up while it is still running, however long it takes. A run whose gateway process stopped (no sign of life for 30 seconds) becomes a stored 502 `test_run_failed` with `may_have_run`: true, and the original request, if it still answers, returns that same answer; it is never run again under that key. A different body under the key is 409 `idempotency_conflict`; a new key runs the tool again.",
        "operationId": "Test_custom_tool",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Optional client-chosen token (1 to 200 characters). With it, the same token and body within 24 hours returns the stored answer (a result or a failure) instead of running again; a different body under the same token is 409 `idempotency_conflict`.",
            "example": "test-summarize-2026-11-14",
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "maxLength": 200,
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "arguments": {
                  "limit": 10
                },
                "name": "recent_unread_summary"
              },
              "schema": {
                "$ref": "#/components/schemas/CustomToolTest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "client_result": {
                    "content": [
                      {
                        "text": "{\"unread\": 1, \"items\": [{\"from\": \"ana@example.com\", \"subject\": \"Q3 plan\"}]}",
                        "type": "text"
                      }
                    ],
                    "isError": false
                  },
                  "draft": false,
                  "error": null,
                  "mcp_id": "a1b2c3d4",
                  "name": "recent_unread_summary",
                  "ok": true,
                  "outcome": "ok",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "run": {
                    "approval_required": null,
                    "calls": [
                      {
                        "ms": 790,
                        "ok": true,
                        "tool": "list_messages"
                      }
                    ],
                    "error_kind": null,
                    "logs": "",
                    "ms": 840,
                    "result": {
                      "items": [
                        {
                          "from": "ana@example.com",
                          "subject": "Q3 plan"
                        }
                      ],
                      "unread": 1
                    },
                    "run_id": "6a2f0c1d9e8b4a7f",
                    "unfinished_calls": []
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/CustomToolTestResult"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Test-run a custom tool",
        "tags": [
          "Custom tools"
        ],
        "x-scopes": [
          "tools:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/custom-tools:validate": {
      "post": {
        "description": "Runs every check a save runs and returns the normalized tool, without saving or running it.",
        "operationId": "Validate_custom_tool",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "annotations": {
                  "readOnlyHint": true
                },
                "code": "msgs = await list_messages(folder=args[\"folder\"], top=args[\"limit\"])\nunread = [m for m in msgs[\"value\"] if not m[\"isRead\"]]\n{\"unread\": len(unread), \"items\": [{\"from\": m[\"from\"], \"subject\": m[\"subject\"]} for m in unread]}",
                "defaults": {
                  "folder": "inbox",
                  "limit": 25
                },
                "description": "Unread emails in a folder: sender and subject only. Use to brief the user on new mail.",
                "input_schema": {
                  "additionalProperties": false,
                  "properties": {
                    "folder": {
                      "type": "string"
                    },
                    "limit": {
                      "maximum": 50,
                      "minimum": 1,
                      "type": "integer"
                    }
                  },
                  "type": "object"
                },
                "name": "recent_unread_summary"
              },
              "schema": {
                "$ref": "#/components/schemas/CustomToolValidate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "custom_tool": {
                    "annotations": {
                      "readOnlyHint": true
                    },
                    "code": "msgs = await list_messages(folder=args[\"folder\"], top=args[\"limit\"])\nunread = [m for m in msgs[\"value\"] if not m[\"isRead\"]]\n{\"unread\": len(unread), \"items\": [{\"from\": m[\"from\"], \"subject\": m[\"subject\"]} for m in unread]}",
                    "defaults": {
                      "folder": "inbox",
                      "limit": 25
                    },
                    "description": "Unread emails in a folder: sender and subject only. Use to brief the user on new mail.",
                    "enabled": true,
                    "fixed_args": {},
                    "input_schema": {
                      "additionalProperties": false,
                      "properties": {
                        "folder": {
                          "type": "string"
                        },
                        "limit": {
                          "maximum": 50,
                          "minimum": 1,
                          "type": "integer"
                        }
                      },
                      "type": "object"
                    },
                    "limits": {
                      "max_tool_calls": 50,
                      "timeout_s": 60
                    },
                    "name": "recent_unread_summary",
                    "output_schema": null,
                    "status": "active",
                    "uses_tools": [
                      "list_messages"
                    ],
                    "warnings": []
                  },
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "valid": true
                },
                "schema": {
                  "$ref": "#/components/schemas/CustomToolValidation"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Check a custom tool definition",
        "tags": [
          "Custom tools"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/oauth-client": {
      "get": {
        "description": "Which OAuth client the MCP signs users in with (never the secret) and whether it can be rotated: only clients an administrator supplied can be; clients the gateway registered are managed by the gateway.",
        "operationId": "Read_OAuth_client",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "mcp_id": "a1b2c3d4",
                  "oauth_client": {
                    "client_id_hint": "...9f2c",
                    "configured": true,
                    "custom": true,
                    "oauth": true,
                    "registered_at": "2026-11-14T09:00:00Z",
                    "rotatable": true
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "version": "r5"
                },
                "schema": {
                  "$ref": "#/components/schemas/OAuthClient"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read an MCP's OAuth client",
        "tags": [
          "User sign-in"
        ],
        "x-scopes": [
          "read"
        ]
      },
      "put": {
        "description": "Replaces the client secret, and optionally the client id. A new secret alone keeps every user connected. A new client id needs `reconnect_users`: true deletes every user's connection so each signs in again with the new client; false keeps existing connections on the previous client until it stops working at the provider, while new sign-ins use the new one. 409 `oauth_client_not_custom` or `not_oauth_mcp` when there is nothing to rotate. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Rotate_OAuth_client",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "client_id": "<new client id>",
                "client_secret": "<new secret>",
                "reconnect_users": true
              },
              "schema": {
                "$ref": "#/components/schemas/OAuthClientRotate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "mcp_id": "a1b2c3d4",
                  "oauth_client": {
                    "client_id_hint": "...71ab",
                    "configured": true,
                    "custom": true,
                    "oauth": true,
                    "registered_at": "2026-11-14T09:00:00Z",
                    "rotatable": true
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "rotation": {
                    "client_id_changed": true,
                    "connections_dropped": 12,
                    "reconnect_users": true
                  },
                  "version": "r6"
                },
                "schema": {
                  "$ref": "#/components/schemas/OAuthClient"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Rotate an MCP's OAuth client",
        "tags": [
          "User sign-in"
        ],
        "x-scopes": [
          "credentials:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/oauth-scope-options": {
      "get": {
        "description": "Permission bundles the provider offers for this OAuth MCP and the stored selection. Select bundles with settings `oauth_scopes` (PATCH /mcps/{mcp_id}/settings).",
        "operationId": "Read_OAuth_scope_options",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "always_available_tools": [],
                  "available": false,
                  "cross_area_tools": [],
                  "mcp_id": "a1b2c3d4",
                  "options": [],
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "selected": null
                },
                "schema": {
                  "$ref": "#/components/schemas/OAuthScopeOptions"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read OAuth permission options",
        "tags": [
          "Tool changes"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/scoped-settings": {
      "get": {
        "description": "Overrides of tools, dlp and token_saving for one user or smart group, ordered by scope type and value and paginated with `limit` and `cursor`. `scope_type` with `scope_value` returns only that scope's override (an empty list when there is none). `version` is the MCP configuration version of the page it comes with.",
        "operationId": "List_scoped_settings",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Page size, 1 to 200 (default 50).",
            "example": 50,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "With scope_value: only the override for this scope, user or smart_group. Matched exactly after trimming spaces. Send both or neither (one alone is 400).",
            "example": "user",
            "in": "query",
            "name": "scope_type",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "With scope_type: only the override for this user email or smart group name, matched exactly (case kept) after trimming spaces. Send both or neither.",
            "example": "dana@example.com",
            "in": "query",
            "name": "scope_value",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "mcp_id": "a1b2c3d4",
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "scoped_settings": [
                    {
                      "created_at": "2026-11-10T12:00:00Z",
                      "enabled": true,
                      "scope_type": "user",
                      "scope_value": "dana@example.com",
                      "settings": {
                        "dlp": {
                          "data_risk_action": "block"
                        }
                      },
                      "updated_at": "2026-11-10T12:00:00Z",
                      "updated_by": "admin@example.com"
                    }
                  ],
                  "version": "r4"
                },
                "schema": {
                  "$ref": "#/components/schemas/ScopedSettingsList"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List per-user and per-group overrides",
        "tags": [
          "Settings"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/scoped-settings/{scope_type}/{scope_value}": {
      "delete": {
        "description": "Removes the override; `deleted` is false when none existed (the version is then unchanged). Under QuilrQL the answer carries an `inactive_under_quilrql` warning. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Delete_scoped_settings",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "`user` (an email of this tenant) or `smart_group` (a smart group name).",
            "example": "user",
            "in": "path",
            "name": "scope_type",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The user email or smart group name. Encode `/` as `%2F`.",
            "example": "dana@example.com",
            "in": "path",
            "name": "scope_value",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Empty"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "deleted": true,
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "scope_type": "user",
                  "scope_value": "dana@example.com",
                  "scoped_setting": null,
                  "version": "r6"
                },
                "schema": {
                  "$ref": "#/components/schemas/ScopedSettingResult"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Remove an override",
        "tags": [
          "Settings"
        ],
        "x-scopes": [
          "settings:write"
        ]
      },
      "put": {
        "description": "Stores the override for one user (email of this tenant) or smart group. A user override wins over smart group overrides, which win over the MCP settings. Saving an override identical to the stored one keeps the version. Under QuilrQL the override is saved with an `inactive_under_quilrql` warning. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Put_scoped_settings",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "`user` (an email of this tenant) or `smart_group` (a smart group name).",
            "example": "user",
            "in": "path",
            "name": "scope_type",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The user email or smart group name. Encode `/` as `%2F`.",
            "example": "dana@example.com",
            "in": "path",
            "name": "scope_value",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "enabled": true,
                "settings": {
                  "dlp": {
                    "data_risk_action": "block"
                  }
                }
              },
              "schema": {
                "$ref": "#/components/schemas/ScopedSettingsPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "deleted": false,
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "scoped_setting": {
                    "created_at": "2026-11-10T12:00:00Z",
                    "enabled": true,
                    "scope_type": "user",
                    "scope_value": "dana@example.com",
                    "settings": {
                      "dlp": {
                        "data_risk_action": "block"
                      }
                    },
                    "updated_at": "2026-11-10T12:00:00Z",
                    "updated_by": "admin@example.com"
                  },
                  "version": "r5"
                },
                "schema": {
                  "$ref": "#/components/schemas/ScopedSettingResult"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Create or replace an override",
        "tags": [
          "Settings"
        ],
        "x-scopes": [
          "settings:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/settings": {
      "get": {
        "description": "Every settings section with defaults filled in, and whether QuilrQL policies are authoritative (`policy_authority.mode`).",
        "operationId": "Read_mcp_settings",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "mcp_id": "a1b2c3d4",
                  "policy_authority": {
                    "mode": "legacy"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "settings": {
                    "dlp": {
                      "data_risk_action": "redact"
                    },
                    "oauth_scopes": null,
                    "send_user_claims_header": false,
                    "token_saving": {
                      "strip_base64": true
                    },
                    "tools": {
                      "delete_file": {
                        "enabled": false,
                        "enforce_confirmation": false,
                        "require_justification": false
                      }
                    },
                    "upstream_session_max_concurrency": null
                  },
                  "version": "r4"
                },
                "schema": {
                  "$ref": "#/components/schemas/McpSettings"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read MCP settings",
        "tags": [
          "Settings"
        ],
        "x-scopes": [
          "read"
        ]
      },
      "patch": {
        "description": "Sectioned patch: tools, dlp, token_saving, access_control, tool_sync, tool_exposure and onemcp merge by key; web_search_policy and oauth_scopes replace the stored value. Unknown fields at any depth answer 400 with their paths in `error.fields`. Changes reach both the MCP's own endpoint and OneMCP immediately. Under QuilrQL the settings are saved with an `inactive_under_quilrql` warning. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Update_mcp_settings",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "examples": {
                "dlp": {
                  "summary": "Redact sensitive data",
                  "value": {
                    "dlp": {
                      "data_risk_action": "redact"
                    }
                  }
                },
                "tool": {
                  "summary": "Disable one tool and confirm another",
                  "value": {
                    "tools": {
                      "delete_file": {
                        "enabled": false
                      },
                      "write_file": {
                        "enforce_confirmation": true
                      }
                    }
                  }
                }
              },
              "schema": {
                "$ref": "#/components/schemas/McpSettingsPatch"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "mcp_id": "a1b2c3d4",
                  "policy_authority": {
                    "mode": "legacy"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "settings": {
                    "dlp": {
                      "data_risk_action": "redact"
                    },
                    "oauth_scopes": null,
                    "send_user_claims_header": false,
                    "token_saving": {
                      "strip_base64": true
                    },
                    "tools": {
                      "delete_file": {
                        "enabled": false,
                        "enforce_confirmation": false,
                        "require_justification": false
                      }
                    },
                    "upstream_session_max_concurrency": null
                  },
                  "version": "r5",
                  "warnings": []
                },
                "schema": {
                  "$ref": "#/components/schemas/McpSettings"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Update MCP settings",
        "tags": [
          "Settings"
        ],
        "x-scopes": [
          "settings:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/sign-in-link": {
      "get": {
        "description": "A link to hand to users, for example on an internal page. It opens the Quilr user dashboard: the user signs in to Quilr as themselves, then the dashboard starts this MCP's connect step (`connection`: oauth signs in to the provider, user_key asks for their own key). The link carries no credential and connects no one by itself; users without access to the MCP see a message instead. MCPs of other tenants answer 404.",
        "operationId": "Read_sign_in_link",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "connection": "oauth",
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "requires_user_action": true,
                  "url": "https://mcp.example.com/user/dashboard?connect=a1b2c3d4"
                },
                "schema": {
                  "$ref": "#/components/schemas/SignInLink"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Get the user sign-in link",
        "tags": [
          "User sign-in"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/tokens": {
      "get": {
        "description": "Tokens issued for this MCP, newest first, without secrets. The Quilr console lists the same tokens.",
        "operationId": "List_MCP_API_tokens",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Page size, 1 to 200 (default 50).",
            "example": 50,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "items": [
                    {
                      "agent": "cursor",
                      "created_at": "2026-11-14T09:00:00Z",
                      "created_by": "admin@example.com",
                      "last_used_at": null,
                      "mcp_id": "a1b2c3d4",
                      "name": "CI runner",
                      "token_id": "3c1f9a2b-5d6e-4f70-8a9b-0c1d2e3f4a5b"
                    }
                  ],
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/McpTokenList"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List MCP API tokens",
        "tags": [
          "Client access"
        ],
        "x-scopes": [
          "read"
        ]
      },
      "post": {
        "description": "Issues a token for a client that cannot sign users in. Clients send it as `Authorization: Bearer` and name the end user in the `mcpuser` header; it only works for the chosen agent. OAuth MCPs answer 409 `oauth_mcp_uses_sign_in`. The secret is returned once in `token.secret`. Requires an Idempotency-Key; retrying with the same key and body within 24 hours returns the original response, a different body under the same key is 409 `idempotency_conflict`.",
        "operationId": "Issue_an_MCP_API_token",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Client-chosen token (1 to 200 characters) that makes retries safe: the same token and body within 24 hours returns the original response.",
            "example": "create-files-mcp-2026-11-14",
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "maxLength": 200,
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "agent": "cursor",
                "name": "CI runner"
              },
              "schema": {
                "$ref": "#/components/schemas/McpTokenCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "example": {
                  "operation_id": "8e4a5b6c-7d8e-9f0a-1b2c-3d4e5f607182",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "token": {
                    "agent": "cursor",
                    "created_at": "2026-11-14T09:00:00Z",
                    "created_by": "admin@example.com",
                    "last_used_at": null,
                    "mcp_id": "a1b2c3d4",
                    "name": "CI runner",
                    "secret": "sk-quilr-mcp-<secret>",
                    "token_id": "3c1f9a2b-5d6e-4f70-8a9b-0c1d2e3f4a5b"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/McpTokenCreated"
                }
              }
            },
            "description": "Created",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Issue an MCP API token",
        "tags": [
          "Client access"
        ],
        "x-scopes": [
          "tokens:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/tokens/{token_id}": {
      "delete": {
        "description": "Deletes the token; clients using it are refused from the next request.",
        "operationId": "Revoke_an_MCP_API_token",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "MCP API token id (`token_id` from the list or create response).",
            "example": "3c1f9a2b-5d6e-4f70-8a9b-0c1d2e3f4a5b",
            "in": "path",
            "name": "token_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Empty"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "token": {
                    "agent": "cursor",
                    "created_at": "2026-11-14T09:00:00Z",
                    "created_by": "admin@example.com",
                    "last_used_at": null,
                    "mcp_id": "a1b2c3d4",
                    "name": "CI runner",
                    "revoked": true,
                    "token_id": "3c1f9a2b-5d6e-4f70-8a9b-0c1d2e3f4a5b"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/McpTokenRevoked"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Revoke an MCP API token",
        "tags": [
          "Client access"
        ],
        "x-scopes": [
          "tokens:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/tool-changes": {
      "get": {
        "description": "Status, the tools added, removed or modified upstream, and when it was last checked. A pending change carries `version` (also the ETag): the If-Match value for apply and dismiss.",
        "operationId": "Read_tool_changes",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "tool_changes": {
                    "added": [
                      {
                        "name": "zip_files"
                      }
                    ],
                    "change_count": 1,
                    "checked_at": "2026-11-14T09:00:00Z",
                    "detected_at": "2026-11-14T09:00:00Z",
                    "mcp_id": "a1b2c3d4",
                    "mode": "notify",
                    "modified": [],
                    "name": "Files",
                    "reason_code": null,
                    "removed": [],
                    "resolved_at": null,
                    "resolved_by": null,
                    "status": "pending",
                    "version": "c3f1a9e07b52d4c68e1f0a2b"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ToolChangeResponse"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read tool-change state",
        "tags": [
          "Tool changes"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/tool-changes/apply": {
      "post": {
        "description": "Adopts the change you reviewed: send its `version` quoted in If-Match (428 when missing). The upstream tool list is fetched again and adopted only when it still matches the reviewed change; otherwise nothing is adopted and the answer is 412 `tool_changes_changed` with the current change in `error.tool_changes` (review it and retry with its `version`). A change that was replaced or closed since the read (by a check, another apply or a dismiss) is 412 `version_conflict`, also with `error.tool_changes` (its `version` is null when nothing is pending any more). New tools may still be held for review. 409 `tool_changes_unavailable` when the upstream tool list cannot be read now (nothing adopted).",
        "operationId": "Apply_tool_changes",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"c3f1a9e07b52d4c68e1f0a2b\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Empty"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "tool_changes": {
                    "added": [
                      {
                        "name": "zip_files"
                      }
                    ],
                    "change_count": 1,
                    "checked_at": "2026-11-14T09:00:00Z",
                    "detected_at": "2026-11-14T09:00:00Z",
                    "mcp_id": "a1b2c3d4",
                    "mode": "notify",
                    "modified": [],
                    "name": "Files",
                    "reason_code": null,
                    "removed": [],
                    "resolved_at": "2026-11-14T09:05:00Z",
                    "resolved_by": "admin@example.com",
                    "status": "applied",
                    "version": null
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ToolChangeResponse"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Adopt the reviewed upstream tool list",
        "tags": [
          "Tool changes"
        ],
        "x-scopes": [
          "tool_reviews:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/tool-changes/check": {
      "post": {
        "description": "Compares the upstream tool list with the cached one now.",
        "operationId": "Check_tool_changes",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Empty"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "tool_changes": {
                    "added": [
                      {
                        "name": "zip_files"
                      }
                    ],
                    "change_count": 1,
                    "checked_at": "2026-11-14T09:00:00Z",
                    "detected_at": "2026-11-14T09:00:00Z",
                    "mcp_id": "a1b2c3d4",
                    "mode": "notify",
                    "modified": [],
                    "name": "Files",
                    "reason_code": null,
                    "removed": [],
                    "resolved_at": null,
                    "resolved_by": null,
                    "status": "pending",
                    "version": "c3f1a9e07b52d4c68e1f0a2b"
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ToolChangeResponse"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Check for tool changes now",
        "tags": [
          "Tool changes"
        ],
        "x-scopes": [
          "tool_reviews:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/tool-changes/dismiss": {
      "post": {
        "description": "Keeps the cached tool list and stops flagging this upstream list; a different upstream list opens a new change. Send the reviewed change's `version` quoted in If-Match (428 when missing); a change that was replaced, applied or dismissed since the read is 412 `version_conflict` with the current state in `error.tool_changes` (`version` null when nothing is pending).",
        "operationId": "Dismiss_tool_changes",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"c3f1a9e07b52d4c68e1f0a2b\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Empty"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "tool_changes": {
                    "added": [
                      {
                        "name": "zip_files"
                      }
                    ],
                    "change_count": 1,
                    "checked_at": "2026-11-14T09:00:00Z",
                    "detected_at": "2026-11-14T09:00:00Z",
                    "mcp_id": "a1b2c3d4",
                    "mode": "notify",
                    "modified": [],
                    "name": "Files",
                    "reason_code": null,
                    "removed": [],
                    "resolved_at": null,
                    "resolved_by": null,
                    "status": "dismissed",
                    "version": null
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ToolChangeResponse"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Dismiss a tool change",
        "tags": [
          "Tool changes"
        ],
        "x-scopes": [
          "tool_reviews:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/tool-reviews": {
      "get": {
        "description": "Review mode and the tools detected upstream that are held, rejected or already approved.",
        "operationId": "Read_tool_reviews",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "hold_new_tools": null,
                  "mcp_id": "a1b2c3d4",
                  "mode": "hold",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "tenant_hold_new_tools": true,
                  "tools": [
                    {
                      "description": "Delete a repository",
                      "detected_at": "2026-11-13T18:00:00Z",
                      "input_schema": {
                        "type": "object"
                      },
                      "name": "delete_repo",
                      "resolved_at": null,
                      "resolved_by": null,
                      "source": "refresh",
                      "status": "held",
                      "updated_at": "2026-11-13T18:00:00Z"
                    }
                  ]
                },
                "schema": {
                  "$ref": "#/components/schemas/ToolReviews"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read tool reviews",
        "tags": [
          "Tool reviews"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/tool-reviews/approve": {
      "post": {
        "description": "Approves the named tools; they are added to the tool list. 409 `tools_not_awaiting_review` when one is not awaiting review.",
        "operationId": "Approve_tools",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "tools": [
                  "delete_repo"
                ]
              },
              "schema": {
                "$ref": "#/components/schemas/ToolReviewDecision"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "hold_new_tools": null,
                  "mcp_id": "a1b2c3d4",
                  "mode": "hold",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "tenant_hold_new_tools": true,
                  "tools": []
                },
                "schema": {
                  "$ref": "#/components/schemas/ToolReviews"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Approve held tools",
        "tags": [
          "Tool reviews"
        ],
        "x-scopes": [
          "tool_reviews:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/tool-reviews/reject": {
      "post": {
        "description": "Rejects the named tools; they stay hidden from clients. 409 `tools_not_awaiting_review` when one is not awaiting review.",
        "operationId": "Reject_tools",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "tools": [
                  "delete_repo"
                ]
              },
              "schema": {
                "$ref": "#/components/schemas/ToolReviewDecision"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "hold_new_tools": null,
                  "mcp_id": "a1b2c3d4",
                  "mode": "hold",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "tenant_hold_new_tools": true,
                  "tools": []
                },
                "schema": {
                  "$ref": "#/components/schemas/ToolReviews"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Reject held tools",
        "tags": [
          "Tool reviews"
        ],
        "x-scopes": [
          "tool_reviews:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/tools": {
      "get": {
        "description": "Cached tools, resources and prompts of the MCP. Each tool carries its enabled and confirmation settings, its review state (held or rejected tools are listed too) and its all-time call count (null with a `usage_unavailable` warning when usage data cannot be read).",
        "operationId": "List_mcp_tools",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "mcp_id": "a1b2c3d4",
                  "policy_authority": {
                    "mode": "legacy"
                  },
                  "prompts": [],
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "resources": [],
                  "tools": [
                    {
                      "annotations": null,
                      "call_count": 310,
                      "description": "Read a file",
                      "enabled": true,
                      "enforce_confirmation": false,
                      "input_schema": {
                        "type": "object"
                      },
                      "name": "read_file",
                      "require_justification": false,
                      "review_state": null,
                      "title": null
                    }
                  ],
                  "warnings": []
                },
                "schema": {
                  "$ref": "#/components/schemas/McpTools"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List an MCP's tools",
        "tags": [
          "MCPs"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/upstream-auth": {
      "delete": {
        "description": "Removes the static credential and, unless `keep_extras=true`, the extra headers and query parameters (a REST API MCP keeps its extra headers and query parameters: clear them with `PUT` `{\"extra_headers\": {}, \"extra_query_params\": {}}`). Refused with 409 `policy_dependency` while the active QuilrQL policy depends on them. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Delete_upstream_auth",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "true keeps the extra headers and query parameters; default false removes them too. A REST API MCP always keeps them (clear them with PUT {\"extra_headers\": {}, \"extra_query_params\": {}}).",
            "in": "query",
            "name": "keep_extras",
            "required": false,
            "schema": {
              "default": false,
              "type": "boolean"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Empty"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "upstream_auth": {
                    "configured": false,
                    "credential_editable": true,
                    "extra_header_names": [],
                    "extra_query_param_names": [],
                    "header_name": null,
                    "mode": null,
                    "oauth_mode": null,
                    "query_param": null,
                    "scheme": null,
                    "secret_configured": false,
                    "type": null,
                    "updated_at": "2026-11-12T08:30:00Z",
                    "user_credentials_saved": 0
                  },
                  "version": "r6"
                },
                "schema": {
                  "$ref": "#/components/schemas/UpstreamAuth"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Remove upstream credentials",
        "tags": [
          "Upstream credentials"
        ],
        "x-scopes": [
          "credentials:write"
        ]
      },
      "get": {
        "description": "Whether a static credential is configured, how it is sent and the names (never values) of extra headers and query parameters.",
        "operationId": "Read_upstream_auth",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "upstream_auth": {
                    "configured": true,
                    "credential_editable": true,
                    "extra_header_names": [
                      "X-Team"
                    ],
                    "extra_query_param_names": [],
                    "header_name": "X-Api-Key",
                    "mode": "admin_shared",
                    "oauth_mode": null,
                    "query_param": null,
                    "scheme": null,
                    "secret_configured": true,
                    "type": "header",
                    "updated_at": "2026-11-12T08:30:00Z",
                    "user_credentials_saved": 0
                  },
                  "version": "r4"
                },
                "schema": {
                  "$ref": "#/components/schemas/UpstreamAuth"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read upstream credential metadata",
        "tags": [
          "Upstream credentials"
        ],
        "x-scopes": [
          "read"
        ]
      },
      "put": {
        "description": "Creates, rotates or changes the static credential and/or the extra headers and query parameters. `mode: user_required` makes every user bring their own key (they save it from the sign-in link, `GET /mcps/{mcp_id}/sign-in-link`); the shared key is deleted. Omitted extras keep the stored ones; {} clears them. On OAuth MCPs only the extra headers and query parameters can be set (sent upstream with each user's OAuth token); a static credential is refused with 400. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Put_upstream_auth",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"r4\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "header_name": "X-Api-Key",
                "token": "<token>",
                "type": "header"
              },
              "schema": {
                "$ref": "#/components/schemas/UpstreamAuthPut"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "mcp_id": "a1b2c3d4",
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "upstream_auth": {
                    "configured": true,
                    "credential_editable": true,
                    "extra_header_names": [
                      "X-Team"
                    ],
                    "extra_query_param_names": [],
                    "header_name": "X-Api-Key",
                    "mode": "admin_shared",
                    "oauth_mode": null,
                    "query_param": null,
                    "scheme": null,
                    "secret_configured": true,
                    "type": "header",
                    "updated_at": "2026-11-12T08:30:00Z",
                    "user_credentials_saved": 0
                  },
                  "version": "r5"
                },
                "schema": {
                  "$ref": "#/components/schemas/UpstreamAuth"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Set or rotate upstream credentials",
        "tags": [
          "Upstream credentials"
        ],
        "x-scopes": [
          "credentials:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/usage": {
      "get": {
        "description": "The usage report restricted to one MCP of your tenant.",
        "operationId": "Read_mcp_usage",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Inclusive start: RFC 3339 time with a timezone, or a date (UTC midnight). Default: UTC midnight 7 days before `to`. At most 92 days before `to`.",
            "example": "2026-11-01",
            "in": "query",
            "name": "from",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exclusive end: RFC 3339 time with a timezone, or a date (through the end of that UTC day). Default: now.",
            "example": "2026-11-08",
            "in": "query",
            "name": "to",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Period of each row: total (default), month, week, day or hour (hour covers at most 14 days). Periods start on UTC boundaries.",
            "example": "day",
            "in": "query",
            "name": "granularity",
            "required": false,
            "schema": {
              "enum": [
                "total",
                "month",
                "week",
                "day",
                "hour"
              ],
              "type": "string"
            }
          },
          {
            "description": "Up to two comma-separated dimensions: mcp, tool, user, agent, called_via, auth_mode, transport, outcome.",
            "example": "mcp",
            "in": "query",
            "name": "group_by",
            "required": false,
            "schema": {
              "description": "Comma-separated, any of: mcp, tool, user, agent, called_via, auth_mode, transport, outcome",
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact tool values.",
            "in": "query",
            "name": "tool",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. User emails (case-insensitive).",
            "in": "query",
            "name": "user",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact agent values.",
            "in": "query",
            "name": "agent",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact called via values.",
            "in": "query",
            "name": "called_via",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact auth mode values.",
            "in": "query",
            "name": "auth_mode",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact transport values.",
            "in": "query",
            "name": "transport",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. One of success, error, blocked.",
            "in": "query",
            "name": "outcome",
            "required": false,
            "schema": {
              "description": "Comma-separated, any of: success, error, blocked",
              "type": "string"
            }
          },
          {
            "description": "Row order: period, requests, errors, blocked, duration.",
            "in": "query",
            "name": "sort",
            "required": false,
            "schema": {
              "enum": [
                "period",
                "requests",
                "errors",
                "blocked",
                "duration"
              ],
              "type": "string"
            }
          },
          {
            "description": "Rows per page, 1 to 5000 (default 500).",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 500,
              "maximum": 5000,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page of the same query. 409 `collection_changed` when the result was recomputed and differs.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data_through": "2026-11-14T00:00:00Z",
                  "from": "2026-11-07T00:00:00Z",
                  "generated_at": "2026-11-14T09:00:02Z",
                  "granularity": "total",
                  "group_by": [
                    "tool"
                  ],
                  "mcp_id": "a1b2c3d4",
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "row_count": 1,
                  "rows": [
                    {
                      "avg_duration_ms": 412.5,
                      "blocked": 8,
                      "errors": 31,
                      "p95_duration_ms": 1630.0,
                      "requests": 1840,
                      "response_chars": 9120034,
                      "success": 1801,
                      "tool": "read_file",
                      "tool_argument_chars": 220481,
                      "unique_tools": 9,
                      "unique_users": 37
                    }
                  ],
                  "timezone": "UTC",
                  "to": "2026-11-14T00:00:00Z",
                  "totals": {
                    "avg_duration_ms": 412.5,
                    "blocked": 8,
                    "errors": 31,
                    "p95_duration_ms": 1630.0,
                    "requests": 1840,
                    "response_chars": 9120034,
                    "success": 1801,
                    "tool_argument_chars": 220481,
                    "unique_tools": 9,
                    "unique_users": 37
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/UsageReport"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Usage report for one MCP",
        "tags": [
          "Analytics"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/users": {
      "get": {
        "description": "Connection state of every user who set this MCP up or is affected by its rules. States: signed_in, available, needs_sign_in, sign_in_not_finished, not_signed_in_yet, turned_off_by_user, blocked_by_access_rules, mcp_turned_off. Computed from stored state; may be a few minutes old (`generated_at`).",
        "operationId": "List_MCP_user_connections",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Page size, 1 to 200 (default 50).",
            "example": 50,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "generated_at": "2026-11-14T09:00:00Z",
                  "items": [
                    {
                      "access_allowed": true,
                      "can_renew": true,
                      "email": "dana@example.com",
                      "preference_enabled": true,
                      "set_up_at": "2026-11-01T10:00:00Z",
                      "signed_in_until": "2026-11-14T11:00:00Z",
                      "state": "signed_in"
                    }
                  ],
                  "mcp_id": "a1b2c3d4",
                  "next_cursor": null,
                  "renews_automatically": true,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "sign_in_required": true
                },
                "schema": {
                  "$ref": "#/components/schemas/McpUsers"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List users of an MCP",
        "tags": [
          "User connections"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps/{mcp_id}/users/{email}/connection": {
      "delete": {
        "description": "Deletes the user's stored credentials for this MCP (provider sign-in, gateway session token and personal upstream credential); the user must connect again. Access rules are unchanged: to block the user, add them to settings `access_control.denied_users`.",
        "operationId": "Revoke_a_user_connection",
        "parameters": [
          {
            "description": "MCP id (the `id` of an MCP, not its slug).",
            "example": "a1b2c3d4",
            "in": "path",
            "name": "mcp_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "User email (case-insensitive).",
            "example": "dana@example.com",
            "in": "path",
            "name": "email",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Empty"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "email": "dana@example.com",
                  "mcp_id": "a1b2c3d4",
                  "removed": {
                    "gateway_token": true,
                    "oauth_token": true,
                    "upstream_credential": false
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "revoked": true
                },
                "schema": {
                  "$ref": "#/components/schemas/ConnectionRevoked"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Revoke a user's connection",
        "tags": [
          "User connections"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "/mcpgateway/management/v1/mcps:probe": {
      "post": {
        "description": "Connects to a URL without saving anything and reports the transport, OAuth discovery results and whether a credential is required, to choose `auth.type` before creating.",
        "operationId": "Probe_an_mcp_url",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "transport": "https://tracker.example.com/mcp"
              },
              "schema": {
                "$ref": "#/components/schemas/McpProbe"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "probe": {
                    "requires_auth": true,
                    "transport_url": "https://tracker.example.com/mcp"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ProbeResult"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Check an MCP URL",
        "tags": [
          "MCPs"
        ],
        "x-conditional-scopes": [
          {
            "scope": "credentials:write",
            "when": "The body carries `extra_headers` or `extra_query_params`, or `transport` is a URL with userinfo (`user:pass@`) or a query string."
          }
        ],
        "x-scopes": [
          "mcps:write"
        ]
      }
    },
    "/mcpgateway/management/v1/openapi.json": {
      "get": {
        "description": "This OpenAPI 3.1 document, generated by the server from its route table so it always matches the deployed API. Requires the read scope. The body is the bare document (no request_id field).",
        "operationId": "Get_openapi",
        "parameters": [],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "components": {},
                  "info": {
                    "title": "MCP Gateway Management API",
                    "version": "1.0.0"
                  },
                  "openapi": "3.1.0",
                  "paths": {}
                },
                "schema": {
                  "$ref": "#/components/schemas/OpenApiDocument"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Download the OpenAPI document",
        "tags": [
          "Reference"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/operations/{op_id}": {
      "get": {
        "description": "Status of a journaled create (MCP create, catalog install, REST API MCP create) by its `operation_id`: state pending, done, failed or expired, the created resource id and the completed stages. Only the key that started the operation can read it. A pending operation is completed by retrying the original request with the same Idempotency-Key.",
        "operationId": "Get_operation",
        "parameters": [
          {
            "description": "Operation id returned by a create (`operation_id`).",
            "example": "5b1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
            "in": "path",
            "name": "op_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "operation": {
                    "completed_at": "2026-11-14T09:01:01Z",
                    "created_at": "2026-11-14T09:00:59Z",
                    "operation": "mcp_create",
                    "operation_id": "5b1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
                    "resource_id": "a1b2c3d4",
                    "stages": [
                      {
                        "at": "2026-11-14T09:01:00Z",
                        "stage": "registered"
                      }
                    ],
                    "state": "done",
                    "status_code": 201,
                    "updated_at": "2026-11-14T09:01:01Z"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/Operation"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read an operation",
        "tags": [
          "Reference"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/requests": {
      "get": {
        "description": "Tool-call metadata, newest first (default the last 24 hours, at most 31 days): MCP, tool, user, agent, outcome, duration and DLP outcome. Never tool arguments, responses, error text, headers or tokens.",
        "operationId": "List_requests",
        "parameters": [
          {
            "description": "Inclusive start: RFC 3339 time with a timezone, or a date (UTC midnight). Default: 24 hours before `to`. At most 31 days before `to`.",
            "example": "2026-11-01",
            "in": "query",
            "name": "from",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exclusive end: RFC 3339 time with a timezone, or a date (through the end of that UTC day). Default: now.",
            "example": "2026-11-08",
            "in": "query",
            "name": "to",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. MCP ids.",
            "in": "query",
            "name": "mcp",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact tool values.",
            "in": "query",
            "name": "tool",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. User emails (case-insensitive).",
            "in": "query",
            "name": "user",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact agent values.",
            "in": "query",
            "name": "agent",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact called via values.",
            "in": "query",
            "name": "called_via",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact auth mode values.",
            "in": "query",
            "name": "auth_mode",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact transport values.",
            "in": "query",
            "name": "transport",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. One of success, error, blocked.",
            "in": "query",
            "name": "outcome",
            "required": false,
            "schema": {
              "description": "Comma-separated, any of: success, error, blocked",
              "type": "string"
            }
          },
          {
            "description": "Rows per page, 1 to 1000 (default 100).",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "maximum": 1000,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page of the same query. 409 `collection_changed` when the result was recomputed and differs.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "true: blocked calls only; false: calls that were not blocked.",
            "in": "query",
            "name": "blocked",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Request ids.",
            "in": "query",
            "name": "request_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data_through": "2026-11-14T00:00:00Z",
                  "from": "2026-11-07T00:00:00Z",
                  "generated_at": "2026-11-14T09:00:02Z",
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "rows": [
                    {
                      "agent": "claude-code",
                      "auth_mode": "proxy_token",
                      "blocked": false,
                      "called_via": "direct",
                      "completed_at": "2026-11-14T08:59:59Z",
                      "dlp": {
                        "input": {
                          "blocked": false,
                          "categories": [],
                          "outcome": "allowed"
                        },
                        "output": {
                          "blocked": false,
                          "categories": [],
                          "outcome": "allowed"
                        }
                      },
                      "duration_ms": 421,
                      "error": false,
                      "mcp": "a1b2c3d4",
                      "mcp_name": "Files",
                      "outcome": "success",
                      "request_id": "f00dfeed",
                      "started_at": "2026-11-14T08:59:58Z",
                      "tool": "read_file",
                      "transport": "streamable_http",
                      "user": "dana@example.com"
                    }
                  ],
                  "timezone": "UTC",
                  "to": "2026-11-14T00:00:00Z"
                },
                "schema": {
                  "$ref": "#/components/schemas/RequestsReport"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List tool calls",
        "tags": [
          "Analytics"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/tenant/settings": {
      "get": {
        "description": "Tenant switches and the data-retention status (managed in the Quilr console). When QuilrQL policies govern the tenant, the switches are stored but the policies decide.",
        "operationId": "Read_tenant_settings",
        "parameters": [],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data_retention": {
                    "managed_by": "console",
                    "stored_revision": null,
                    "updated_at": null
                  },
                  "memories": {
                    "enabled": true,
                    "updated_at": null,
                    "updated_by": null
                  },
                  "policy_authority": {
                    "mode": "legacy"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "smart_mode": {
                    "mode": "user_preference",
                    "updated_at": null,
                    "updated_by": null
                  },
                  "tenant_id": "tenant-123",
                  "tool_review": {
                    "hold_new_tools": false,
                    "updated_at": null,
                    "updated_by": null
                  },
                  "version": "t1a2b3c4d5e6f7081"
                },
                "schema": {
                  "$ref": "#/components/schemas/TenantConfig"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read tenant settings",
        "tags": [
          "Tenant"
        ],
        "x-scopes": [
          "read"
        ]
      },
      "patch": {
        "description": "Changes any of smart_mode, memories and tool_review. Send the quoted `version` from the latest read in If-Match (428 when missing, 412 when stale).",
        "operationId": "Update_tenant_settings",
        "parameters": [
          {
            "description": "Quoted `version` (ETag) from the latest read of this resource.",
            "example": "\"t5e0c2b9a7d413f86\"",
            "in": "header",
            "name": "If-Match",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "memories": {
                  "enabled": false
                }
              },
              "schema": {
                "$ref": "#/components/schemas/TenantConfigPatch"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data_retention": {
                    "managed_by": "console",
                    "stored_revision": null,
                    "updated_at": null
                  },
                  "memories": {
                    "enabled": false,
                    "updated_at": "2026-11-14T09:00:00Z",
                    "updated_by": "admin@example.com"
                  },
                  "policy_authority": {
                    "mode": "legacy"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "smart_mode": {
                    "mode": "user_preference",
                    "updated_at": null,
                    "updated_by": null
                  },
                  "tenant_id": "tenant-123",
                  "tool_review": {
                    "hold_new_tools": false,
                    "updated_at": null,
                    "updated_by": null
                  },
                  "version": "t9f8e7d6c5b4a3921",
                  "warnings": []
                },
                "schema": {
                  "$ref": "#/components/schemas/TenantConfig"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "412": {
            "$ref": "#/components/responses/VersionConflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "428": {
            "$ref": "#/components/responses/PreconditionRequired"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Update tenant settings",
        "tags": [
          "Tenant"
        ],
        "x-scopes": [
          "tenant_settings:write"
        ]
      }
    },
    "/mcpgateway/management/v1/tool-arg-aliases": {
      "get": {
        "description": "Aliases that rewrite the arguments clients send (parameter renames and value normalizations) before a call reaches the MCP.",
        "operationId": "List_tool_argument_aliases",
        "parameters": [
          {
            "description": "Page size, 1 to 200 (default 50).",
            "example": 50,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only aliases of this MCP.",
            "in": "query",
            "name": "mcp_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only aliases of this tool.",
            "in": "query",
            "name": "tool_name",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "items": [
                    {
                      "active": true,
                      "alias_id": "7d2e4f60-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
                      "created_at": "2026-11-14T09:00:00Z",
                      "enabled": true,
                      "kind": "param_alias",
                      "mcp_id": "a1b2c3d4",
                      "note": null,
                      "source": "manual",
                      "spec": {
                        "action": null,
                        "from": "id",
                        "kind": "param_alias",
                        "path": [],
                        "to": "work_item_id",
                        "tool_name": "get_work_item",
                        "version": 1
                      },
                      "tool_name": "get_work_item",
                      "updated_at": "2026-11-14T09:00:00Z"
                    }
                  ],
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ToolArgAliasList"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List tool-argument aliases",
        "tags": [
          "Tenant"
        ],
        "x-scopes": [
          "read"
        ]
      },
      "post": {
        "description": "Adds an alias after checking it against the tool's input schema (400 when it does not fit).",
        "operationId": "Create_a_tool_argument_alias",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "mcp_id": "a1b2c3d4",
                "spec": {
                  "action": null,
                  "from": "id",
                  "kind": "param_alias",
                  "path": [],
                  "to": "work_item_id",
                  "tool_name": "get_work_item",
                  "version": 1
                }
              },
              "schema": {
                "$ref": "#/components/schemas/ToolArgAliasCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "example": {
                  "alias": {
                    "active": true,
                    "alias_id": "7d2e4f60-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
                    "created_at": "2026-11-14T09:00:00Z",
                    "enabled": true,
                    "kind": "param_alias",
                    "mcp_id": "a1b2c3d4",
                    "note": null,
                    "schema_verified": true,
                    "source": "manual",
                    "spec": {
                      "action": null,
                      "from": "id",
                      "kind": "param_alias",
                      "path": [],
                      "to": "work_item_id",
                      "tool_name": "get_work_item",
                      "version": 1
                    },
                    "tool_name": "get_work_item",
                    "updated_at": "2026-11-14T09:00:00Z"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ToolArgAliasResponse"
                }
              }
            },
            "description": "Created",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Create a tool-argument alias",
        "tags": [
          "Tenant"
        ],
        "x-scopes": [
          "tenant_settings:write"
        ]
      }
    },
    "/mcpgateway/management/v1/tool-arg-aliases/{alias_id}": {
      "delete": {
        "description": "Deletes the alias.",
        "operationId": "Delete_a_tool_argument_alias",
        "parameters": [
          {
            "description": "Alias id (`alias_id`).",
            "example": "7d2e4f60-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
            "in": "path",
            "name": "alias_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Empty"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "alias": {
                    "alias_id": "7d2e4f60-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
                    "deleted": true,
                    "mcp_id": "a1b2c3d4"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ToolArgAliasDeleted"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Delete a tool-argument alias",
        "tags": [
          "Tenant"
        ],
        "x-scopes": [
          "tenant_settings:write"
        ]
      },
      "get": {
        "description": "One alias.",
        "operationId": "Read_a_tool_argument_alias",
        "parameters": [
          {
            "description": "Alias id (`alias_id`).",
            "example": "7d2e4f60-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
            "in": "path",
            "name": "alias_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "alias": {
                    "active": true,
                    "alias_id": "7d2e4f60-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
                    "created_at": "2026-11-14T09:00:00Z",
                    "enabled": true,
                    "kind": "param_alias",
                    "mcp_id": "a1b2c3d4",
                    "note": null,
                    "source": "manual",
                    "spec": {
                      "action": null,
                      "from": "id",
                      "kind": "param_alias",
                      "path": [],
                      "to": "work_item_id",
                      "tool_name": "get_work_item",
                      "version": 1
                    },
                    "tool_name": "get_work_item",
                    "updated_at": "2026-11-14T09:00:00Z"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ToolArgAliasResponse"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read a tool-argument alias",
        "tags": [
          "Tenant"
        ],
        "x-scopes": [
          "read"
        ]
      },
      "patch": {
        "description": "Changes `enabled` and/or `note`.",
        "operationId": "Update_a_tool_argument_alias",
        "parameters": [
          {
            "description": "Alias id (`alias_id`).",
            "example": "7d2e4f60-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
            "in": "path",
            "name": "alias_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "enabled": false
              },
              "schema": {
                "$ref": "#/components/schemas/ToolArgAliasPatch"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "alias": {
                    "active": false,
                    "alias_id": "7d2e4f60-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
                    "created_at": "2026-11-14T09:00:00Z",
                    "enabled": false,
                    "kind": "param_alias",
                    "mcp_id": "a1b2c3d4",
                    "note": null,
                    "source": "manual",
                    "spec": {
                      "action": null,
                      "from": "id",
                      "kind": "param_alias",
                      "path": [],
                      "to": "work_item_id",
                      "tool_name": "get_work_item",
                      "version": 1
                    },
                    "tool_name": "get_work_item",
                    "updated_at": "2026-11-14T09:00:00Z"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ToolArgAliasResponse"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Enable, disable or annotate an alias",
        "tags": [
          "Tenant"
        ],
        "x-scopes": [
          "tenant_settings:write"
        ]
      },
      "put": {
        "description": "Creates the alias with this id (for example an accepted suggestion's id) or replaces it, spec included. 409 `alias_id_in_use` when the id belongs to another organization.",
        "operationId": "Put_a_tool_argument_alias",
        "parameters": [
          {
            "description": "Alias id (`alias_id`).",
            "example": "7d2e4f60-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
            "in": "path",
            "name": "alias_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "mcp_id": "a1b2c3d4",
                "spec": {
                  "action": null,
                  "from": "id",
                  "kind": "param_alias",
                  "path": [],
                  "to": "work_item_id",
                  "tool_name": "get_work_item",
                  "version": 1
                }
              },
              "schema": {
                "$ref": "#/components/schemas/ToolArgAliasPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "alias": {
                    "active": true,
                    "alias_id": "7d2e4f60-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
                    "created_at": "2026-11-14T09:00:00Z",
                    "enabled": true,
                    "kind": "param_alias",
                    "mcp_id": "a1b2c3d4",
                    "note": null,
                    "schema_verified": true,
                    "source": "manual",
                    "spec": {
                      "action": null,
                      "from": "id",
                      "kind": "param_alias",
                      "path": [],
                      "to": "work_item_id",
                      "tool_name": "get_work_item",
                      "version": 1
                    },
                    "tool_name": "get_work_item",
                    "updated_at": "2026-11-14T09:00:00Z"
                  },
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ToolArgAliasResponse"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "408": {
            "$ref": "#/components/responses/BodyTimeout"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/BodyTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Create or replace a tool-argument alias",
        "tags": [
          "Tenant"
        ],
        "x-scopes": [
          "tenant_settings:write"
        ]
      }
    },
    "/mcpgateway/management/v1/tool-changes": {
      "get": {
        "description": "One row per MCP: whether the upstream tool list differs from the cached one. Pending rows carry the change's `version` for apply and dismiss.",
        "operationId": "List_tool_changes",
        "parameters": [
          {
            "description": "Page size, 1 to 200 (default 50).",
            "example": 50,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "true lists only MCPs with a change awaiting review.",
            "in": "query",
            "name": "pending_only",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "items": [
                    {
                      "added": [
                        {
                          "name": "zip_files"
                        }
                      ],
                      "change_count": 1,
                      "checked_at": "2026-11-14T09:00:00Z",
                      "detected_at": "2026-11-14T09:00:00Z",
                      "mcp_id": "a1b2c3d4",
                      "mode": "notify",
                      "modified": [],
                      "name": "Files",
                      "reason_code": null,
                      "removed": [],
                      "resolved_at": null,
                      "resolved_by": null,
                      "status": "pending",
                      "version": "c3f1a9e07b52d4c68e1f0a2b"
                    }
                  ],
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/ToolChangeList"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List tool-change state",
        "tags": [
          "Tool changes"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/usage": {
      "get": {
        "description": "Tool calls, outcomes, unique users and tools, durations and payload sizes per period and up to two dimensions, with totals of the whole selection. Outcome: blocked (DLP or policy), error, or success.",
        "operationId": "Read_usage",
        "parameters": [
          {
            "description": "Inclusive start: RFC 3339 time with a timezone, or a date (UTC midnight). Default: UTC midnight 7 days before `to`. At most 92 days before `to`.",
            "example": "2026-11-01",
            "in": "query",
            "name": "from",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exclusive end: RFC 3339 time with a timezone, or a date (through the end of that UTC day). Default: now.",
            "example": "2026-11-08",
            "in": "query",
            "name": "to",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Period of each row: total (default), month, week, day or hour (hour covers at most 14 days). Periods start on UTC boundaries.",
            "example": "day",
            "in": "query",
            "name": "granularity",
            "required": false,
            "schema": {
              "enum": [
                "total",
                "month",
                "week",
                "day",
                "hour"
              ],
              "type": "string"
            }
          },
          {
            "description": "Up to two comma-separated dimensions: mcp, tool, user, agent, called_via, auth_mode, transport, outcome.",
            "example": "mcp",
            "in": "query",
            "name": "group_by",
            "required": false,
            "schema": {
              "description": "Comma-separated, any of: mcp, tool, user, agent, called_via, auth_mode, transport, outcome",
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. MCP ids.",
            "in": "query",
            "name": "mcp",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact tool values.",
            "in": "query",
            "name": "tool",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. User emails (case-insensitive).",
            "in": "query",
            "name": "user",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact agent values.",
            "in": "query",
            "name": "agent",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact called via values.",
            "in": "query",
            "name": "called_via",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact auth mode values.",
            "in": "query",
            "name": "auth_mode",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact transport values.",
            "in": "query",
            "name": "transport",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. One of success, error, blocked.",
            "in": "query",
            "name": "outcome",
            "required": false,
            "schema": {
              "description": "Comma-separated, any of: success, error, blocked",
              "type": "string"
            }
          },
          {
            "description": "Row order: period, requests, errors, blocked, duration.",
            "in": "query",
            "name": "sort",
            "required": false,
            "schema": {
              "enum": [
                "period",
                "requests",
                "errors",
                "blocked",
                "duration"
              ],
              "type": "string"
            }
          },
          {
            "description": "Rows per page, 1 to 5000 (default 500).",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 500,
              "maximum": 5000,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page of the same query. 409 `collection_changed` when the result was recomputed and differs.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data_through": "2026-11-14T00:00:00Z",
                  "from": "2026-11-07T00:00:00Z",
                  "generated_at": "2026-11-14T09:00:02Z",
                  "granularity": "day",
                  "group_by": [
                    "mcp"
                  ],
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "row_count": 1,
                  "rows": [
                    {
                      "avg_duration_ms": 412.5,
                      "blocked": 8,
                      "errors": 31,
                      "mcp": "a1b2c3d4",
                      "mcp_name": "Files",
                      "p95_duration_ms": 1630.0,
                      "period_start": "2026-11-12T00:00:00Z",
                      "requests": 1840,
                      "response_chars": 9120034,
                      "success": 1801,
                      "tool_argument_chars": 220481,
                      "unique_tools": 9,
                      "unique_users": 37
                    }
                  ],
                  "timezone": "UTC",
                  "to": "2026-11-14T00:00:00Z",
                  "totals": {
                    "avg_duration_ms": 412.5,
                    "blocked": 8,
                    "errors": 31,
                    "p95_duration_ms": 1630.0,
                    "requests": 1840,
                    "response_chars": 9120034,
                    "success": 1801,
                    "tool_argument_chars": 220481,
                    "unique_tools": 9,
                    "unique_users": 37
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/UsageReport"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Usage report",
        "tags": [
          "Analytics"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/user-connections": {
      "get": {
        "description": "Every known user of the tenant with how many MCPs are in each connection state.",
        "operationId": "List_user_connections",
        "parameters": [
          {
            "description": "Page size, 1 to 200 (default 50).",
            "example": 50,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "generated_at": "2026-11-14T09:00:00Z",
                  "items": [
                    {
                      "email": "dana@example.com",
                      "mcp_states": {
                        "signed_in": 2
                      },
                      "registered_at": "2026-10-01T08:00:00Z",
                      "user_types": [
                        "user"
                      ]
                    }
                  ],
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/UserConnections"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "List users",
        "tags": [
          "User connections"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/user-connections/{email}": {
      "get": {
        "description": "Connection state of each MCP for one user. 404 when the user is unknown.",
        "operationId": "Read_a_user_connections",
        "parameters": [
          {
            "description": "User email (case-insensitive).",
            "example": "dana@example.com",
            "in": "path",
            "name": "email",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Page size, 1 to 200 (default 50).",
            "example": 50,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page. 409 `collection_changed` when the list changed; restart.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "email": "dana@example.com",
                  "generated_at": "2026-11-14T09:00:00Z",
                  "items": [
                    {
                      "access_allowed": true,
                      "can_renew": true,
                      "mcp_id": "a1b2c3d4",
                      "name": "Files",
                      "preference_enabled": true,
                      "set_up_at": "2026-11-01T10:00:00Z",
                      "signed_in_until": "2026-11-14T11:00:00Z",
                      "slug": "files",
                      "state": "signed_in"
                    }
                  ],
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f"
                },
                "schema": {
                  "$ref": "#/components/schemas/UserMcpConnections"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Read a user's MCP connections",
        "tags": [
          "User connections"
        ],
        "x-scopes": [
          "read"
        ]
      }
    },
    "/mcpgateway/management/v1/users": {
      "get": {
        "description": "Per user: calls, successes, errors, blocked calls, MCPs and tools used, first and last seen (default the last 30 days). Calls without a recorded user are one row with `user` null.",
        "operationId": "List_users",
        "parameters": [
          {
            "description": "Inclusive start: RFC 3339 time with a timezone, or a date (UTC midnight). Default: UTC midnight 30 days before `to`. At most 92 days before `to`.",
            "example": "2026-11-01",
            "in": "query",
            "name": "from",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exclusive end: RFC 3339 time with a timezone, or a date (through the end of that UTC day). Default: now.",
            "example": "2026-11-08",
            "in": "query",
            "name": "to",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. MCP ids.",
            "in": "query",
            "name": "mcp",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact tool values.",
            "in": "query",
            "name": "tool",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. User emails (case-insensitive).",
            "in": "query",
            "name": "user",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact agent values.",
            "in": "query",
            "name": "agent",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact called via values.",
            "in": "query",
            "name": "called_via",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact auth mode values.",
            "in": "query",
            "name": "auth_mode",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. Exact transport values.",
            "in": "query",
            "name": "transport",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Comma-separated values (at most 50); matches any. One of success, error, blocked.",
            "in": "query",
            "name": "outcome",
            "required": false,
            "schema": {
              "description": "Comma-separated, any of: success, error, blocked",
              "type": "string"
            }
          },
          {
            "description": "Row order: calls, errors, blocked, last_seen, user.",
            "in": "query",
            "name": "sort",
            "required": false,
            "schema": {
              "enum": [
                "calls",
                "errors",
                "blocked",
                "last_seen",
                "user"
              ],
              "type": "string"
            }
          },
          {
            "description": "Rows per page, 1 to 1000 (default 100).",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "maximum": 1000,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The `next_cursor` of the previous page of the same query. 409 `collection_changed` when the result was recomputed and differs.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data_through": "2026-11-14T00:00:00Z",
                  "from": "2026-11-07T00:00:00Z",
                  "generated_at": "2026-11-14T09:00:02Z",
                  "next_cursor": null,
                  "request_id": "8d0f6c1e2a4b4c9d9e7f1a2b3c4d5e6f",
                  "row_count": 1,
                  "rows": [
                    {
                      "blocked": 1,
                      "calls": 120,
                      "errors": 2,
                      "first_seen": "2026-10-16T08:00:00Z",
                      "last_seen": "2026-11-14T08:59:58Z",
                      "mcps_used": 3,
                      "success": 117,
                      "tools_used": 7,
                      "user": "dana@example.com"
                    }
                  ],
                  "timezone": "UTC",
                  "to": "2026-11-14T00:00:00Z",
                  "totals": {
                    "blocked": 1,
                    "calls": 120,
                    "errors": 2,
                    "mcps_used": 3,
                    "success": 117,
                    "tools_used": 7,
                    "users": 1
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/UsersReport"
                }
              }
            },
            "description": "Success",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/Cache-Control"
              },
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "X-Request-ID": {
                "$ref": "#/components/headers/X-Request-ID"
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/Unprocessable"
          },
          "429": {
            "$ref": "#/components/responses/Busy"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "security": [
          {
            "ManagementKey": []
          }
        ],
        "summary": "Per-user activity",
        "tags": [
          "Analytics"
        ],
        "x-scopes": [
          "read"
        ]
      }
    }
  },
  "servers": [
    {
      "url": "https://mcpgateway.quilr.ai"
    }
  ],
  "tags": [
    {
      "description": "Discover what this deployment supports, download this document and follow long-running operations.",
      "name": "Reference"
    },
    {
      "description": "List, inspect, create, rename, enable, disable and remove the MCPs of your tenant, including MCPs that expose a REST API as tools.",
      "name": "MCPs"
    },
    {
      "description": "Per-MCP settings (tools, DLP, token saving, access control, tool exposure and more) and per-user or per-smart-group overrides.",
      "name": "Settings"
    },
    {
      "description": "Static credentials and extra headers or query parameters that the gateway sends to an MCP's upstream server. Secrets are write-only.",
      "name": "Upstream credentials"
    },
    {
      "description": "Approve or reject new upstream tools held for review.",
      "name": "Tool reviews"
    },
    {
      "description": "Connection state of an MCP, tool refresh, and single-use OAuth connect links: whoever opens one in a browser signs in with the provider, and the connection is saved for the administrator who owns the issuing key.",
      "name": "Connections"
    },
    {
      "description": "The MCP Library: prebuilt MCPs your tenant can install.",
      "name": "Catalog"
    },
    {
      "description": "Who changed what: configuration changes made in the Quilr console and through this API, newest first.",
      "name": "Audit"
    },
    {
      "description": "Tool-call usage, latency, DLP activity, request metadata and per-user activity over any period up to 92 days.",
      "name": "Analytics"
    },
    {
      "description": "Hand an MCP out: endpoint URLs and client configuration, MCP API tokens for clients without sign-in, and which agents may use each MCP.",
      "name": "Client access"
    },
    {
      "description": "Per user and MCP connection state, and revoking one user's stored credentials for an MCP.",
      "name": "User connections"
    },
    {
      "description": "Upstream tool-list changes detected by the tool watch: check now, adopt the new list or dismiss the change.",
      "name": "Tool changes"
    },
    {
      "description": "Tenant-wide switches (Dynamic Tool Calling, Memories, new-tool review), tool-argument aliases and users' requests for MCP Library entries.",
      "name": "Tenant"
    },
    {
      "description": "Change a REST API MCP after it was created: base URL, limits, access rules and which OpenAPI operations become tools; preview a selection, test access rules and resync the OpenAPI document from its source.",
      "name": "REST API MCPs"
    },
    {
      "description": "Rotate an MCP's OAuth client and get the link users open to sign in and connect an MCP themselves.",
      "name": "User sign-in"
    },
    {
      "description": "Add your own tools to an MCP: a short Python script that calls the MCP's tools with default parameters and simple logic (chain, filter, trim). Users and agents see a custom tool like any other tool of the MCP. The custom tool is what you authorize: its own call gets the usual access checks, policies, quotas, approvals, DLP on its arguments and result, and logging. The tools its script calls run as the caller and are logged, but skip their own per-tool checks (enabled setting, policies, quotas, DLP, approvals). So a custom tool can put a check in front of a tool: turn off `read_file` for users (in the MCP's settings or with a policy that denies it) and add `read_file_safe`, which checks the file's folder with `get_file_info` and only then calls `read_file`. Users still cannot call the turned-off tool themselves. A discovery policy only hides a tool from tool lists; it does not stop users from calling it.",
      "name": "Custom tools"
    },
    {
      "description": "Tenant-administrator endpoints that enable management for a tenant and issue management keys. Authenticated with a tenant administrator token, not a management key.",
      "name": "Administration"
    }
  ],
  "x-scope-descriptions": {
    "agents:write": "Create and delete custom agents.",
    "connections:write": "Revoke a user's stored credentials for an MCP.",
    "credentials:write": "Set or remove upstream credentials and extra headers or query parameters (also needed for any create, check or preview that carries credentials).",
    "mcps:write": "Create, rename, enable, disable and remove MCPs, install catalog MCPs, check MCP URLs, preview REST API specs, refresh tools and issue OAuth connect links.",
    "read": "Read MCPs, tools, settings, credential metadata, tool reviews, connection state, the catalog, operations, analytics and this document.",
    "settings:write": "Change MCP settings and per-user or per-smart-group overrides (also needed to send settings with a create).",
    "tenant_settings:write": "Change tenant switches, manage tool-argument aliases and dismiss users' MCP requests.",
    "tokens:write": "Issue and revoke MCP API tokens.",
    "tool_reviews:write": "Approve or reject tools held for review, and check, adopt or dismiss upstream tool changes.",
    "tools:write": "Create, change, delete and test-run custom tools. Test runs call the MCP as the key owner."
  }
}
