MCP Server YAML Creator

Overview

Create valid server.yaml files for custom MCP servers that can be added to Docker MCP Gateway catalogs and profiles using the --server file://server.yaml flag.

MCP servers can be of three types:

• server: Containerized MCP servers (most common)
• remote: Remote HTTP/SSE MCP servers

Quick Start - Creation from Templates

Start from a template for your server type:

• assets/template-server.yaml - Containerized MCP servers
• assets/template-remote.yaml - Remote HTTP/SSE servers

Copy the relevant template and customize it for your needs.

Advanced Configuration

For complex scenarios (nested objects, conditional requirements, OAuth), consult references/spec.md for the complete specification.

Core Requirements

All server.yaml files must include:

name: server-name          # Lowercase, hyphen-separated
type: server               # or: remote
title: Display Name
description: Server capabilities and purpose (1-2 sentences)

Type: "server" (Containerized)

Most common type for custom MCP servers. Requires a Docker image. If the user doesn't have a Docker image, ALWAYS guide them on the process on creating a Dockerfile, building it, and pushing it. If they already have a Dockerfile, ALWAYS guide them on building and pushing the docker image so that it can be referenced in the image field.

Essential fields:

name: my-server
type: server
title: My Server
description: Brief description of what the server does (1-2 sentences)
image: myorg/my-server:latest

Common additions:

• secrets: API keys, tokens (never hardcode)
• config: User-configurable settings
• env: Environment variables (can reference config with {{server-name.property}})
• allowHosts: Network access restrictions
• volumes: File system mounts (can be a named volume "named-volume:/app/data or mapped to a config "{{my-server.config_path}}:/app/config")
• longLived: Keep running vs on-demand for tool calls (only enable this if there's good reason to keep the server running)
• tools: An optional (but very helpful) list of tools the server exposes for discovery purposes

See assets/template-server.yaml for a complete example.

Type: "remote" (HTTP/SSE)

For remotely hosted MCP servers.

Essential fields:

name: remote-server
type: remote
title: Remote Server
description: Brief description of what the server does (1-2 sentences)
remote:
  url: https://mcp.example.com/sse
  transport_type: sse

See assets/template-remote.yaml for a complete example.

Configuration Schema

User-configurable settings allow users to provide values when using your server.

Basic example:

config:
  - name: server-name
    description: Connection settings
    type: object
    properties:
      endpoint:
        type: string
        description: API endpoint URL
      timeout:
        type: number
        description: Timeout in seconds
    required:
      - endpoint

Reference config values in environment variables:

env:
  - name: API_ENDPOINT
    value: "{{server-name.endpoint}}"

Environment variables should only ever be used for:

1. Config values that are setup in the config at the top level.
2. Hard-coded environment variables that the server requires.
3. Secrets should never be added here, as they are injected automatically as environment variables.

For arrays, nested objects, conditional requirements (anyOf/oneOf), see references/spec.md.

Secrets and Authentication

Always use the secrets field for sensitive values:

secrets:
  - name: server-name.api_key
    env: API_KEY
    example: YOUR_API_KEY

Secrets are automatically injected as environment variables. NEVER put a secret in the env field of the server yaml.

For OAuth configuration, see references/spec.md.

Network Security

Option 1: Restrict to specific hosts

allowHosts:
  - api.example.com:443
  - github.com:443

Option 2: Disable all network

disableNetwork: true

Usage

After creating server.yaml, add it to a profile or catalog:

# Add to a profile
docker mcp profile server add <profile-id> --server file://./server.yaml

# Create catalog with the server
docker mcp catalog-next create <catalog-id> --title "My Catalog" --server file://./server.yaml

Be sure to ask the user what they would like to do. The recommended approach would be to create a new catalog and add it to a new catalog.

If you need to understand more about what docker mcp commands are available, check out the docs at https://raw.githubusercontent.com/docker/mcp-gateway/refs/heads/main/docs/profiles.md

Best Practices

1. Use lowercase-hyphenated naming: my-custom-server
2. Keep server descriptions short and concise (1-2 sentences maximum)
3. Always use secrets field for API keys/tokens, never hardcode in env
4. Use allowHosts to restrict network access
5. Provide clear descriptions for all config properties
6. Consider if any environment variables should be hard-coded rather than user-defined.
7. Use SHA256 digests for production images, tags for development
8. Mark config fields as required when necessary
9. Omit fields that are empty (e.g. env, secrets)
10. Test the server.yaml by adding it to a profile and running the gateway
11. ONLY use or show docker mcp commands that you've been told about. Don't make up commands.

Resources

• assets/: Template examples for each server type (server, remote)
• references/spec.md: Complete technical specification with advanced patterns