Update some more docs.

Author: cmrigney

docs/catalog.md

@@ -1,5 +1,7 @@
 # MCP Catalog Management
 
+*Important note: This method of catalog management is deprecated. Please see [Profiles](profiles.md) for more information on how to use catalogs.*
+
 Docker MCP Gateway provides comprehensive catalog management capabilities, allowing you to create, manage, and use custom MCP server catalogs alongside Docker's official catalog.
 
 ## Quick Start with Bootstrap
@@ -8,7 +10,7 @@ The easiest way to get started with custom catalogs is to use the `bootstrap` co
 
 ```bash
 # Create a starter catalog with Docker Hub and Docker CLI server examples
-docker mcp catalog bootstrap ./my-starter-catalog.yaml
+docker mcp catalog-deprecated bootstrap ./my-starter-catalog.yaml
 
 # The file now contains properly formatted server definitions you can modify
 ```
@@ -25,17 +27,17 @@ This creates a YAML file with real server definitions that you can:
 
 ```bash
 # List all configured catalogs
-docker mcp catalog ls
+docker mcp catalog-deprecated ls
 
 # List in JSON format
-docker mcp catalog ls --format=json
+docker mcp catalog-deprecated ls --format=json
 ```
 
 ### Creating Catalogs
 
 ```bash
 # Create a new empty catalog
-docker mcp catalog create my-custom-catalog
+docker mcp catalog-deprecated create my-custom-catalog
 
 # The catalog is now ready for adding servers
 ```
@@ -44,62 +46,62 @@ docker mcp catalog create my-custom-catalog
 
 ```bash
 # Show servers in the default Docker catalog
-docker mcp catalog show
+docker mcp catalog-deprecated show
 
 # Show servers in a specific catalog
-docker mcp catalog show my-custom-catalog
+docker mcp catalog-deprecated show my-custom-catalog
 
 # Show in different formats
-docker mcp catalog show docker-mcp --format json
-docker mcp catalog show docker-mcp --format yaml
+docker mcp catalog-deprecated show docker-mcp --format json
+docker mcp catalog-deprecated show docker-mcp --format yaml
 ```
 
 ### Adding Servers to Catalogs
 
 ```bash
 # Add a server from another catalog file
-docker mcp catalog add my-custom-catalog server-name ./source-catalog.yaml
+docker mcp catalog-deprecated add my-custom-catalog server-name ./source-catalog.yaml
 
 # Force overwrite if server already exists
-docker mcp catalog add my-custom-catalog server-name ./source-catalog.yaml --force
+docker mcp catalog-deprecated add my-custom-catalog server-name ./source-catalog.yaml --force
 ```
 
 ### Importing Servers from OSS MCP Community Registry
 
 ```bash
 # replace {id} in the url below
-docker mcp catalog import my-custom-catalog --mcp-registry https://registry.modelcontextprotocol.io/v0/servers/{id}
+docker mcp catalog-deprecated import my-custom-catalog --mcp-registry https://registry.modelcontextprotocol.io/v0/servers/{id}
 ```
 
 ### Importing Other Catalogs
 
 ```bash
 # Import a catalog from a local file
-docker mcp catalog import ./my-catalog.yaml
+docker mcp catalog-deprecated import ./my-catalog.yaml
 
 # Import from a URL
-docker mcp catalog import https://example.com/catalog.yaml
+docker mcp catalog-deprecated import https://example.com/catalog.yaml
 
 # Import with an alias
-docker mcp catalog import team-servers
+docker mcp catalog-deprecated import team-servers
 ```
 
 ### Exporting Catalogs
 
 ```bash
 # Export a custom catalog to a file
-docker mcp catalog export my-custom-catalog ./backup.yaml
+docker mcp catalog-deprecated export my-custom-catalog ./backup.yaml
 
 # Note: You cannot export Docker's official catalog
-docker mcp catalog export docker-mcp ./docker-backup.yaml
-# Error: Cannot export the Docker MCP catalog as it is managed by Docker
+docker mcp catalog-deprecated export docker-mcp ./docker-backup.yaml
+# Error: Cannot export the Docker MCP catalog-deprecated as it is managed by Docker
 ```
 
 ### Forking Catalogs
 
 ```bash
 # Create a copy of an existing catalog
-docker mcp catalog fork docker-mcp my-custom-version
+docker mcp catalog-deprecated fork docker-mcp my-custom-version
 
 # Now you can modify my-custom-version independently
 ```
@@ -108,7 +110,7 @@ docker mcp catalog fork docker-mcp my-custom-version
 
 ```bash
 # Remove a custom catalog
-docker mcp catalog rm my-custom-catalog
+docker mcp catalog-deprecated rm my-custom-catalog
 
 # Note: You cannot remove Docker's official catalog
 ```
@@ -117,17 +119,17 @@ docker mcp catalog rm my-custom-catalog
 
 ```bash
 # Update all catalogs
-docker mcp catalog update
+docker mcp catalog-deprecated update
 
 # Update a specific catalog
-docker mcp catalog update my-custom-catalog
+docker mcp catalog-deprecated update my-custom-catalog
 ```
 
 ### Resetting Catalogs
 
 ```bash
 # Remove all custom catalogs and reset to Docker defaults
-docker mcp catalog reset
+docker mcp catalog-deprecated reset
 ```
 
 ## Catalog YAML Format
@@ -255,13 +257,13 @@ registry:
 
 ```bash
 # 1. Create a starter catalog for reference
-docker mcp catalog bootstrap ./starter-catalog.yaml
+docker mcp catalog-deprecated bootstrap ./starter-catalog.yaml
 
 # 2. Create your own catalog
-docker mcp catalog create dev-servers
+docker mcp catalog-deprecated create dev-servers
 
 # 3. Add useful servers from the starter (optional)
-docker mcp catalog add dev-servers dockerhub ./starter-catalog.yaml
+docker mcp catalog-deprecated add dev-servers dockerhub ./starter-catalog.yaml
 
 # 4. Create a custom server definition file
 cat > my-server.yaml << EOF
@@ -276,66 +278,66 @@ registry:
 EOF
 
 # 5. Add your custom server
-docker mcp catalog add dev-servers my-dev-server ./my-server.yaml
+docker mcp catalog-deprecated add dev-servers my-dev-server ./my-server.yaml
 ```
 
 ### Importing from the OSS MCP Community Registry
 
 ```bash
 # 1. Create a destination catalog for your community servers
-docker mcp catalog create community-catalog
+docker mcp catalog-deprecated create community-catalog
 
 # 2. import the OSS MCP community server resource
-docker mcp catalog import --mcp-registry http://registry.modelcontextprotocol.io/v0/servers/71de5a2a-6cfb-4250-a196-f93080ecc860
+docker mcp catalog-deprecated import --mcp-registry http://registry.modelcontextprotocol.io/v0/servers/71de5a2a-6cfb-4250-a196-f93080ecc860
 
 # 3. show the imported server
-docker mcp catalog show community-catalog --format=json | jq .
+docker mcp catalog-deprecated show community-catalog --format=json | jq .
 ```
 
 ### Team Sharing Workflow
 
 ```bash
 # Team lead: Create and export a team catalog
-docker mcp catalog create team-servers
-docker mcp catalog add team-servers shared-db ./shared-db-server.yaml
-docker mcp catalog add team-servers api-helper ./api-helper-server.yaml
-docker mcp catalog export team-servers ./team-catalog.yaml
+docker mcp catalog-deprecated create team-servers
+docker mcp catalog-deprecated add team-servers shared-db ./shared-db-server.yaml
+docker mcp catalog-deprecated add team-servers api-helper ./api-helper-server.yaml
+docker mcp catalog-deprecated export team-servers ./team-catalog.yaml
 
 # Share team-catalog.yaml with team members
 
 # Team members: Import the shared catalog
-docker mcp catalog import ./team-catalog.yaml
+docker mcp catalog-deprecated import ./team-catalog.yaml
 docker mcp gateway run
 ```
 
 ### Testing New Servers
 
 ```bash
 # 1. Create a test catalog
-docker mcp catalog create test-servers
+docker mcp catalog-deprecated create test-servers
 
 # 2. Add your server for testing
-docker mcp catalog add test-servers test-server ./test-server.yaml
+docker mcp catalog-deprecated add test-servers test-server ./test-server.yaml
 
 # 3. Run gateway with test catalog
 docker mcp gateway run
 
 # 4. When done testing, clean up
-docker mcp catalog rm test-servers
+docker mcp catalog-deprecated rm test-servers
 ```
 
 ### Production Deployment
 
 ```bash
 # 1. Create production catalog
-docker mcp catalog create prod-servers
+docker mcp catalog-deprecated create prod-servers
 
 # 2. Add only production-ready servers
-docker mcp catalog add prod-servers monitoring ./monitoring-server.yaml
-docker mcp catalog add prod-servers logging ./logging-server.yaml
+docker mcp catalog-deprecated add prod-servers monitoring ./monitoring-server.yaml
+docker mcp catalog-deprecated add prod-servers logging ./logging-server.yaml
 
 # 3. Export for backup and deployment
-docker mcp catalog export prod-servers ./prod-catalog-backup.yaml
+docker mcp catalog-deprecated export prod-servers ./prod-catalog-backup.yaml
 
 # 4. Deploy with production catalog
 docker mcp gateway run
@@ -375,7 +377,7 @@ Error: server "server-name" not found in catalog "source.yaml"
 
 ### Cannot Export Docker Catalog
 ```bash
-Error: cannot export the Docker MCP catalog as it is managed by Docker
+Error: cannot export the Docker MCP catalog-deprecated as it is managed by Docker
 ```
 **Solution**: This is intentional - Docker's catalog cannot be exported. Use `bootstrap` to get Docker server examples instead.
 

docs/mcp-gateway.md

@@ -9,29 +9,23 @@ See [Why running MCP Servers in Container is more secure](security.md)
 Start up an MCP Gateway. This can be used for one client, or to service multiple clients if using either `sse` or `streaming` transports.
 
 ```bash
-# Run the MCP gateway (stdio)
+# Run with a profile (stdio)
+docker mcp gateway run --profile my-profile
+
+# Run the MCP gateway (stdio) - uses the profile with ID "default"
 docker mcp gateway run
 
 # Run the MCP gateway (streaming)
-docker mcp gateway run --port 8080 --transport streaming
-
-# Run with specific servers only, and select all tools from server1 and just tool2 from server2
-docker mcp gateway run --servers server1,server2 --tools server1:* --tools server2:tool2
-
-# Run a fallback secret lookup - lookup desktop secret first and the fallback to a local .env file
-docker mcp gateway run --secrets=docker-desktop:./.env
+docker mcp gateway run --profile my-profile --port 8080 --transport streaming
 
 # Run with verbose logging
-docker mcp gateway run --verbose --log-calls
+docker mcp gateway run  --profile my-profile --verbose --log-calls
 
 # Run in watch mode (auto-reload on config changes)
-docker mcp gateway run --watch
+docker mcp gateway run --profile my-profile --watch
 
 # Run a standalone dockerized MCP server (no catalog required)
 docker mcp gateway run --server docker.io/namespace/repository:latest
-
-# Run with a profile (requires profiles feature to be enabled)
-docker mcp gateway run --profile my-working-set
 ```
 
 See [Profiles](profiles.md) for more information about organizing servers into reusable collections.
@@ -45,14 +39,16 @@ A typical usage looks like this Claude Desktop configuration:
     "mcpServers": {
         "MCP_DOCKER": {
             "command": "docker",
-            "args": ["mcp", "gateway", "run"]
+            "args": ["mcp", "gateway", "run", "--profile", "my-profile"]
         }
     }
 }
 ```
 
 ## How to run the MCP Gateway with Docker Compose?
 
+*Note: This is using a deprecated method of working with the gateway. Profile support in compose is coming soon.*
+
 The simplest way to tun the MCP Gateway with Docker Compose is with this kind of compose file:
 
 ```
@@ -61,8 +57,10 @@ services:
     image: docker/mcp-gateway
     command:
       - --servers=duckduckgo
+      - --catalog=/mcp/catalog.yaml
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
+      - ./catalog.yaml:/mcp/catalog.yaml
 ```
 
 ### What does it do?
@@ -90,6 +88,7 @@ Docker MCP Toolkit's CLI - Manage your MCP servers and clients.
 Usage: docker mcp gateway run
 
 Flags:
+      --profile string                    Profile ID to use (incompatible with --servers, --enable-all-servers, --catalog, --registry, --config, --tools-config, --secrets, --oci-ref, --mcp-registry)
       --block-network             Block tools from accessing forbidden network resources
       --block-secrets             Block secrets from being/received sent to/from tools (default true)
       --catalog string            path to the docker-mcp.yaml catalog (absolute or relative to ~/.docker/mcp/catalogs/) (default "docker-mcp.yaml")
@@ -109,11 +108,8 @@ Flags:
       --verbose                   Verbose output
       --verify-signatures         Verify signatures of the server images
       --watch                     Watch for changes and reconfigure the gateway (default true)
-      --profile string            Profile ID to use (requires working-sets feature, mutually exclusive with --servers and --enable-all-servers)
 ```
 
-**Note:** The `--profile` flag is only available when the `profiles` feature is enabled via `docker mcp feature enable profiles`.
-
 ## Troubleshooting
 
 Look at our [Troubleshooting Guide](/docs/troubleshooting.md)

docs/troubleshooting.md

@@ -8,7 +8,7 @@ What can you do to pinpoint where the problem comes from?
 The go to command to start a fresh Gateway, plugged into Docker Desltop's Toolkit is this one:
 
 ```console
-docker mcp gateway run --verbose --dry-run
+docker mcp gateway run --profile my-profile --verbose --dry-run
 ```
 
 This will show you how the Gateway is reading the configuration, which servers are actually
@@ -19,12 +19,6 @@ It'll show you how many tools you have, in aggregate.
 This is usually a good way to troubleshoot missing images, invalid server names, missing config
 or secrets...
 
-You can also focus a one given server with:
-
-```console
-docker mcp gateway run --verbose --dry-run --servers=duckduckgo
-```
-
 ## Debug tool calls
 
 Full fledge MCP clients might sometimes hide the errors they encounter while calling tools