feati(api): add connectors API

Closes #4235 and #4061 (partially)

Signed-off-by: Jaideep Rao <jrao@redhat.com>

client-sdks/stainless/config.yml

@@ -427,6 +427,24 @@ resources:
       cancel: post /v1/batches/{batch_id}/cancel
   alpha:
     subresources:
+      connectors:
+        models:
+          connector: Connector
+          list_connectors_response: ListConnectorsResponse
+          list_tools_response: ListToolsResponse
+          tool_def: ToolDef
+        methods:
+          list:
+            paginated: false
+            endpoint: get /v1alpha/connectors
+          retrieve: get /v1alpha/connectors/{connector_id}
+        subresources:
+          tools:
+            methods:
+              list:
+                paginated: false
+                endpoint: get /v1alpha/connectors/{connector_id}/tools
+              retrieve: get /v1alpha/connectors/{connector_id}/tools/{tool_name}
       inference:
         methods:
           rerank: post /v1alpha/inference/rerank

client-sdks/stainless/openapi.yml

@@ -3893,6 +3893,160 @@ paths:
             schema:
               $ref: '#/components/schemas/SupervisedFineTuneRequest'
         required: true
+  /v1alpha/connectors/{connector_id}:
+    get:
+      responses:
+        '200':
+          description: A Connector.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Connector'
+        '400':
+          $ref: '#/components/responses/BadRequest400'
+          description: Bad Request
+        '429':
+          $ref: '#/components/responses/TooManyRequests429'
+          description: Too Many Requests
+        '500':
+          $ref: '#/components/responses/InternalServerError500'
+          description: Internal Server Error
+        default:
+          $ref: '#/components/responses/DefaultError'
+          description: Default Response
+      tags:
+      - Connectors
+      summary: Get Connector
+      description: Get a connector by its ID.
+      operationId: get_connector_v1alpha_connectors__connector_id__get
+      parameters:
+      - name: include_tools
+        in: query
+        required: false
+        schema:
+          type: boolean
+          default: false
+          title: Include Tools
+      - name: connector_id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: 'Path parameter: connector_id'
+  /v1alpha/connectors/{connector_id}/tools/{tool_name}:
+    get:
+      responses:
+        '200':
+          description: A ToolDef.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ToolDef'
+        '400':
+          description: Bad Request
+          $ref: '#/components/responses/BadRequest400'
+        '429':
+          description: Too Many Requests
+          $ref: '#/components/responses/TooManyRequests429'
+        '500':
+          description: Internal Server Error
+          $ref: '#/components/responses/InternalServerError500'
+        default:
+          description: Default Response
+          $ref: '#/components/responses/DefaultError'
+      tags:
+      - Connectors
+      summary: Get Connector Tool
+      description: Get a tool definition by its name from a connector.
+      operationId: get_connector_tool_v1alpha_connectors__connector_id__tools__tool_name__get
+      parameters:
+      - name: connector_id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: 'Path parameter: connector_id'
+      - name: tool_name
+        in: path
+        required: true
+        schema:
+          type: string
+        description: 'Path parameter: tool_name'
+  /v1alpha/connectors/{connector_id}/tools:
+    get:
+      responses:
+        '200':
+          description: A ListToolsResponse.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListToolsResponse'
+        '400':
+          description: Bad Request
+          $ref: '#/components/responses/BadRequest400'
+        '429':
+          description: Too Many Requests
+          $ref: '#/components/responses/TooManyRequests429'
+        '500':
+          description: Internal Server Error
+          $ref: '#/components/responses/InternalServerError500'
+        default:
+          description: Default Response
+          $ref: '#/components/responses/DefaultError'
+      tags:
+      - Connectors
+      summary: List Connector Tools
+      description: List tools available from a connector.
+      operationId: list_connector_tools_v1alpha_connectors__connector_id__tools_get
+      parameters:
+      - name: connector_id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: 'Path parameter: connector_id'
+  /v1alpha/connectors:
+    get:
+      responses:
+        '200':
+          description: A ListConnectorsResponse.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListConnectorsResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest400'
+          description: Bad Request
+        '429':
+          $ref: '#/components/responses/TooManyRequests429'
+          description: Too Many Requests
+        '500':
+          $ref: '#/components/responses/InternalServerError500'
+          description: Internal Server Error
+        default:
+          $ref: '#/components/responses/DefaultError'
+          description: Default Response
+      tags:
+      - Connectors
+      summary: List Connectors
+      description: List all configured connectors.
+      operationId: list_connectors_v1alpha_connectors_get
+      parameters:
+      - name: include_tools
+        in: query
+        required: false
+        schema:
+          type: boolean
+          default: false
+          title: Include Tools
+      - name: registry_id
+        in: query
+        required: false
+        schema:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Registry Id
 components:
   schemas:
     Error:
@@ -11618,6 +11772,90 @@ components:
       - chunk_id
       title: Chunk
       description: A chunk of content that can be inserted into a vector database.
+    Connector:
+      properties:
+        identifier:
+          type: string
+          title: Identifier
+          description: Unique identifier for this resource in llama stack
+        provider_resource_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Unique identifier for this resource in the provider
+        provider_id:
+          type: string
+          title: Provider Id
+          description: ID of the provider that owns this resource
+        type:
+          type: string
+          const: connector
+          title: Type
+          default: connector
+        connector_type:
+          $ref: '#/components/schemas/ConnectorType'
+          default: mcp
+        connector_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: User-specified identifier for the connector
+        url:
+          type: string
+          title: Url
+          description: URL of the connector
+        created_at:
+          type: string
+          format: date-time
+          title: Created At
+          description: Timestamp of creation
+        updated_at:
+          type: string
+          format: date-time
+          title: Updated At
+          description: Timestamp of last update
+        server_name:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Name of the server
+        server_label:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Label of the server
+        server_description:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Description of the server
+        tools:
+          anyOf:
+          - items:
+              $ref: '#/components/schemas/ToolDef'
+            type: array
+          - type: 'null'
+          description: List of tools available from the connector
+        registry_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: ID of the registry this connector belongs to
+      type: object
+      required:
+      - identifier
+      - provider_id
+      - url
+      - created_at
+      - updated_at
+      title: Connector
+      description: A connector resource representing a connector registered in Llama Stack.
+    ConnectorType:
+      type: string
+      enum:
+      - mcp
+      title: ConnectorType
+      description: Type of connector.
     ConversationItemInclude:
       type: string
       enum:
@@ -11708,6 +11946,30 @@ components:
       - cancelled
       title: JobStatus
       description: Status of a job execution.
+    ListConnectorsResponse:
+      properties:
+        data:
+          items:
+            $ref: '#/components/schemas/Connector'
+          type: array
+          title: Data
+      type: object
+      required:
+      - data
+      title: ListConnectorsResponse
+      description: Response containing a list of connectors.
+    ListToolsResponse:
+      properties:
+        data:
+          items:
+            $ref: '#/components/schemas/ToolDef'
+          type: array
+          title: Data
+      type: object
+      required:
+      - data
+      title: ListToolsResponse
+      description: Response containing a list of tools.
     MCPListToolsTool:
       properties:
         input_schema:
@@ -12573,6 +12835,66 @@ components:
           type: string
       title: DialogType
       type: object
+    ToolGroupInput:
+      description: Input data for registering a tool group.
+      properties:
+        toolgroup_id:
+          title: Toolgroup Id
+          type: string
+        provider_id:
+          title: Provider Id
+          type: string
+        args:
+          anyOf:
+          - additionalProperties: true
+            type: object
+          - type: 'null'
+          nullable: true
+        mcp_endpoint:
+          anyOf:
+          - $ref: '#/components/schemas/URL'
+            title: URL
+          - type: 'null'
+          nullable: true
+          title: URL
+      required:
+      - toolgroup_id
+      - provider_id
+      title: ToolGroupInput
+      type: object
+    ConnectorInput:
+      description: Input for creating a connector.
+      properties:
+        connector_type:
+          $ref: '#/components/schemas/ConnectorType'
+          default: mcp
+        connector_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Unique identifier for the connector
+          nullable: true
+        url:
+          description: URL of the connector
+          title: Url
+          type: string
+        headers:
+          anyOf:
+          - additionalProperties: true
+            type: object
+          - type: 'null'
+          description: HTTP headers to include when connecting
+          nullable: true
+        authorization:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: OAuth access token for authentication
+          nullable: true
+      required:
+      - url
+      title: ConnectorInput
+      type: object
     ConversationMessage:
       description: OpenAI-compatible message item for conversations.
       properties:
@@ -12657,33 +12979,6 @@ components:
       - items
       title: ConversationItemCreateRequest
       type: object
-    ToolGroupInput:
-      description: Input data for registering a tool group.
-      properties:
-        toolgroup_id:
-          title: Toolgroup Id
-          type: string
-        provider_id:
-          title: Provider Id
-          type: string
-        args:
-          anyOf:
-          - additionalProperties: true
-            type: object
-          - type: 'null'
-          nullable: true
-        mcp_endpoint:
-          anyOf:
-          - $ref: '#/components/schemas/URL'
-            title: URL
-          - type: 'null'
-          nullable: true
-          title: URL
-      required:
-      - toolgroup_id
-      - provider_id
-      title: ToolGroupInput
-      type: object
     Api:
       description: Enumeration of all available APIs in the Llama Stack system.
       enum:
@@ -12708,6 +13003,7 @@ components:
       - files
       - prompts
       - conversations
+      - connectors
       - inspect
       title: Api
       type: string

docs/static/deprecated-llama-stack-spec.yaml

@@ -8612,6 +8612,90 @@ components:
       - chunk_id
       title: Chunk
       description: A chunk of content that can be inserted into a vector database.
+    Connector:
+      properties:
+        identifier:
+          type: string
+          title: Identifier
+          description: Unique identifier for this resource in llama stack
+        provider_resource_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Unique identifier for this resource in the provider
+        provider_id:
+          type: string
+          title: Provider Id
+          description: ID of the provider that owns this resource
+        type:
+          type: string
+          const: connector
+          title: Type
+          default: connector
+        connector_type:
+          $ref: '#/components/schemas/ConnectorType'
+          default: mcp
+        connector_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: User-specified identifier for the connector
+        url:
+          type: string
+          title: Url
+          description: URL of the connector
+        created_at:
+          type: string
+          format: date-time
+          title: Created At
+          description: Timestamp of creation
+        updated_at:
+          type: string
+          format: date-time
+          title: Updated At
+          description: Timestamp of last update
+        server_name:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Name of the server
+        server_label:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Label of the server
+        server_description:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Description of the server
+        tools:
+          anyOf:
+          - items:
+              $ref: '#/components/schemas/ToolDef'
+            type: array
+          - type: 'null'
+          description: List of tools available from the connector
+        registry_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: ID of the registry this connector belongs to
+      type: object
+      required:
+      - identifier
+      - provider_id
+      - url
+      - created_at
+      - updated_at
+      title: Connector
+      description: A connector resource representing a connector registered in Llama Stack.
+    ConnectorType:
+      type: string
+      enum:
+      - mcp
+      title: ConnectorType
+      description: Type of connector.
     ConversationItemInclude:
       type: string
       enum:
@@ -8702,6 +8786,30 @@ components:
       - cancelled
       title: JobStatus
       description: Status of a job execution.
+    ListConnectorsResponse:
+      properties:
+        data:
+          items:
+            $ref: '#/components/schemas/Connector'
+          type: array
+          title: Data
+      type: object
+      required:
+      - data
+      title: ListConnectorsResponse
+      description: Response containing a list of connectors.
+    ListToolsResponse:
+      properties:
+        data:
+          items:
+            $ref: '#/components/schemas/ToolDef'
+          type: array
+          title: Data
+      type: object
+      required:
+      - data
+      title: ListToolsResponse
+      description: Response containing a list of tools.
     MCPListToolsTool:
       properties:
         input_schema:
@@ -9567,6 +9675,66 @@ components:
           type: string
       title: DialogType
       type: object
+    ToolGroupInput:
+      description: Input data for registering a tool group.
+      properties:
+        toolgroup_id:
+          title: Toolgroup Id
+          type: string
+        provider_id:
+          title: Provider Id
+          type: string
+        args:
+          anyOf:
+          - additionalProperties: true
+            type: object
+          - type: 'null'
+          nullable: true
+        mcp_endpoint:
+          anyOf:
+          - $ref: '#/components/schemas/URL'
+            title: URL
+          - type: 'null'
+          nullable: true
+          title: URL
+      required:
+      - toolgroup_id
+      - provider_id
+      title: ToolGroupInput
+      type: object
+    ConnectorInput:
+      description: Input for creating a connector.
+      properties:
+        connector_type:
+          $ref: '#/components/schemas/ConnectorType'
+          default: mcp
+        connector_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Unique identifier for the connector
+          nullable: true
+        url:
+          description: URL of the connector
+          title: Url
+          type: string
+        headers:
+          anyOf:
+          - additionalProperties: true
+            type: object
+          - type: 'null'
+          description: HTTP headers to include when connecting
+          nullable: true
+        authorization:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: OAuth access token for authentication
+          nullable: true
+      required:
+      - url
+      title: ConnectorInput
+      type: object
     ConversationMessage:
       description: OpenAI-compatible message item for conversations.
       properties:
@@ -9651,33 +9819,6 @@ components:
       - items
       title: ConversationItemCreateRequest
       type: object
-    ToolGroupInput:
-      description: Input data for registering a tool group.
-      properties:
-        toolgroup_id:
-          title: Toolgroup Id
-          type: string
-        provider_id:
-          title: Provider Id
-          type: string
-        args:
-          anyOf:
-          - additionalProperties: true
-            type: object
-          - type: 'null'
-          nullable: true
-        mcp_endpoint:
-          anyOf:
-          - $ref: '#/components/schemas/URL'
-            title: URL
-          - type: 'null'
-          nullable: true
-          title: URL
-      required:
-      - toolgroup_id
-      - provider_id
-      title: ToolGroupInput
-      type: object
     Api:
       description: Enumeration of all available APIs in the Llama Stack system.
       enum:
@@ -9702,6 +9843,7 @@ components:
       - files
       - prompts
       - conversations
+      - connectors
       - inspect
       title: Api
       type: string

docs/static/experimental-llama-stack-spec.yaml

@@ -630,6 +630,160 @@ paths:
             schema:
               $ref: '#/components/schemas/SupervisedFineTuneRequest'
         required: true
+  /v1alpha/connectors/{connector_id}:
+    get:
+      responses:
+        '200':
+          description: A Connector.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Connector'
+        '400':
+          $ref: '#/components/responses/BadRequest400'
+          description: Bad Request
+        '429':
+          $ref: '#/components/responses/TooManyRequests429'
+          description: Too Many Requests
+        '500':
+          $ref: '#/components/responses/InternalServerError500'
+          description: Internal Server Error
+        default:
+          $ref: '#/components/responses/DefaultError'
+          description: Default Response
+      tags:
+      - Connectors
+      summary: Get Connector
+      description: Get a connector by its ID.
+      operationId: get_connector_v1alpha_connectors__connector_id__get
+      parameters:
+      - name: include_tools
+        in: query
+        required: false
+        schema:
+          type: boolean
+          default: false
+          title: Include Tools
+      - name: connector_id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: 'Path parameter: connector_id'
+  /v1alpha/connectors/{connector_id}/tools/{tool_name}:
+    get:
+      responses:
+        '200':
+          description: A ToolDef.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ToolDef'
+        '400':
+          description: Bad Request
+          $ref: '#/components/responses/BadRequest400'
+        '429':
+          description: Too Many Requests
+          $ref: '#/components/responses/TooManyRequests429'
+        '500':
+          description: Internal Server Error
+          $ref: '#/components/responses/InternalServerError500'
+        default:
+          description: Default Response
+          $ref: '#/components/responses/DefaultError'
+      tags:
+      - Connectors
+      summary: Get Connector Tool
+      description: Get a tool definition by its name from a connector.
+      operationId: get_connector_tool_v1alpha_connectors__connector_id__tools__tool_name__get
+      parameters:
+      - name: connector_id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: 'Path parameter: connector_id'
+      - name: tool_name
+        in: path
+        required: true
+        schema:
+          type: string
+        description: 'Path parameter: tool_name'
+  /v1alpha/connectors/{connector_id}/tools:
+    get:
+      responses:
+        '200':
+          description: A ListToolsResponse.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListToolsResponse'
+        '400':
+          description: Bad Request
+          $ref: '#/components/responses/BadRequest400'
+        '429':
+          description: Too Many Requests
+          $ref: '#/components/responses/TooManyRequests429'
+        '500':
+          description: Internal Server Error
+          $ref: '#/components/responses/InternalServerError500'
+        default:
+          description: Default Response
+          $ref: '#/components/responses/DefaultError'
+      tags:
+      - Connectors
+      summary: List Connector Tools
+      description: List tools available from a connector.
+      operationId: list_connector_tools_v1alpha_connectors__connector_id__tools_get
+      parameters:
+      - name: connector_id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: 'Path parameter: connector_id'
+  /v1alpha/connectors:
+    get:
+      responses:
+        '200':
+          description: A ListConnectorsResponse.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListConnectorsResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest400'
+          description: Bad Request
+        '429':
+          $ref: '#/components/responses/TooManyRequests429'
+          description: Too Many Requests
+        '500':
+          $ref: '#/components/responses/InternalServerError500'
+          description: Internal Server Error
+        default:
+          $ref: '#/components/responses/DefaultError'
+          description: Default Response
+      tags:
+      - Connectors
+      summary: List Connectors
+      description: List all configured connectors.
+      operationId: list_connectors_v1alpha_connectors_get
+      parameters:
+      - name: include_tools
+        in: query
+        required: false
+        schema:
+          type: boolean
+          default: false
+          title: Include Tools
+      - name: registry_id
+        in: query
+        required: false
+        schema:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Registry Id
 components:
   schemas:
     Error:
@@ -7459,6 +7613,90 @@ components:
       - chunk_id
       title: Chunk
       description: A chunk of content that can be inserted into a vector database.
+    Connector:
+      properties:
+        identifier:
+          type: string
+          title: Identifier
+          description: Unique identifier for this resource in llama stack
+        provider_resource_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Unique identifier for this resource in the provider
+        provider_id:
+          type: string
+          title: Provider Id
+          description: ID of the provider that owns this resource
+        type:
+          type: string
+          const: connector
+          title: Type
+          default: connector
+        connector_type:
+          $ref: '#/components/schemas/ConnectorType'
+          default: mcp
+        connector_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: User-specified identifier for the connector
+        url:
+          type: string
+          title: Url
+          description: URL of the connector
+        created_at:
+          type: string
+          format: date-time
+          title: Created At
+          description: Timestamp of creation
+        updated_at:
+          type: string
+          format: date-time
+          title: Updated At
+          description: Timestamp of last update
+        server_name:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Name of the server
+        server_label:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Label of the server
+        server_description:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Description of the server
+        tools:
+          anyOf:
+          - items:
+              $ref: '#/components/schemas/ToolDef'
+            type: array
+          - type: 'null'
+          description: List of tools available from the connector
+        registry_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: ID of the registry this connector belongs to
+      type: object
+      required:
+      - identifier
+      - provider_id
+      - url
+      - created_at
+      - updated_at
+      title: Connector
+      description: A connector resource representing a connector registered in Llama Stack.
+    ConnectorType:
+      type: string
+      enum:
+      - mcp
+      title: ConnectorType
+      description: Type of connector.
     DatasetPurpose:
       type: string
       enum:
@@ -7537,6 +7775,30 @@ components:
       - cancelled
       title: JobStatus
       description: Status of a job execution.
+    ListConnectorsResponse:
+      properties:
+        data:
+          items:
+            $ref: '#/components/schemas/Connector'
+          type: array
+          title: Data
+      type: object
+      required:
+      - data
+      title: ListConnectorsResponse
+      description: Response containing a list of connectors.
+    ListToolsResponse:
+      properties:
+        data:
+          items:
+            $ref: '#/components/schemas/ToolDef'
+          type: array
+          title: Data
+      type: object
+      required:
+      - data
+      title: ListToolsResponse
+      description: Response containing a list of tools.
     MCPListToolsTool:
       properties:
         input_schema:
@@ -8333,6 +8595,66 @@ components:
           type: string
       title: DialogType
       type: object
+    ToolGroupInput:
+      description: Input data for registering a tool group.
+      properties:
+        toolgroup_id:
+          title: Toolgroup Id
+          type: string
+        provider_id:
+          title: Provider Id
+          type: string
+        args:
+          anyOf:
+          - additionalProperties: true
+            type: object
+          - type: 'null'
+          nullable: true
+        mcp_endpoint:
+          anyOf:
+          - $ref: '#/components/schemas/URL'
+            title: URL
+          - type: 'null'
+          nullable: true
+          title: URL
+      required:
+      - toolgroup_id
+      - provider_id
+      title: ToolGroupInput
+      type: object
+    ConnectorInput:
+      description: Input for creating a connector.
+      properties:
+        connector_type:
+          $ref: '#/components/schemas/ConnectorType'
+          default: mcp
+        connector_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Unique identifier for the connector
+          nullable: true
+        url:
+          description: URL of the connector
+          title: Url
+          type: string
+        headers:
+          anyOf:
+          - additionalProperties: true
+            type: object
+          - type: 'null'
+          description: HTTP headers to include when connecting
+          nullable: true
+        authorization:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: OAuth access token for authentication
+          nullable: true
+      required:
+      - url
+      title: ConnectorInput
+      type: object
     ConversationMessage:
       description: OpenAI-compatible message item for conversations.
       properties:
@@ -8417,33 +8739,6 @@ components:
       - items
       title: ConversationItemCreateRequest
       type: object
-    ToolGroupInput:
-      description: Input data for registering a tool group.
-      properties:
-        toolgroup_id:
-          title: Toolgroup Id
-          type: string
-        provider_id:
-          title: Provider Id
-          type: string
-        args:
-          anyOf:
-          - additionalProperties: true
-            type: object
-          - type: 'null'
-          nullable: true
-        mcp_endpoint:
-          anyOf:
-          - $ref: '#/components/schemas/URL'
-            title: URL
-          - type: 'null'
-          nullable: true
-          title: URL
-      required:
-      - toolgroup_id
-      - provider_id
-      title: ToolGroupInput
-      type: object
     Api:
       description: Enumeration of all available APIs in the Llama Stack system.
       enum:
@@ -8468,6 +8763,7 @@ components:
       - files
       - prompts
       - conversations
+      - connectors
       - inspect
       title: Api
       type: string

docs/static/llama-stack-spec.yaml

@@ -10054,6 +10054,90 @@ components:
       - chunk_id
       title: Chunk
       description: A chunk of content that can be inserted into a vector database.
+    Connector:
+      properties:
+        identifier:
+          type: string
+          title: Identifier
+          description: Unique identifier for this resource in llama stack
+        provider_resource_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Unique identifier for this resource in the provider
+        provider_id:
+          type: string
+          title: Provider Id
+          description: ID of the provider that owns this resource
+        type:
+          type: string
+          const: connector
+          title: Type
+          default: connector
+        connector_type:
+          $ref: '#/components/schemas/ConnectorType'
+          default: mcp
+        connector_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: User-specified identifier for the connector
+        url:
+          type: string
+          title: Url
+          description: URL of the connector
+        created_at:
+          type: string
+          format: date-time
+          title: Created At
+          description: Timestamp of creation
+        updated_at:
+          type: string
+          format: date-time
+          title: Updated At
+          description: Timestamp of last update
+        server_name:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Name of the server
+        server_label:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Label of the server
+        server_description:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Description of the server
+        tools:
+          anyOf:
+          - items:
+              $ref: '#/components/schemas/ToolDef'
+            type: array
+          - type: 'null'
+          description: List of tools available from the connector
+        registry_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: ID of the registry this connector belongs to
+      type: object
+      required:
+      - identifier
+      - provider_id
+      - url
+      - created_at
+      - updated_at
+      title: Connector
+      description: A connector resource representing a connector registered in Llama Stack.
+    ConnectorType:
+      type: string
+      enum:
+      - mcp
+      title: ConnectorType
+      description: Type of connector.
     ConversationItemInclude:
       type: string
       enum:
@@ -10144,6 +10228,30 @@ components:
       - cancelled
       title: JobStatus
       description: Status of a job execution.
+    ListConnectorsResponse:
+      properties:
+        data:
+          items:
+            $ref: '#/components/schemas/Connector'
+          type: array
+          title: Data
+      type: object
+      required:
+      - data
+      title: ListConnectorsResponse
+      description: Response containing a list of connectors.
+    ListToolsResponse:
+      properties:
+        data:
+          items:
+            $ref: '#/components/schemas/ToolDef'
+          type: array
+          title: Data
+      type: object
+      required:
+      - data
+      title: ListToolsResponse
+      description: Response containing a list of tools.
     MCPListToolsTool:
       properties:
         input_schema:
@@ -11009,6 +11117,66 @@ components:
           type: string
       title: DialogType
       type: object
+    ToolGroupInput:
+      description: Input data for registering a tool group.
+      properties:
+        toolgroup_id:
+          title: Toolgroup Id
+          type: string
+        provider_id:
+          title: Provider Id
+          type: string
+        args:
+          anyOf:
+          - additionalProperties: true
+            type: object
+          - type: 'null'
+          nullable: true
+        mcp_endpoint:
+          anyOf:
+          - $ref: '#/components/schemas/URL'
+            title: URL
+          - type: 'null'
+          nullable: true
+          title: URL
+      required:
+      - toolgroup_id
+      - provider_id
+      title: ToolGroupInput
+      type: object
+    ConnectorInput:
+      description: Input for creating a connector.
+      properties:
+        connector_type:
+          $ref: '#/components/schemas/ConnectorType'
+          default: mcp
+        connector_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Unique identifier for the connector
+          nullable: true
+        url:
+          description: URL of the connector
+          title: Url
+          type: string
+        headers:
+          anyOf:
+          - additionalProperties: true
+            type: object
+          - type: 'null'
+          description: HTTP headers to include when connecting
+          nullable: true
+        authorization:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: OAuth access token for authentication
+          nullable: true
+      required:
+      - url
+      title: ConnectorInput
+      type: object
     ConversationMessage:
       description: OpenAI-compatible message item for conversations.
       properties:
@@ -11093,33 +11261,6 @@ components:
       - items
       title: ConversationItemCreateRequest
       type: object
-    ToolGroupInput:
-      description: Input data for registering a tool group.
-      properties:
-        toolgroup_id:
-          title: Toolgroup Id
-          type: string
-        provider_id:
-          title: Provider Id
-          type: string
-        args:
-          anyOf:
-          - additionalProperties: true
-            type: object
-          - type: 'null'
-          nullable: true
-        mcp_endpoint:
-          anyOf:
-          - $ref: '#/components/schemas/URL'
-            title: URL
-          - type: 'null'
-          nullable: true
-          title: URL
-      required:
-      - toolgroup_id
-      - provider_id
-      title: ToolGroupInput
-      type: object
     Api:
       description: Enumeration of all available APIs in the Llama Stack system.
       enum:
@@ -11144,6 +11285,7 @@ components:
       - files
       - prompts
       - conversations
+      - connectors
       - inspect
       title: Api
       type: string

docs/static/stainless-llama-stack-spec.yaml

@@ -3893,6 +3893,160 @@ paths:
             schema:
               $ref: '#/components/schemas/SupervisedFineTuneRequest'
         required: true
+  /v1alpha/connectors/{connector_id}:
+    get:
+      responses:
+        '200':
+          description: A Connector.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Connector'
+        '400':
+          $ref: '#/components/responses/BadRequest400'
+          description: Bad Request
+        '429':
+          $ref: '#/components/responses/TooManyRequests429'
+          description: Too Many Requests
+        '500':
+          $ref: '#/components/responses/InternalServerError500'
+          description: Internal Server Error
+        default:
+          $ref: '#/components/responses/DefaultError'
+          description: Default Response
+      tags:
+      - Connectors
+      summary: Get Connector
+      description: Get a connector by its ID.
+      operationId: get_connector_v1alpha_connectors__connector_id__get
+      parameters:
+      - name: include_tools
+        in: query
+        required: false
+        schema:
+          type: boolean
+          default: false
+          title: Include Tools
+      - name: connector_id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: 'Path parameter: connector_id'
+  /v1alpha/connectors/{connector_id}/tools/{tool_name}:
+    get:
+      responses:
+        '200':
+          description: A ToolDef.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ToolDef'
+        '400':
+          description: Bad Request
+          $ref: '#/components/responses/BadRequest400'
+        '429':
+          description: Too Many Requests
+          $ref: '#/components/responses/TooManyRequests429'
+        '500':
+          description: Internal Server Error
+          $ref: '#/components/responses/InternalServerError500'
+        default:
+          description: Default Response
+          $ref: '#/components/responses/DefaultError'
+      tags:
+      - Connectors
+      summary: Get Connector Tool
+      description: Get a tool definition by its name from a connector.
+      operationId: get_connector_tool_v1alpha_connectors__connector_id__tools__tool_name__get
+      parameters:
+      - name: connector_id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: 'Path parameter: connector_id'
+      - name: tool_name
+        in: path
+        required: true
+        schema:
+          type: string
+        description: 'Path parameter: tool_name'
+  /v1alpha/connectors/{connector_id}/tools:
+    get:
+      responses:
+        '200':
+          description: A ListToolsResponse.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListToolsResponse'
+        '400':
+          description: Bad Request
+          $ref: '#/components/responses/BadRequest400'
+        '429':
+          description: Too Many Requests
+          $ref: '#/components/responses/TooManyRequests429'
+        '500':
+          description: Internal Server Error
+          $ref: '#/components/responses/InternalServerError500'
+        default:
+          description: Default Response
+          $ref: '#/components/responses/DefaultError'
+      tags:
+      - Connectors
+      summary: List Connector Tools
+      description: List tools available from a connector.
+      operationId: list_connector_tools_v1alpha_connectors__connector_id__tools_get
+      parameters:
+      - name: connector_id
+        in: path
+        required: true
+        schema:
+          type: string
+        description: 'Path parameter: connector_id'
+  /v1alpha/connectors:
+    get:
+      responses:
+        '200':
+          description: A ListConnectorsResponse.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListConnectorsResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest400'
+          description: Bad Request
+        '429':
+          $ref: '#/components/responses/TooManyRequests429'
+          description: Too Many Requests
+        '500':
+          $ref: '#/components/responses/InternalServerError500'
+          description: Internal Server Error
+        default:
+          $ref: '#/components/responses/DefaultError'
+          description: Default Response
+      tags:
+      - Connectors
+      summary: List Connectors
+      description: List all configured connectors.
+      operationId: list_connectors_v1alpha_connectors_get
+      parameters:
+      - name: include_tools
+        in: query
+        required: false
+        schema:
+          type: boolean
+          default: false
+          title: Include Tools
+      - name: registry_id
+        in: query
+        required: false
+        schema:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Registry Id
 components:
   schemas:
     Error:
@@ -11618,6 +11772,90 @@ components:
       - chunk_id
       title: Chunk
       description: A chunk of content that can be inserted into a vector database.
+    Connector:
+      properties:
+        identifier:
+          type: string
+          title: Identifier
+          description: Unique identifier for this resource in llama stack
+        provider_resource_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Unique identifier for this resource in the provider
+        provider_id:
+          type: string
+          title: Provider Id
+          description: ID of the provider that owns this resource
+        type:
+          type: string
+          const: connector
+          title: Type
+          default: connector
+        connector_type:
+          $ref: '#/components/schemas/ConnectorType'
+          default: mcp
+        connector_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: User-specified identifier for the connector
+        url:
+          type: string
+          title: Url
+          description: URL of the connector
+        created_at:
+          type: string
+          format: date-time
+          title: Created At
+          description: Timestamp of creation
+        updated_at:
+          type: string
+          format: date-time
+          title: Updated At
+          description: Timestamp of last update
+        server_name:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Name of the server
+        server_label:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Label of the server
+        server_description:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Description of the server
+        tools:
+          anyOf:
+          - items:
+              $ref: '#/components/schemas/ToolDef'
+            type: array
+          - type: 'null'
+          description: List of tools available from the connector
+        registry_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: ID of the registry this connector belongs to
+      type: object
+      required:
+      - identifier
+      - provider_id
+      - url
+      - created_at
+      - updated_at
+      title: Connector
+      description: A connector resource representing a connector registered in Llama Stack.
+    ConnectorType:
+      type: string
+      enum:
+      - mcp
+      title: ConnectorType
+      description: Type of connector.
     ConversationItemInclude:
       type: string
       enum:
@@ -11708,6 +11946,30 @@ components:
       - cancelled
       title: JobStatus
       description: Status of a job execution.
+    ListConnectorsResponse:
+      properties:
+        data:
+          items:
+            $ref: '#/components/schemas/Connector'
+          type: array
+          title: Data
+      type: object
+      required:
+      - data
+      title: ListConnectorsResponse
+      description: Response containing a list of connectors.
+    ListToolsResponse:
+      properties:
+        data:
+          items:
+            $ref: '#/components/schemas/ToolDef'
+          type: array
+          title: Data
+      type: object
+      required:
+      - data
+      title: ListToolsResponse
+      description: Response containing a list of tools.
     MCPListToolsTool:
       properties:
         input_schema:
@@ -12573,6 +12835,66 @@ components:
           type: string
       title: DialogType
       type: object
+    ToolGroupInput:
+      description: Input data for registering a tool group.
+      properties:
+        toolgroup_id:
+          title: Toolgroup Id
+          type: string
+        provider_id:
+          title: Provider Id
+          type: string
+        args:
+          anyOf:
+          - additionalProperties: true
+            type: object
+          - type: 'null'
+          nullable: true
+        mcp_endpoint:
+          anyOf:
+          - $ref: '#/components/schemas/URL'
+            title: URL
+          - type: 'null'
+          nullable: true
+          title: URL
+      required:
+      - toolgroup_id
+      - provider_id
+      title: ToolGroupInput
+      type: object
+    ConnectorInput:
+      description: Input for creating a connector.
+      properties:
+        connector_type:
+          $ref: '#/components/schemas/ConnectorType'
+          default: mcp
+        connector_id:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Unique identifier for the connector
+          nullable: true
+        url:
+          description: URL of the connector
+          title: Url
+          type: string
+        headers:
+          anyOf:
+          - additionalProperties: true
+            type: object
+          - type: 'null'
+          description: HTTP headers to include when connecting
+          nullable: true
+        authorization:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: OAuth access token for authentication
+          nullable: true
+      required:
+      - url
+      title: ConnectorInput
+      type: object
     ConversationMessage:
       description: OpenAI-compatible message item for conversations.
       properties:
@@ -12657,33 +12979,6 @@ components:
       - items
       title: ConversationItemCreateRequest
       type: object
-    ToolGroupInput:
-      description: Input data for registering a tool group.
-      properties:
-        toolgroup_id:
-          title: Toolgroup Id
-          type: string
-        provider_id:
-          title: Provider Id
-          type: string
-        args:
-          anyOf:
-          - additionalProperties: true
-            type: object
-          - type: 'null'
-          nullable: true
-        mcp_endpoint:
-          anyOf:
-          - $ref: '#/components/schemas/URL'
-            title: URL
-          - type: 'null'
-          nullable: true
-          title: URL
-      required:
-      - toolgroup_id
-      - provider_id
-      title: ToolGroupInput
-      type: object
     Api:
       description: Enumeration of all available APIs in the Llama Stack system.
       enum:
@@ -12708,6 +13003,7 @@ components:
       - files
       - prompts
       - conversations
+      - connectors
       - inspect
       title: Api
       type: string

src/llama_stack/core/resolver.py

@@ -28,6 +28,7 @@ from llama_stack_api import (
     Batches,
     Benchmarks,
     BenchmarksProtocolPrivate,
+    Connectors,
     Conversations,
     DatasetIO,
     Datasets,
@@ -100,6 +101,7 @@ def api_protocol_map(external_apis: dict[Api, ExternalApiSpec] | None = None) ->
         Api.files: Files,
         Api.prompts: Prompts,
         Api.conversations: Conversations,
+        Api.connectors: Connectors,
     }
 
     if external_apis:

src/llama_stack_api/__init__.py

@@ -66,6 +66,14 @@ from .common.type_system import (
     ParamType,
     StringType,
 )
+from .connectors import (
+    Connector,
+    ConnectorInput,
+    Connectors,
+    ConnectorType,
+    ListConnectorsResponse,
+    ListToolsResponse,
+)
 from .conversations import (
     Conversation,
     ConversationDeletedResource,
@@ -482,6 +490,10 @@ __all__ = [
     "CommonShieldFields",
     "CompletionInputType",
     "CompletionRequest",
+    "Connector",
+    "ConnectorInput",
+    "Connectors",
+    "ConnectorType",
     "Conversation",
     "ConversationDeletedResource",
     "ConversationItem",
@@ -556,6 +568,7 @@ __all__ = [
     "LLMRAGQueryGeneratorConfig",
     "ListBatchesResponse",
     "ListBenchmarksResponse",
+    "ListConnectorsResponse",
     "ListDatasetsResponse",
     "ListModelsResponse",
     "ListOpenAIChatCompletionResponse",
@@ -570,6 +583,7 @@ __all__ = [
     "ListShieldsResponse",
     "ListToolDefsResponse",
     "ListToolGroupsResponse",
+    "ListToolsResponse",
     "LogProbConfig",
     "LoraFinetuningConfig",
     "MCPListToolsTool",

src/llama_stack_api/connectors.py

@@ -0,0 +1,171 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any, Literal, Protocol
+
+from pydantic import BaseModel, Field
+from typing_extensions import runtime_checkable
+
+from llama_stack_api.resource import Resource, ResourceType
+from llama_stack_api.schema_utils import json_schema_type, webmethod
+from llama_stack_api.tools import ToolDef
+from llama_stack_api.version import LLAMA_STACK_API_V1ALPHA
+
+
+@json_schema_type
+class ConnectorType(StrEnum):
+    """Type of connector."""
+
+    MCP = "mcp"
+
+
+@json_schema_type
+class Connector(Resource):
+    """A connector resource representing a connector registered in Llama Stack.
+
+    :param type: Type of resource, always 'connector' for connectors
+    :param connector_type: Type of connector (e.g., MCP)
+    :param connector_id: User-specified identifier for the connector
+    :param url: URL of the connector
+    :param created_at: Timestamp of creation
+    :param updated_at: Timestamp of last update
+    :param server_label: (Optional) Label of the server
+    :param server_description: (Optional) Description of the server
+    :param tools: (Optional) List of tools available from the connector
+    :param registry_id: (Optional) ID of the registry this connector belongs to
+    """
+
+    model_config = {"populate_by_name": True}
+
+    type: Literal[ResourceType.connector] = ResourceType.connector
+    connector_type: ConnectorType = Field(default=ConnectorType.MCP)
+    user_connector_id: str | None = Field(
+        default=None, alias="connector_id", description="User-specified identifier for the connector"
+    )
+    url: str = Field(..., description="URL of the connector")
+    created_at: datetime = Field(..., description="Timestamp of creation")
+    updated_at: datetime = Field(..., description="Timestamp of last update")
+    server_name: str | None = Field(default=None, description="Name of the server")
+    server_label: str | None = Field(default=None, description="Label of the server")
+    server_description: str | None = Field(default=None, description="Description of the server")
+    # TODO: using ToolDef for now, but MCPListToolsTool should probably be updated and used instead
+    # once toolgroups are removed completely
+    tools: list[ToolDef] | None = Field(default=None, description="List of tools available from the connector")
+    registry_id: str | None = Field(default=None, description="ID of the registry this connector belongs to")
+
+    def _generate_connector_id(self) -> str:
+        name = self.server_name if self.server_name is not None else self.identifier
+        if self.registry_id is not None:
+            return f"{self.connector_type.value}::{self.registry_id}::{name}"
+        return f"{self.connector_type.value}::{name}"
+
+    @property
+    def connector_id(self) -> str:
+        return self.user_connector_id if self.user_connector_id is not None else self._generate_connector_id()
+
+    @property
+    def without_tools(self) -> "Connector":
+        """Return a copy of this connector with tools removed."""
+        return self.model_copy(update={"tools": None})
+
+
+@json_schema_type
+class ConnectorInput(BaseModel):
+    """Input for creating a connector.
+
+    :param connector_type: Type of connector
+    :param connector_id: Unique identifier for the connector
+    :param url: URL of the connector
+    :param headers: (Optional) HTTP headers to include when connecting to the server
+    :param authorization: (Optional) OAuth access token for authenticating with the MCP server
+    """
+
+    connector_type: ConnectorType = Field(default=ConnectorType.MCP)
+    connector_id: str | None = Field(default=None, description="Unique identifier for the connector")
+    url: str = Field(..., description="URL of the connector")
+    headers: dict[str, Any] | None = Field(default=None, description="HTTP headers to include when connecting")
+    authorization: str | None = Field(default=None, description="OAuth access token for authentication")
+
+
+@json_schema_type
+class ListConnectorsResponse(BaseModel):
+    """Response containing a list of connectors.
+
+    :param data: List of connectors
+    """
+
+    data: list[Connector]
+
+
+@json_schema_type
+class ListToolsResponse(BaseModel):
+    """Response containing a list of tools.
+
+    :param data: List of tools
+    """
+
+    data: list[ToolDef]
+
+
+@runtime_checkable
+class Connectors(Protocol):
+    # NOTE: Route order matters! More specific routes must come before less specific ones.
+    # Routes with {param:path} are greedy and will match everything including slashes.
+
+    @webmethod(route="/connectors", method="GET", level=LLAMA_STACK_API_V1ALPHA)
+    async def list_connectors(
+        self,
+        registry_id: str | None = None,
+        include_tools: bool = False,
+    ) -> ListConnectorsResponse:
+        """List all configured connectors.
+
+        :param registry_id: (Optional) The ID of a registry to filter connectors for.
+        :param include_tools: (Optional) Whether to include tools in the response.
+        :returns: A ListConnectorsResponse.
+        """
+        ...
+
+    @webmethod(route="/connectors/{connector_id}/tools/{tool_name}", method="GET", level=LLAMA_STACK_API_V1ALPHA)
+    async def get_connector_tool(
+        self,
+        connector_id: str,
+        tool_name: str,
+    ) -> ToolDef:
+        """Get a tool definition by its name from a connector.
+
+        :param connector_id: The ID of the connector to get the tool from.
+        :param tool_name: The name of the tool to get.
+        :returns: A ToolDef.
+        """
+        ...
+
+    @webmethod(route="/connectors/{connector_id}/tools", method="GET", level=LLAMA_STACK_API_V1ALPHA)
+    async def list_connector_tools(
+        self,
+        connector_id: str,
+    ) -> ListToolsResponse:
+        """List tools available from a connector.
+
+        :param connector_id: The ID of the connector to list tools for.
+        :returns: A ListToolsResponse.
+        """
+        ...
+
+    @webmethod(route="/connectors/{connector_id}", method="GET", level=LLAMA_STACK_API_V1ALPHA)
+    async def get_connector(
+        self,
+        connector_id: str,
+        include_tools: bool = False,
+    ) -> Connector:
+        """Get a connector by its ID.
+
+        :param connector_id: The ID of the connector to get.
+        :returns: A Connector.
+        """
+        ...

src/llama_stack_api/datatypes.py

@@ -111,6 +111,7 @@ class Api(Enum, metaclass=DynamicApiMeta):
     :cvar tool_groups: Tool group organization
     :cvar files: File storage and management
     :cvar prompts: Prompt versions and management
+    :cvar connectors: External connector management (e.g., MCP servers)
     :cvar inspect: Built-in system inspection and introspection
     """
 
@@ -136,6 +137,7 @@ class Api(Enum, metaclass=DynamicApiMeta):
     files = "files"
     prompts = "prompts"
     conversations = "conversations"
+    connectors = "connectors"
 
     # built-in API
     inspect = "inspect"

src/llama_stack_api/resource.py

@@ -20,6 +20,7 @@ class ResourceType(StrEnum):
     tool = "tool"
     tool_group = "tool_group"
     prompt = "prompt"
+    connector = "connector"
 
 
 class Resource(BaseModel):