Skip to content
Latest (currently 2026.8.0) has the newest features, bug fixes, and CVE patches of Solo Enterprise for agentregistry.

For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Build a catalog for AI artifacts

Page as Markdown
Learn what the catalog is and how to publish an MCP server and agent to it so that they are discoverable and reusable across your organization.
Without a central registry, AI artifacts, such as agents, MCP servers, skills, and prompts, are scattered across GitHub repositories, container registries, and individual workstations. Artifacts are duplicated across teams, deployed versions diverge from source control, and there is no authoritative record of what is running in production or who built it. Solo Enterprise for agentregistry solves this with the AI artifact catalog — a centralized, versioned store where every AI artifact has a single authoritative home, with the discovery, governance, and lifecycle controls that production AI systems require.
Think of the catalog as a package registry for AI: the same way a software engineer publishes a library once and lets others import it, your AI teams publish agents and MCP servers once and let others deploy them to any runtime. Every artifact gets a canonical home with:
  • Discoverability: Browse all available agents and MCP servers from the UI, the arctl CLI, or REST API.
  • Versioning: Every artifact is published with a tag, such as latest or v1.0.0. Deploy any version independently and roll back if something breaks.
  • Reuse: An MCP server, skill, or plugin published once can be wired into any number of agents.
  • Governance: Before an artifact can be deployed to a runtime, it must be in the catalog, creating a natural gate for review, policy enforcement, and auditability.
Tip
New to Solo Enterprise for agentregistry? Learn about core concepts and the architecture before getting started.
About this guide

In this guide, you build an AI artifact catalog by scaffolding, testing, and publishing an MCP server and an agent, so that both are discoverable, versioned, and ready to deploy to any runtime.
Solo Enterprise for agentregistry supports different types of agents and MCP servers. Agents can be self-contained containers that you build end-to-end (BYO agents), or compositions of skills and plugins that run inside an agent harness (harness agents). MCP servers can be packaged servers that you build and deploy, or remote servers that are already running at an external URL. For a full overview, see the Core concepts.
This guide covers the most common development path: a BYO agent and a packaged MCP server, plus adding a skill and a prompt to the catalog. By the end, you have an AI catalog that you can share with your teams. The catalog contains the following artifacts:
  • A versioned Python MCP server with echo, sum, and greet tools.
  • A versioned Python agent that can roll a dice and check prime numbers.
  • A skill with an optional source repository reference.
  • A prompt with inline content for use as a system prompt.
This guide does not cover deploying artifacts to a runtime. To deploy your catalog artifacts to a runtime after completing this guide, see one of the runtime-specific guides in the Next steps section.
Before you begin

To complete this guide, you need a running installation of Solo Enterprise for agentregistry that is configured with your OIDC provider, and the arctl CLI so that you can start building your AI artifact catalog. If you have not set up Solo Enterprise for agentregistry yet, complete the following steps first.
  1. Set up an OIDC provider so that users can authenticate with the registry.
  2. Install Solo Enterprise for agentregistry and the arctl CLI so that you can start building your catalog.
  3. Verify that you are logged in by running the following command.
    arctl user whoami
  4. Port-forward the Solo Enterprise for agentregistry server on port 12121 if you have not done so already. The registry is not exposed externally by default, so you need port-forwarding to reach it from your local machine.
    kubectl -n agentregistry-system port-forward svc/agentregistry-enterprise-server 12121:12121
Step 1: Register an MCP server

Registering an MCP server adds the server to the registry catalog so that it can be discovered by catalog users and referenced in agent definitions.
This step walks you through how to register different types of MCP servers depending on whether you want to add existing MCP servers or create your own. Select the tab that matches your situation.
A remote MCP server runs outside of Solo Enterprise for agentregistry at an external URL. You do not deploy or manage the MCP server and you cannot use Solo Enterprise for agentregistry to re-deploy it. After you register the server in the catalog, you can reference the server in the agent definition so that the agent can access the server’s tools during runtime.
  1. Create a registry catalog entry for your remote MCP server. The following example uses the Solo.io documentation MCP server.
    arctl apply -f - <<EOF
apiVersion: ar.dev/v1alpha1
kind: MCPServer
metadata:
  name: remotemcp
spec:
  description: Remote MCP test server
  remote:
    type: streamable-http
    url: https://search.solo.io/mcp
EOF
    FieldDescription
    metadata.nameThe catalog name for the server.
    spec.remote.typeThe transport type. Use streamable-http for HTTP-based MCP servers.
    spec.remote.urlThe full URL of the remote MCP server, including the path, such as /mcp.
    Example output:
    ✓ MCPServer/remotemcp (latest) created

  2. Verify that the remote MCP server is registered in the catalog.
    arctl get mcp
    Example output:
    NAME        TAG      DESCRIPTION
remotemcp   latest   Remote MCP test server

  3. Open the catalog in the registry UI to see the MCP server listed under MCP servers.
Use this path if your team already built an MCP server outside of Solo Enterprise for agentregistry and you want to bring it into the catalog so that it is discoverable and deployable through the registry.
Unlike a remote server registration, which only stores the server’s URL for discoverability, registering an existing server with its container image or source repository URL lets Solo Enterprise for agentregistry deploy and manage the server’s lifecycle across any connected deployment runtime in addition to providing discoverability for catalog users.
  1. Create an MCP server definition file for your packaged MCP server. The definition describes the catalog entry that you want to create in the registry. To enable Solo Enterprise for agentregistry to deploy the server to a runtime at a later time, provide either a container image or a source repository, depending on your target runtime:
    • Container image (spec.source.package.origin): Required to deploy to Solo Enterprise for kagent. The registry pulls the image and runs it as a pod in your cluster when you deploy the MCP server.
    • Source repository URL (spec.source.repository): Required to deploy to cloud-managed agentic platforms, such as AWS Bedrock AgentCore. The repository must include the MCP source code and Dockerfile. During a deployment, Solo Enterprise for agentregistry uses these files to build an image that is compatible to run in the runtime that you selected.
      Tip
      If your source repository is private, you must configure registry credentials before the registry can access it. For more information, see Private repository access.
    Example MCP server definition with an image:
    arctl apply -f - <<EOF
apiVersion: ar.dev/v1alpha1
kind: MCPServer
metadata:
  name: mymcp
spec:
  description: My existing MCP server
  source:
    package:
      origin:
        type: oci
        identifier: localhost:5001/mymcp  
        oci:
          serverName: mymcp
      transport:
        path: /mcp
        port: 3000
        type: http
      launch:
        command: python3
        args:
          - type: positional
            value: src/main.py
          - type: positional
            value: --transport
          - type: positional
            value: http
          - type: positional
            value: --host
          - type: positional
            value: 0.0.0.0
          - type: positional
            value: --port
          - type: positional
            value: "3000"
EOF
    FieldDescription
    metadata.nameThe catalog name for the server. This name is displayed in the registry catalog.
    spec.source.package.origin.typeThe origin type. Use oci for container images.
    spec.source.package.origin.identifierThe container image reference, including the registry, image name, and tag.
    spec.source.package.origin.oci.serverNameThe name of the server as defined in the OCI image.
    spec.source.package.transportHow the server exposes its MCP endpoint.
    spec.source.package.launchThe command and arguments that are used to start the server.
    Example MCP server definition with a source repository:
    arctl apply -f - <<EOF
apiVersion: ar.dev/v1alpha1
kind: MCPServer
metadata:
  name: mymcp
spec:
  description: mymcp MCP server
  source:
    repository:
      url: https://github.com/solo-io/doc-examples
      subfolder: agentregistry/mymcp
EOF
    FieldDescription
    metadata.nameThe catalog name for the server. This name is displayed in the registry catalog.
    spec.source.repository.urlThe URL of the GitHub repository that stores the MCP source code and Dockerfile.
    spec.source.repository.subfolderOptional. The path within the repository to the MCP server source code, if it is not at the repository root.
  2. Verify that the server is in the catalog.
    arctl get mcp
    Example output:
    NAME    TAG      DESCRIPTION
mymcp   latest   My existing MCP server

  3. Open the catalog in the registry UI to see the MCP server listed under MCP servers.
Use the arctl CLI to quickly scaffold a sample MCP server with tools. The scaffold creates a ready-to-run project with an entry point, a Dockerfile, a tool directory, and an mcp.yaml definition file, which is everything you need to later publish the server to the registry catalog.
  1. Create an MCP server scaffold. The following command creates a FastMCP Python server named mymcp that comes pre-built with two example tools: an echo tool that returns a message back to the caller, and a sum tool that adds two numbers together.
    arctl init mcp mymcp --framework fastmcp --language python \
  --description "Sample MCP server" \
  --image localhost:5001/mymcp:latest
    Example output:
    ✓ Created MCP server: mymcp (framework: fastmcp, language: python)

    Review the files that are created as part of the scaffold:
    FileDescription
    mcp.yamlThe MCP server definition that you publish to the catalog. It describes the server metadata, transport settings, and image location.
    arctl.yamlA summary of the flags that you used to configure MCP server settings during scaffolding.
    DockerfileThe Dockerfile to build and run the MCP server in a container.
    pyproject.tomlThe Python project configuration file with dependencies and build settings.
    src/main.pyThe entry point that bootstraps and starts the MCP server.
    src/core/The core server source code, including the FastMCP instance and shared utilities.
    src/tools/The directory where each tool is defined as its own Python file. The scaffold includes two ready-to-use example tools in the src/tools/ directory. Each tool is an @mcp.tool() Python function that an agent can call during a conversation.
    tests/Auto-generated tests for the server and tools.
  2. Review the tools that were created by the scaffold.
    • echo.py: The example_echo function accepts a message string and returns it unchanged, or prepends an optional prefix if one is set in the tool’s configuration. The prefix is read at runtime from get_tool_config, so you can customize the behavior without editing the code.
    • sum.py: The example_sum function accepts two numbers, a and b, as either integers or floats, and returns their sum.
    cat mymcp/src/tools/echo.py
cat mymcp/src/tools/sum.py
    Example output for the echo.py tool:
    from core.server import mcp
from core.utils import get_tool_config

@mcp.tool(description="Echo a message back to the client.")
def example_echo(message: str) -> str:
    config = get_tool_config("example_echo")
    prefix = config.get("prefix", "")
    return f"{prefix}{message}" if prefix else message

  3. You can optionally add your own tools by creating a new .py file in the src/tools/ directory. Each file must import the shared mcp instance from core.server and define at least one function that is decorated with @mcp.tool(). The file is picked up automatically at server startup, no registration step is needed.
    The following command creates a greeting tool that takes a name as an input and returns Hello, {name}!.
    cat > mymcp/src/tools/greet.py << 'EOF'
from core.server import mcp

@mcp.tool(description="Return a greeting for the given name.")
def example_greet(name: str) -> str:
    return f"Hello, {name}!"
EOF
  4. Review the MCP server definition (mcp.yaml) file that the scaffold generated.
    When you scaffold an MCP server, the default container image location and tag localhost:5001/mymcp:latest are added to the MCP server definition. Before you can add an MCP server to the registry catalog, the MCP server definition must either have an image location or a source repository URL that points to the Dockerfile and MCP source files. Solo Enterprise for agentregistry uses the files in the repo to build runtime-specific images when you deploy AI artifacts to agentic platforms, such as AWS Bedrock AgentCore. If you plan to deploy MCP servers to Solo Enterprise for kagent, you must provide a container image. For more information, see Build image or store source code.
    cat mymcp/mcp.yaml
    Example output:
    apiVersion: ar.dev/v1alpha1
kind: MCPServer
metadata:
  name: mymcp
spec:
  description: mymcp MCP server
  source:
    package:
      launch:
        args:
        - type: positional
          value: src/main.py
        - type: positional
          value: --transport
        - type: positional
          value: http
        - type: positional
          value: --host
        - type: positional
          value: 0.0.0.0
        - type: positional
          value: --port
        - type: positional
          value: "3000"
        command: python3
      origin:
        identifier: localhost:5001/mymcp:latest
        oci:
          serverName: mymcp
        type: oci
      transport:
        path: /mcp
        port: 3000
        type: http
  title: mymcp

  5. Build the MCP server container image so that it can be run locally.
    arctl build mymcp
    Example output:
    Building MCP server image: localhost:5001/mymcp:latest
Building Docker image for python project...
...
✓ Successfully built Docker image: localhost:5001/mymcp:latest

    Tip
    You can use the --push flag to optionally push the container image to your registry.
  6. Run the MCP server on your local machine with the MCP Inspector. The --inspector flag starts the server and automatically opens the MCP Inspector so you can test your tools without any additional setup.
    arctl run mymcp --inspector
    Example output:
    → fastmcp-python: docker run --rm -p 3000:3000 localhost:5001/mymcp:latest --transport http --host 0.0.0.0 --port 3000
2026-05-14 18:39:46,327 - INFO - Loaded tool module: sum
2026-05-14 18:39:46,329 - INFO - Loaded tool module: echo
2026-05-14 18:39:46,329 - INFO - 📦 Successfully loaded 2 tools
...
INFO     Starting MCP server 'mymcp' with transport 'http' on http://0.0.0.0:3000/mcp

  7. Connect to your MCP server in the Inspector tool.
  8. Try out an MCP tool.
    1. Navigate to the Tools tab. Verify that you see the example_sum, example_echo, and example_greet tools.
    2. Select the example_greet tool and enter any name in the name field, such as me.
    3. Click Execute Tool and verify that you see the Hello, me! message.
    4. Continue testing the other example MCP tools.
    5. Exit the MCP Inspector and stop the running MCP server by pressing ctrl + c.
  9. Publish the MCP server in the registry catalog.
    arctl apply -f mymcp/mcp.yaml
    Example output:
    ✓ MCPServer/mymcp (latest) created

  10. Verify that the MCP server is in the catalog.
    arctl get mcp
    Example output:
    NAME    TAG      DESCRIPTION
mymcp   latest   mymcp MCP server

  11. Open the catalog in the registry UI to see the MCP server listed under MCP servers.
Step 2: Register an agent

Registering an agent adds it to the registry catalog so that it can be discovered by catalog users and deployed to any connected runtime.
This step walks you through how to register an agent depending on whether you want to develop your own agent from scratch or register an existing agent that your team has already built. Select the tab that matches your situation.
Use this path if your team already built an agent outside of Solo Enterprise for agentregistry and you want to bring it into the catalog so that it is discoverable and deployable through the registry.
Unlike developing your own agent from scratch, registering an existing agent with its container image or source repository URL lets Solo Enterprise for agentregistry deploy and manage the agent’s lifecycle across any connected deployment runtime, in addition to providing discoverability for catalog users.
  1. Create a registry catalog entry for your existing agent. To enable Solo Enterprise for agentregistry to deploy the agent to a runtime at a later time, provide either a container image or a source repository, depending on your target runtime:
    • Container image (spec.source.image): Required to deploy to Solo Enterprise for kagent. The registry pulls the image and runs it as a pod in your cluster when you deploy the agent.
    • Source repository URL (spec.source.repository): Required to deploy to cloud-managed agentic platforms, such as AWS Bedrock AgentCore. The repository must include the agent source code and Dockerfile. During a deployment, Solo Enterprise for agentregistry uses these files to build an image that is compatible to run in the runtime that you selected.
      Tip
      If your source repository is private, you must configure registry credentials before the registry can access it. For more information, see Private repository access.
    Example agent definition with an image:
    arctl apply -f - <<EOF
apiVersion: ar.dev/v1alpha1
kind: Agent
metadata:
  name: myagent
spec:
  description: My existing agent
  source:
    image: localhost:5001/myagent:latest
EOF
    Example agent definition with a source repository:
    arctl apply -f - <<EOF
apiVersion: ar.dev/v1alpha1
kind: Agent
metadata:
  name: myagent
spec:
  description: My existing agent
  source:
    repository:
      url: https://github.com/solo-io/doc-examples
      subfolder: agentregistry/myagent
EOF
    FieldDescription
    metadata.nameThe catalog name for the agent. This name is displayed in the registry catalog.
    spec.source.repository.urlThe URL of the GitHub repository that stores the agent source code and Dockerfile.
    spec.source.repository.subfolderOptional. The path within the repository to the agent source code, if it is not at the repository root.
    spec.source.imageThe container image reference, including the registry, image name, and tag.
    Example output:
    ✓ Agent/myagent (latest) created

  2. Verify that the agent is in the catalog.
    arctl get agents
    Example output:
    NAME      TAG      DESCRIPTION
myagent   latest   My existing agent

  3. Open the catalog in the registry UI to see the agent listed under Agents.
Use the arctl CLI to quickly scaffold a sample agent. The scaffold creates a ready-to-run agent with a Dockerfile, agent definition, and agent source code, which is everything you need to later publish the agent in the registry catalog.
  1. Create the agent scaffold. The following command creates an agent that uses the Google ADK with Gemini as the default LLM provider.
    arctl init agent myagent --framework adk --language python  --model-provider gemini --model-name gemini-2.5-flash
    Example output:
    ✓ Created agent: myagent (framework: adk, language: python)

🚀 Next steps:
1. Run locally (optional):
   arctl run myagent
2. Publish to the registry:
   arctl apply -f myagent/agent.yaml

    The scaffold creates the following files:
    FileDescription
    agent.yamlThe agent definition that you publish to the catalog. It describes the agent source image and metadata.
    arctl.yamlThe agent details you specified with the arctl CLI, used to inject metadata labels at publish time.
    .envLocal environment variables for the agent, including the API key for the LLM provider.
    docker-compose.yamlA Docker Compose file for running the agent locally.
    DockerfileThe Dockerfile to build and run the agent in a container.
    myagent/The agent source directory, including agent.py which defines the agent’s behavior.
    otel-collector-config.yamlAn OpenTelemetry configuration for the agent.
    pyproject.tomlThe Python project dependency file.
    README.mdGetting-started notes and customization instructions.
  2. Review the agent definition (agent.yaml) file that the scaffold generated.
    When you scaffold an agent, the default container image location and tag localhost:5001/myagent:latest are added to the agent definition (agent.yaml) file. Before you can add an agent to the registry catalog, the agent definition must either have an image location or a GitHub or GitLab repository URL that points to the Dockerfile and agent source files. Solo Enterprise for agentregistry uses these files to build runtime-specific images when you deploy AI artifacts to agentic platforms, such as AWS Bedrock AgentCore.
    This tutorial uses the default localhost:5001/myagent:latest image location to build the image. To use a private registry or a GitHub or GitLab repository URL instead, update source.image or source.repository fields in the agent.yaml file. For more information, see Build image or store source code.
    cat myagent/agent.yaml
    Example output:
    apiVersion: ar.dev/v1alpha1
kind: Agent
metadata:
  name: myagent
spec:
  description: myagent agent
  source:
    image: localhost:5001/myagent:latest

  3. Build the agent container image before publishing it to the catalog.
    arctl build myagent
    Example output:
    Building agent image: localhost:5001/myagent:latest
Building Docker image for python project...
...
✓ Successfully built Docker image: localhost:5001/myagent:latest

    Tip
    You can use the --push flag to optionally push the container image to your registry.
  4. Save the API key for the Gemini LLM provider. The agent that you scaffold as part of this tutorial uses the Google ADK and Gemini provider by default. To interact with the agent, you must have an API key. You can retrieve the API key or create one by logging in to the Google AI Studio and selecting API Keys.
    GOOGLE_API_KEY=your-api-key-here
  5. Start the agent on your local machine. The following command starts the agent and opens up a chat window.
    arctl run myagent
    Example output:
    [+] Running 2/2
 ✔ Container myagent-otel-collector-1  Started
 ✔ Container myagent-myagent-1         Started

  6. Chat with the agent. For example, you can ask it what it can do for you. Then, hit Enter and wait for the agent to reply. You can exit the agent by using the ctrl + c keys.
  7. Publish the agent in the registry catalog.
    arctl apply -f myagent/agent.yaml
    Example output:
    → Injecting labels from arctl.yaml: arctl.dev/framework=adk, arctl.dev/language=python
✓ Agent/myagent (latest) created

  8. Verify that the agent is in the catalog.
    arctl get agents
    Example output:
    NAME      TAG      MODE     DESCRIPTION
myagent   latest   source   myagent agent

  9. Open the catalog in the registry UI to see your catalog with agents and MCP servers.
Step 3: Register a skill

Publishing a skill adds a reusable instruction set or slash command to the catalog, where any team can discover and reference it in their agent configurations.
  1. Create a skill definition and add the skill to the registry catalog.
    arctl apply -f- <<EOF
apiVersion: ar.dev/v1alpha1
kind: Skill
metadata:
  name: myskill
spec:
  title: myskill
  description: myskill skill
  source:
    repository:
      url: https://github.com/solo-io/doc-examples
      subfolder: agentregistry/myskill  # optional
EOF
    Tip
    To create your own skill, use the arctl init skill myskill command that creates a skill scaffold. Then, adjust the files in the scaffold to your needs.
  2. Verify that the skill is in the catalog.
    arctl get skills
    Example output:
    NAME      TAG      DESCRIPTION
myskill   latest   myskill skill

  3. Open the catalog in the registry UI to see the skill listed under Skills.
Step 4: Register a prompt

Publishing a prompt adds a versioned, org-wide system prompt or instruction template to the catalog. Platform teams can publish standardized baselines — such as safety guardrails, agent persona guidelines, or approved reasoning frameworks — that development teams reference from their agent configurations.
  1. Create a prompt definition and add it to the registry catalog. A prompt definition includes two distinct fields:
    • spec.content: The actual prompt text that agents use at runtime as their system prompt.
    • spec.description: A short catalog label shown in arctl get prompts and the UI. It describes what the prompt is for, not the prompt itself.
    arctl apply -f- <<EOF
apiVersion: ar.dev/v1alpha1
kind: Prompt
metadata:
  name: myprompt
spec:
  content: You are a concise technical assistant. Answer only what is asked. Do not add preamble, filler, or suggestions unless explicitly requested. If you are unsure, say so rather than guessing.
  description: Concise technical assistant baseline
EOF
    Example output:
    ✓ Prompt/myprompt (latest) created

  2. Verify that the prompt is in the catalog.
    arctl get prompts
    Example output:
    NAME       TAG      DESCRIPTION
myprompt   latest   Concise technical assistant baseline

  3. Open the catalog in the registry UI to see the prompt listed under Prompts.
Congratulations! You have a functioning catalog with a versioned MCP server, agent, skill, and prompt. All artifacts are discoverable, reusable, and ready to be deployed to any runtime that Solo Enterprise for agentregistry supports.
Next steps

Now that your catalog is populated, choose a path based on what you want to do next.
Govern catalog access

Control who can publish artifacts to the catalog, require approval before an artifact becomes visible to other teams, and restrict what deployed agents are allowed to call at runtime.

Access control
Configure OIDC authentication and define access policies for users and groups.

Artifact approval
Enable artifact approval mode and manage the approval queue through the UI, API, or Python client.
Discover agents

Connect to a discovery runtime to catalog agents that were deployed outside the registry.

Discover agents on Azure AI Foundry
Connect to Azure AI Foundry and surface existing agents in the registry.

Discover agents on Microsoft Copilot Studio
Connect to Microsoft Copilot Studio and surface existing agents in the registry.
Deploy to a runtime

Connect a deployment runtime and push your catalog artifacts so that agents are running and tools are accessible to users.

Solo Enterprise for kagent
Deploy your catalog artifacts to a Kubernetes cluster with Solo Enterprise for kagent.

AWS Bedrock AgentCore
Deploy your catalog artifacts to AWS Bedrock AgentCore.
Expose and secure MCP servers with agentgateway