How to Build and Deploy Custom MCP Catalogs and Profiles for Enterprise AI Tooling

What You Need

• Docker Desktop installed (version 4.30 or later recommended)
• A Docker Hub account (or any OCI-compliant registry)
• Basic familiarity with YAML and command-line tools
• Access to a code editor (e.g., VS Code)
• Optional: Git to clone example repositories

Step-by-Step Guide

Step 1: Set Up Your Custom MCP Server Image

Start by building an MCP server and pushing its Docker image to a registry. For this example, we use a simple roll-dice server that communicates over stdio. Clone the reference repository from GitHub:

git clone https://github.com/docker/roll-dice-mcp.git
cd roll-dice-mcp
docker build -t your-dockerhub-id/mcp-dice:latest .
docker push your-dockerhub-id/mcp-dice:latest

Once the image is published, create a metadata file (e.g., mcp-dice.yaml) that describes the server:

name: roll-dice
title: Roll Dice
type: server
image: your-dockerhub-id/mcp-dice@latest
description: An MCP server that can roll dice randomly

This YAML file will be part of your custom catalog later.

Step 2: Create the Custom Catalog Manifest

A custom catalog is defined by a directory that contains a catalog.yaml manifest and one or more server definition files (like the one above). Create a new folder for your catalog:

mkdir my-mcp-catalog
cd my-mcp-catalog

Inside, create catalog.yaml with the following structure:

version: 1
servers:
  - roll-dice
  - docker-postgres  # from Docker’s MCP Catalog

Next, add the server definition files. For the roll-dice server, copy your mcp-dice.yaml into this folder. For servers from Docker’s MCP Catalog, you can reference them by name—Docker Desktop will resolve them automatically. To include a completely custom server built internally, simply add another YAML file following the same schema.

Step 3: Publish the Catalog to a Registry

Once your catalog folder is ready, package it as an OCI artifact and push to Docker Hub. Use the Docker CLI to create and push the catalog:

docker push your-dockerhub-id/my-mcp-catalog:latest --platform linux/amd64 --format oci

Alternatively, you can distribute the catalog folder via a private HTTP server or shared network drive. For enterprise use, Docker Hub provides simple access control and versioning.

Step 4: Import the Catalog into Docker Desktop

With the catalog published, team members can import it into Docker Desktop to discover and use approved MCP servers. In Docker Desktop, go to Settings > MCP > Catalogs and add the catalog URL:

your-dockerhub-id/my-mcp-catalog:latest

Docker Desktop will fetch and display all servers defined in the catalog. Users can then browse and enable servers directly from the interface.

Step 5: Define and Share MCP Profiles

Profiles extend catalogs by letting you group servers into portable configurations. For example, you can create a data-analysis profile that includes a Postgres server, a file system server, and your custom dice server. Create a profile.yaml file:

name: data-analysis
servers:
  - docker-postgres
  - roll-dice
  - filesystem

Save this alongside your catalog or share it separately. Profiles can be checked into version control, shared via link, or imported directly into Docker Desktop. When a teammate imports a profile, Docker Desktop automatically enables all listed servers—no manual searching required.

Step 6: Test and Iterate

After importing the catalog and activating a profile, verify that the MCP servers are working. Open an MCP-aware tool (like Copilot or a custom agent) and execute a request—e.g., “Roll a d20.” The dice server should respond with a random number. If something fails, check Docker Desktop logs and ensure the images are accessible. Update your catalog YAML and push new versions as you refine your server collection.

Tips and Best Practices

• Use Semantic Versioning on your catalog pushes to allow smooth upgrades and rollbacks.
• Combine public and private servers in the same catalog to balance convenience with security.
• Document your profiles with comments in YAML so teammates know what each set of servers does.
• Leverage Docker’s scanning to ensure all images in your catalog are free of vulnerabilities.
• Test profiles in a staging environment before distributing them to the whole team.
• Promote reuse by creating base profiles (e.g., core-infra) that other profiles can inherit from (future feature).