mcp-server-yaml-creator

What this skill does

# 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:

```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:

```yaml
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**
```yaml
allowHosts:
  - api.example.com:443
  - github.com:443
```

**Option 2: Disable all network**
```yaml
disableNetwork: true
```

## Usage

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

```bash
# 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