From 324c361c4cb85a009422cba3b9513bddac73199c Mon Sep 17 00:00:00 2001 From: Pavel Tisnovsky Date: Thu, 22 Jan 2026 08:52:14 +0100 Subject: [PATCH] LCORE-1219: up to date OpenAPI specifiction after MCP patch was merged --- docs/openapi.json | 171 +++++++++++++++++++++++++++++++++++++++++++++- docs/openapi.md | 144 +++++++++++++++++++++++++++++++++++++- 2 files changed, 311 insertions(+), 4 deletions(-) diff --git a/docs/openapi.json b/docs/openapi.json index 5f1e2d05..85878971 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -102,7 +102,7 @@ "info" ], "summary": "Info Endpoint Handler", - "description": "Handle request to the /info endpoint.\n\nProcess GET requests to the /info endpoint, returning the\nservice name, version and Llama-stack version.\n\nReturns:\n InfoResponse: An object containing the service's name and version.", + "description": "Handle request to the /info endpoint.\n\nProcess GET requests to the /info endpoint, returning the\nservice name, version and Llama-stack version.\n\nRaises:\n HTTPException: with status 500 and a detail object\n containing `response` and `cause` when unable to connect to\n Llama Stack. It can also return status 401 or 403 for\n unauthorized access.\n\nReturns:\n InfoResponse: An object containing the service's name and version.", "operationId": "info_endpoint_handler_v1_info_get", "responses": { "200": { @@ -492,6 +492,113 @@ } } }, + "/v1/mcp-auth/client-options": { + "get": { + "tags": [ + "mcp-auth" + ], + "summary": "Get Mcp Client Auth Options", + "description": "Get MCP servers that accept client-provided authorization.\n\nReturns a list of MCP servers configured to accept client-provided\nauthorization tokens, along with the header names where clients\nshould provide these tokens.\n\nThis endpoint helps clients discover which MCP servers they can\nauthenticate with using their own tokens.\n\nArgs:\n request: The incoming HTTP request (used by middleware).\n auth: Authentication tuple from the auth dependency (used by middleware).\n\nReturns:\n MCPClientAuthOptionsResponse: List of MCP servers and their\n accepted client authentication headers.", + "operationId": "get_mcp_client_auth_options_v1_mcp_auth_client_options_get", + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MCPClientAuthOptionsResponse" + }, + "example": { + "servers": [ + { + "client_auth_headers": [ + "Authorization" + ], + "name": "github" + }, + { + "client_auth_headers": [ + "Authorization", + "X-API-Key" + ], + "name": "gitlab" + } + ] + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + }, + "examples": { + "missing header": { + "value": { + "detail": { + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" + } + } + }, + "missing token": { + "value": { + "detail": { + "cause": "No token found in Authorization header", + "response": "Missing or invalid credentials provided by client" + } + } + } + } + } + } + }, + "403": { + "description": "Permission denied", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + }, + "examples": { + "endpoint": { + "value": { + "detail": { + "cause": "User 6789 is not authorized to access this endpoint.", + "response": "User does not have permission to access this endpoint" + } + } + } + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InternalServerErrorResponse" + }, + "examples": { + "configuration": { + "value": { + "detail": { + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" + } + } + } + } + } + } + } + } + } + }, "/v1/shields": { "get": { "tags": [ @@ -1777,7 +1884,7 @@ "config" ], "summary": "Config Endpoint Handler", - "description": "Handle requests to the /config endpoint.\n\nProcess GET requests to the /config endpoint and returns the\ncurrent service configuration.\n\nReturns:\n ConfigurationResponse: The loaded service configuration response.", + "description": "Handle requests to the /config endpoint.\n\nProcess GET requests to the /config endpoint and returns the\ncurrent service configuration.\n\nEnsures the application configuration is loaded before returning it.\n\nReturns:\n ConfigurationResponse: The loaded service configuration response.", "operationId": "config_endpoint_handler_v1_config_get", "responses": { "200": { @@ -3945,7 +4052,7 @@ "authorized" ], "summary": "Authorized Endpoint Handler", - "description": "Handle request to the /authorized endpoint.\n\nProcess POST requests to the /authorized endpoint, returning\nthe authenticated user's ID and username.\n\nReturns:\n AuthorizedResponse: Contains the user ID and username of the authenticated user.", + "description": "Handle request to the /authorized endpoint.\n\nProcess POST requests to the /authorized endpoint, returning\nthe authenticated user's ID and username.\n\nThe response intentionally omits any authentication token.\n\nReturns:\n AuthorizedResponse: Contains the user ID and username of the authenticated user.", "operationId": "authorized_endpoint_handler_authorized_post", "responses": { "200": { @@ -6839,6 +6946,64 @@ "title": "LlamaStackConfiguration", "description": "Llama stack configuration.\n\nLlama Stack is a comprehensive system that provides a uniform set of tools\nfor building, scaling, and deploying generative AI applications, enabling\ndevelopers to create, integrate, and orchestrate multiple AI services and\ncapabilities into an adaptable setup.\n\nUseful resources:\n\n - [Llama Stack](https://www.llama.com/products/llama-stack/)\n - [Python Llama Stack client](https://github.com/llamastack/llama-stack-client-python)\n - [Build AI Applications with Llama Stack](https://llamastack.github.io/)" }, + "MCPClientAuthOptionsResponse": { + "properties": { + "servers": { + "items": { + "$ref": "#/components/schemas/MCPServerAuthInfo" + }, + "type": "array", + "title": "Servers", + "description": "List of MCP servers that accept client-provided authorization" + } + }, + "type": "object", + "title": "MCPClientAuthOptionsResponse", + "description": "Response containing MCP servers that accept client-provided authorization.", + "examples": [ + { + "servers": [ + { + "client_auth_headers": [ + "Authorization" + ], + "name": "github" + }, + { + "client_auth_headers": [ + "Authorization", + "X-API-Key" + ], + "name": "gitlab" + } + ] + } + ] + }, + "MCPServerAuthInfo": { + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "MCP server name" + }, + "client_auth_headers": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Client Auth Headers", + "description": "List of authentication header names for client-provided tokens" + } + }, + "type": "object", + "required": [ + "name", + "client_auth_headers" + ], + "title": "MCPServerAuthInfo", + "description": "Information about MCP server client authentication options." + }, "ModelContextProtocolServer": { "properties": { "name": { diff --git a/docs/openapi.md b/docs/openapi.md index eb598b01..15a62a77 100644 --- a/docs/openapi.md +++ b/docs/openapi.md @@ -87,6 +87,12 @@ Handle request to the /info endpoint. Process GET requests to the /info endpoint, returning the service name, version and Llama-stack version. +Raises: + HTTPException: with status 500 and a detail object + containing `response` and `cause` when unable to connect to + Llama Stack. It can also return status 401 or 403 for + unauthorized access. + Returns: InfoResponse: An object containing the service's name and version. @@ -443,6 +449,99 @@ Examples "response": "Unable to connect to Llama Stack" } } +``` + | +## GET `/v1/mcp-auth/client-options` + +> **Get Mcp Client Auth Options** + +Get MCP servers that accept client-provided authorization. + +Returns a list of MCP servers configured to accept client-provided +authorization tokens, along with the header names where clients +should provide these tokens. + +This endpoint helps clients discover which MCP servers they can +authenticate with using their own tokens. + +Args: + request: The incoming HTTP request (used by middleware). + auth: Authentication tuple from the auth dependency (used by middleware). + +Returns: + MCPClientAuthOptionsResponse: List of MCP servers and their + accepted client authentication headers. + + + + + +### ✅ Responses + +| Status Code | Description | Component | +|-------------|-------------|-----------| +| 200 | Successful response | [MCPClientAuthOptionsResponse](#mcpclientauthoptionsresponse) | +| 401 | Unauthorized | [UnauthorizedResponse](#unauthorizedresponse) + +Examples + + + + + +```json +{ + "detail": { + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" + } +} +``` + + + + +```json +{ + "detail": { + "cause": "No token found in Authorization header", + "response": "Missing or invalid credentials provided by client" + } +} +``` + | +| 403 | Permission denied | [ForbiddenResponse](#forbiddenresponse) + +Examples + + + + + +```json +{ + "detail": { + "cause": "User 6789 is not authorized to access this endpoint.", + "response": "User does not have permission to access this endpoint" + } +} +``` + | +| 500 | Internal server error | [InternalServerErrorResponse](#internalservererrorresponse) + +Examples + + + + + +```json +{ + "detail": { + "cause": "Lightspeed Stack configuration has not been initialized.", + "response": "Configuration is not loaded" + } +} ``` | ## GET `/v1/shields` @@ -1639,6 +1738,8 @@ Handle requests to the /config endpoint. Process GET requests to the /config endpoint and returns the current service configuration. +Ensures the application configuration is loaded before returning it. + Returns: ConfigurationResponse: The loaded service configuration response. @@ -3469,6 +3570,8 @@ Handle request to the /authorized endpoint. Process POST requests to the /authorized endpoint, returning the authenticated user's ID and username. +The response intentionally omits any authentication token. + Returns: AuthorizedResponse: Contains the user ID and username of the authenticated user. @@ -4748,6 +4851,29 @@ Useful resources: | library_client_config_path | | Path to configuration file used when Llama Stack is run in library mode | +## MCPClientAuthOptionsResponse + + +Response containing MCP servers that accept client-provided authorization. + + +| Field | Type | Description | +|-------|------|-------------| +| servers | array | List of MCP servers that accept client-provided authorization | + + +## MCPServerAuthInfo + + +Information about MCP server client authentication options. + + +| Field | Type | Description | +|-------|------|-------------| +| name | string | MCP server name | +| client_auth_headers | array | List of authentication header names for client-provided tokens | + + ## ModelContextProtocolServer @@ -4982,9 +5108,11 @@ Model representing LLM response to a query. Attributes: conversation_id: The optional conversation ID (UUID). response: The response. - rag_chunks: List of RAG chunks used to generate the response. + rag_chunks: Deprecated. List of RAG chunks used to generate the response. + This information is now available in tool_results under file_search_call type. referenced_documents: The URLs and titles for the documents used to generate the response. tool_calls: List of tool calls made during response generation. + tool_results: List of tool results. truncated: Whether conversation history was truncated. input_tokens: Number of tokens sent to LLM. output_tokens: Number of tokens received from LLM. @@ -4995,6 +5123,7 @@ Attributes: |-------|------|-------------| | conversation_id | | The optional conversation ID (UUID) | | response | string | Response from LLM | +| rag_chunks | array | Deprecated: List of RAG chunks used to generate the response. | | referenced_documents | array | List of documents referenced in generating the response | | truncated | boolean | Whether conversation history was truncated | | input_tokens | integer | Number of tokens sent to LLM | @@ -5082,6 +5211,19 @@ Quota scheduler configuration. | database_reconnection_delay | integer | Database reconnection delay specified in seconds. When database for quota is not available on startup, the service tries to reconnect N times with specified delay. | +## RAGChunk + + +Model representing a RAG chunk used in the response. + + +| Field | Type | Description | +|-------|------|-------------| +| content | string | The content of the chunk | +| source | | Source document or URL | +| score | | Relevance score | + + ## RAGInfoResponse