Red Hat Developer Hub 2.1

Discover AI assets in the AI Catalog

Red Hat Customer Content Services

Abstract

Use the AI Catalog to browse, search, and discover AI agents, skills, MCP servers, AI models, and model servers registered in the Software Catalog.

Preface
1. AI Catalog overview
2. Enable and configure the AI Catalog plugin
- 2.1. Enable the AI Catalog plugin
- 2.2. Configure AI Catalog filters
3. Browse AI assets in the catalog
4. View AI asset details
5. Review AI Catalog architecture and dependencies
- 5.1. AI Catalog architecture and dependencies
- 5.2. AI Asset entity model

Preface

Use the AI Catalog to browse, search, and discover AI agents, skills, MCP servers, AI models, and model servers registered in the Software Catalog.

Chapter 1. AI Catalog overview

The AI Catalog provides a marketplace-style interface to browse, search, filter, and discover AI assets registered in the Software Catalog, helping you find agents, skills, MCP servers, AI models, and model servers for your organization.

The AI Catalog is a dynamic front-end plugin that integrates with Developer Hub to give developers a dedicated discovery interface for AI capabilities. Instead of searching across multiple registries, repositories, and documentation sources, developers use a single catalog with category grouping, contextual filtering, and download actions.

The AI Catalog provides the following capabilities:

Browse AI assets — View all available AI agents, skills, MCP servers, AI models, and model servers in a card-based grid layout
Search and filter — Find assets by name, description, or tag, and narrow results by category, source connector, or lifecycle
View asset details — Access complete information about each asset including name, description, versions, source registry, and usage documentation
Copy deployment commands — For OCI-based assets, copy docker or podman pull commands directly from the detail page
Identify recommended versions — View version lists and identify the recommended version for each asset

The AI Catalog is a discovery and metadata browsing interface in this release. It excludes the following capabilities:

Install, deploy, or run actions for AI assets
Ratings, reviews, or usage analytics
Notifications or alerts for new assets
In-UI editing or curation of asset metadata

After you find an asset in the AI Catalog, follow the usage documentation or external links to install, configure, and use the asset in your environment.

The AI Catalog integrates with the following Developer Hub components:

Software Catalog API — Retrieves AI Asset entities registered in the Software Catalog
Search infrastructure — Enables federated search across AI assets and other catalog entities
TechDocs — Renders usage documentation when TechDocs references are present on entities
Permission Framework (optional) — Enforces RBAC visibility policies when configured

The AI Catalog supports the following asset categories:

Category	Description
AI Agents	Autonomous AI systems that perform tasks by using tools and skills
AI Skills	Reusable capabilities that agents call to accomplish specific tasks
MCP Servers	Model Context Protocol servers that expose tools and resources to AI clients
AI Models	Machine learning models for inference and prediction
Model Servers	Deployment platforms that serve AI models at runtime

Chapter 2. Enable and configure the AI Catalog plugin

To allow developers to browse and discover AI assets, enable the AI Catalog dynamic plugin and optionally configure filter visibility.

2.1. Enable the AI Catalog plugin

To allow developers to discover AI assets, enable the AI Catalog dynamic plugin in your Developer Hub instance.

Prerequisites

You have administrator access to your Developer Hub instance.
AI Asset entities are ingested into the Software Catalog.

Procedure

Edit your dynamic-plugins-rhdh ConfigMap to include the AI Catalog plugin:

kind: ConfigMap
apiVersion: v1
metadata:
  name: dynamic-plugins-rhdh
data:
  dynamic-plugins.yaml: |
    includes:
      - dynamic-plugins.default.yaml
    plugins:
      - package: '@redhat/backstage-plugin-ai-catalog'
        disabled: false

Optional: Configure filter visibility in your app-config.yaml or app-config-rhdh ConfigMap:

app:
  extensions:
    - entity-ref: 'plugin:ai-catalog'
      config:
        filters:
          owner:
            disabled: true  # Hide the owner filter

Apply the updated ConfigMap:
```
$ oc apply -f <configmap-file>
```
where <configmap-file> is the path to your updated ConfigMap YAML file.
Restart the Developer Hub pods to load the plugin:
```
$ oc rollout restart deployment/backstage
```

Verification

Navigate to your Developer Hub instance in a web browser.
Confirm that an AI Catalog menu item is displayed in the navigation sidebar.
Click AI Catalog and verify that AI assets are displayed in the card grid.

Additional resources

Installing dynamic plugins in Installing and viewing plugins in Red Hat Developer Hub

2.2. Configure AI Catalog filters

To control which filters appear in the AI Catalog sidebar, configure filter visibility in your application configuration.

Prerequisites

You have administrator access to your Developer Hub instance.
The AI Catalog plugin is enabled.

Procedure

Edit your app-config-rhdh ConfigMap to configure filter visibility:
```
app:
  extensions:
    - entity-ref: 'plugin:ai-catalog'
      config:
        filters:
          owner:
            disabled: true
          lifecycle:
            disabled: false
```
where:
owner
Disables the owner filter, hiding it from the filter sidebar.
lifecycle
Enables the lifecycle filter, showing it in the filter sidebar.
Apply the updated ConfigMap:
```
$ oc apply -f <configmap-file>
```

Restart the Developer Hub pods:

$ oc rollout restart deployment/backstage

Verification

Navigate to the AI Catalog in your browser.
Confirm that the configured filters appear or do not appear in the sidebar based on your settings.

The following table lists the available filters:

Filter	Description
`category`	Filters by AI asset category (AI Agents, AI Skills, MCP Servers, AI Models, Model Servers)
`source`	Filters by source connector (MCP Registry, RHOAI)
`tags`	Filters by tags and labels applied to assets
`owner`	Filters by asset owner (optional, can be disabled)
`lifecycle`	Filters by asset lifecycle status (optional, can be disabled)

Chapter 3. Browse AI assets in the catalog

To find AI capabilities for your application, browse the AI Catalog by using search, filters, and category grouping.

Prerequisites

The AI Catalog plugin is enabled in your Developer Hub instance.
AI assets are registered in the Software Catalog.

Procedure

Navigate to your Developer Hub instance and click AI Catalog in the sidebar.
The AI Catalog landing page displays all AI assets you are authorized to view, grouped by category.
Optional: Search for assets by name, description, or tag:
1. Type keywords into the search box at the top of the page.
2. Results update as you type, showing only assets matching your search terms.
Optional: Filter assets by category, source, or tags:
1. Open the filter sidebar on the left side of the page.
2. Select one or more categories: AI Agents, AI Skills, MCP Servers, AI Models, or Model Servers.
3. Select one or more source connectors to filter by origin: MCP Registry or RHOAI.
4. Select tags or labels to narrow results further.
5. Click Clear filters to reset all filter selections.
Optional: Combine search and filters to narrow large result sets:
1. Type keywords in the search box.
2. Apply filters in the sidebar.
3. The catalog displays only assets matching both your search terms and selected filters.
Review asset cards in the grid:
Each card displays the following information:
- Asset name
- Short description
- Category icon or label
- Source connector
- Current or recommended version
- Owner (if visible)
Click an asset card to view its detail page.

Verification

Assets matching your search terms and filter selections appear in the catalog grid.
The catalog shows a "no results" message if no assets match your current filters.

Additional resources

Chapter 4, View AI asset details

Chapter 4. View AI asset details

To understand what an AI asset does and how to use it, view its detail page showing complete metadata, versions, and usage documentation.

Prerequisites

The AI Catalog plugin is enabled in your Developer Hub instance.
You have browsed the AI Catalog and located an asset.

Procedure

In the AI Catalog, click an asset card.
The asset detail page opens, displaying complete information about the asset.
Review the AI Asset Summary card:
- Asset name
- Full description
- Category and type
- Source registry and ingestion connector
- Owner
- Lifecycle status
Review the Version List card:
- List of all available versions
- Current or recommended version (highlighted)
- Version history
Review the How to use this panel or Usage tab:
- If the asset has TechDocs documentation, the panel renders setup instructions, configuration snippets, and usage examples inline.
- If the asset does not have TechDocs, the panel displays links to:
  - Source registry entry
  - Source repository
  - Download or distribution location
Optional: For OCI-based assets (skills published as container images), copy deployment commands:
1. Locate the Download or Adopt card on the detail page.
2. Click Copy next to the docker pull or podman pull command.
3. Paste the command into your terminal to pull the asset image.

Verification

The detail page displays the asset name, description, category, versions, and usage documentation or external links.
For OCI-based assets, the Download or Adopt card shows a complete pull command with registry URL, namespace, image name, and digest.

Additional resources

Chapter 3, Browse AI assets in the catalog

Chapter 5. Review AI Catalog architecture and dependencies

The AI Catalog integrates with existing Developer Hub infrastructure and requires specific entity metadata to function, making it compatible with air-gapped deployments.

5.1. AI Catalog architecture and dependencies

The AI Catalog integrates with existing Developer Hub components to provide AI asset discovery without introducing new backend services or network requirements.

The AI Catalog is a front-end dynamic plugin that reuses existing Developer Hub infrastructure:

Software Catalog API — Retrieves AI Asset entities from the catalog backend
Search infrastructure — Enables federated search, returning AI assets alongside other catalog entities in global search results
TechDocs rendering — Displays usage documentation when entities include TechDocs references
Permission Framework (optional) — Enforces RBAC visibility policies defined for AI assets

The plugin does not introduce a new backend service. All data flows through the existing Developer Hub backend API.

The AI Catalog requires the following components to function:

Component	Purpose	Status
AI Asset entities	Entities registered in the Software Catalog by using the appropriate entity kind for each asset category (`AiResource`, `API`, or `AiModelServerAPI`)	Required
Ingestion connectors	Populate the Software Catalog with AI assets from external registries (MCP Registry, RHOAI)	Required
RBAC policies	Define visibility and access control for AI assets (`ai-catalog.asset.read`, `ai-catalog.asset.read.usage-docs`)	Optional (available in RHDH 2.2+)
TechDocs content	Provides rich inline usage documentation for assets	Optional

The AI Catalog is fully compatible with disconnected and air-gapped OpenShift Container Platform environments:

All assets, icons, and TechDocs content are served from in-cluster sources
No required runtime calls to external or internet-hosted endpoints
External links (to source registries, repositories, or download locations) open in new tabs and degrade gracefully if unreachable
Custom CA bundles can be configured for internal registries if needed

The AI Catalog does not require additional network egress beyond the existing Developer Hub backend.

The AI Catalog is designed to handle large catalogs with responsive performance:

Initial page load completes in under 2 seconds for catalogs with 500 assets
Filter application completes in under 2 seconds
Pagination or virtualization prevents UI lag with large result sets
Catalog API performance impact is less than 10% compared to baseline (non-AI-Catalog entity queries)

5.2. AI Asset entity model

AI assets are represented as Software Catalog entities. The entity kind and spec.type determine how the AI Catalog classifies and displays each asset.

AI Agent and AI Skill assets use the AiResource entity kind with spec.type values corresponding to their category:

Category	`spec.type`	Description
AI Agent	`ai-agent`	Autonomous systems that perform tasks by using tools and skills
AI Skill	`ai-skill`	Reusable capabilities invoked by agents to accomplish tasks

The following example shows an AI skill entity:

apiVersion: backstage.io/v1alpha1
kind: AiResource
metadata:
  name: python-testing-skill
  namespace: default
spec:
  type: ai-skill
  owner: team-ai
  lifecycle: production

MCP Server assets use the API entity kind with spec.type: mcp-server:

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: github-mcp-server
  title: GitHub MCP Server
  description: Model Context Protocol server providing GitHub repository context, pull request data, and issue tracking integration.
  tags:
    - github
    - mcp
    - context
spec:
  type: mcp-server
  lifecycle: experimental
  owner: team-integrations
  definition: |
    openapi: 3.0.0
    info:
      title: GitHub MCP Server
      version: 0.9.0
  remotes:
    - url: https://mcp.example.com/github
      type: streamable-http

Model Server assets use the AiModelServerAPI entity kind. AI Model assets do not have their own entity kind. Instead, each model is listed under the model server’s spec.models.available field:

apiVersion: backstage.io/v1alpha1
kind: AiModelServerAPI
metadata:
  name: granite-model-server
  title: Granite Model Server
  description: IBM Granite model server hosting code generation and instruction-following models.
  tags:
    - model-server
    - code-generation
    - ibm
  links:
    - title: API
      url: https://granite.example.com/v1
spec:
  type: ai-model-server
  lifecycle: production
  owner: team-ml-ops
  serverType: openai-v1
  serverUrl: https://granite.example.com/v1
  requiresApiKey: true
  models:
    discoverable: true
    available:
      - granite-3-code
      - granite-3-instruct
    default: granite-3-instruct

To display rich usage documentation in the AI Catalog detail page, add a TechDocs reference to the entity:

metadata:
  annotations:
    backstage.io/techdocs-ref: dir:.

When a TechDocs reference is present, the AI Catalog renders the documentation inline in the "How to use this" panel. Without a TechDocs reference, the catalog displays links to the source registry, repository, or download location.

Legal Notice

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

Java® is a registered trademark of Oracle and/or its affiliates.

XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.

MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.

Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.

The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.

All other trademarks are the property of their respective owners.