### JavaScript Examples of Valid Semantic Versions

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/explanations/versioning.md

This JavaScript snippet provides examples of valid semantic version strings that can be used for MCP servers. It includes basic, prerelease, and release candidate formats.

```javascript
"1.0.0"          // Basic semantic version
"2.1.3-alpha"    // Prerelease version  
"1.0.0-beta.1"   // Prerelease with numeric suffix
"3.0.0-rc.2"     // Release candidate
```

--------------------------------

### mcp-publisher init Command Example (JSON Output)

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

Shows an example of the `server.json` file generated by the `mcp-publisher init` command. This template includes basic server information and package details.

```json
{
  "name": "io.github.username/server-name",
  "description": "TODO: Add server description",
  "version": "1.0.0",
  "packages": [
    {
      "registry_type": "npm",
      "identifier": "detected-package-name",
      "version": "1.0.0"
    }
  ]
}
```

--------------------------------

### Install mcp-publisher CLI (macOS/Linux/WSL - From Source)

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/guides/publishing/publish-server.md

Installs the MCP Publisher CLI from source for macOS, Linux, and WSL. This method requires Git, Make, and Go 1.24+.

```bash
# Clone the registry repository
git clone https://github.com/modelcontextprotocol/registry
cd registry
make publisher

# The binary will be at bin/mcp-publisher
export PATH=$PATH:$(pwd)/bin
```

--------------------------------

### JSON Structure for Alignment Example

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/explanations/versioning.md

This JSON example demonstrates version alignment, specifically showing a prerelease version for the registry ('1.2.3-1') while the package itself is at a stable version ('1.2.3'). This is useful for managing release candidates or specific registry deployments.

```json
{
  "version": "1.2.3-1",
  "packages": [{
    "registry_name": "npm",
    "name": "@myorg/k8s-server", 
    "version": "1.2.3"
  }]
}
```

--------------------------------

### mcp-publisher publish Command Example (Bash)

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

Provides examples of using the `mcp-publisher publish` command for basic publishing, performing a dry run for validation, and specifying a custom file location for the server configuration.

```bash
# Basic publish
mcp-publisher publish

# Dry run validation
mcp-publisher publish --dry-run

# Custom file location
mcp-publisher publish --file=./config/server.json
```

--------------------------------

### Release Guide

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

Guide on how to create and manage releases for the MCP Registry, including steps for GitHub releases and Docker image tagging.

```APIDOC
## Release Guide

### Creating a Release

1. **Go to GitHub**: Navigate to https://github.com/modelcontextprotocol/registry/releases
2. **Click "Draft a new release"**
3. **Choose a tag**: Click "Choose a tag" and type a new semantic version that follows the last one available (e.g., `v1.0.0`)
4. **Generate notes**: Click "Generate release notes" to auto-populate the name and description
5. **Publish**: Click "Publish release"

The release workflow will automatically:
- Build binaries for 6 platforms (Linux, macOS, Windows × amd64, arm64)
- Create and push Docker images with `:latest` and `:vX.Y.Z` tags
- Attach all artifacts to the GitHub release
- Generate checksums and signatures

### After Release

- Docker images will be available at:
  - `ghcr.io/modelcontextprotocol/registry:latest` - Latest stable release
  - `ghcr.io/modelcontextprotocol/registry:vX.Y.Z` - Specific release version
- Binaries can be downloaded from the GitHub release page

### Docker Image Tags

The registry publishes different Docker image tags for different use cases:

- **`:latest`** - Latest stable release (updated only on releases)
- **`:vX.Y.Z`** - Specific release versions (e.g., `:v1.0.0`)
- **`:main`** - Rolling tag updated on every push to main branch (continuous deployment)
- **`:main-YYYYMMDD-sha`** - Specific development builds from main branch

### Versioning

We use semantic versioning (SemVer):
- `v1.0.0` - Major release with breaking changes
- `v1.1.0` - Minor release with new features
- `v1.0.1` - Patch release with bug fixes
```

--------------------------------

### mcp-publisher login http Setup (Bash)

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

Provides bash commands for generating an Ed25519 keypair, which is used for both DNS and HTTP verification setup. The public key needs to be hosted at a specific URL.

```bash
# Generate keypair (same as DNS)openssl genpkey -algorithm Ed25519 -out key.pem

# Host public key at:
# https://example.com/.well-known/mcp-registry-auth
# Content: v=MCPv1; k=ed25519; p=PUBLIC_KEY
```

--------------------------------

### Install mcp-publisher CLI (macOS/Linux/WSL - Binaries)

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/guides/publishing/publish-server.md

Installs the MCP Publisher CLI using pre-built binaries for macOS, Linux, and WSL. It downloads, extracts, and moves the executable to the system's PATH.

```bash
curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.1.0/mcp-publisher_1.1.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/
```

--------------------------------

### Install MCP Publisher CLI (macOS/Linux/WSL)

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

Installs the MCP Publisher CLI on macOS, Linux, or WSL. This is the primary tool for managing and publishing MCP servers to the registry. It can be installed using Homebrew, pre-built binaries, or by building from source.

```bash
brew install mcp-publisher
```

```bash
curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/
```

```bash
# Clone the registry repository
git clone https://github.com/modelcontextprotocol/registry
cd registry
make publisher

# The binary will be at bin/mcp-publisher
export PATH=$PATH:$(pwd)/bin
```

--------------------------------

### Add Minimal server.json Example

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

This snippet provides a minimal example of a `server.json` file to be included in the documentation. This serves as a basic template for users to understand the structure and required fields.

```json
{
  "registry_type": "mycustomregistry",
  "registry_base_url": "https://mycustomregistry.example.com",
  "runtime_hint": "mcp-cli publish mycustomregistry"
}

```

--------------------------------

### Install mcp-publisher CLI (Windows PowerShell - Binaries)

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/guides/publishing/publish-server.md

Installs the MCP Publisher CLI on Windows using pre-built binaries. It downloads, extracts, and prepares the executable for use in the system's PATH.

```powershell
$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }; Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/download/v1.1.0/mcp-publisher_1.1.0_windows_$arch.tar.gz" -OutFile "mcp-publisher.tar.gz"; tar xf mcp-publisher.tar.gz mcp-publisher.exe; rm mcp-publisher.tar.gz
# Move mcp-publisher.exe to a directory in your PATH
```

--------------------------------

### Example server.json Structure

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/guides/publishing/publish-server.md

A basic structure for the `server.json` file, including schema, name, description, version, and package deployment details for NPM.

```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
  "name": "io.github.yourname/your-server",
  "description": "A description of your MCP server",
  "version": "1.0.0",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "your-package-name",
      "version": "1.0.0",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}
```

--------------------------------

### Remote Server Versioning

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/explanations/versioning.md

This section explains versioning for remote servers that do not have package dependencies. It provides examples of the JSON structure and outlines different versioning strategy options.

```APIDOC
## Remote Server Versioning

### Description
Manages versioning for remote servers that do not rely on specific package dependencies. This focuses on the server's own version and its remote endpoints.

### Method
POST (Assumed, as this describes data structure)

### Endpoint
/modelcontextprotocol/registry (Assumed)

### Request Body
- **version** (string) - Required - The version of the remote server.
- **remotes** (array) - Optional - A list of remote endpoints for the server.
  - **transport_type** (string) - Required - The transport protocol (e.g., 'sse').
  - **url** (string) - Required - The URL of the remote endpoint.

### Request Example
```json
{
  "version": "2.1.0",
  "remotes": [
    {
      "transport_type": "sse",
      "url": "https://api.myservice.com/mcp/v2.1"
    }
  ]
}
```

### Response
#### Success Response (200)
Indicates successful processing of the remote server versioning information.

#### Response Example
(No example provided in source text)

### Versioning Strategy Options
- **API versioning**: Match your service API version.
- **Semantic versioning**: Standard semver for feature changes.
- **Date-based**: e.g., `2024.03.15` for regular releases.
```

--------------------------------

### Install mcp-publisher CLI (Bash)

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

Provides the command to install the `mcp-publisher` command-line interface tool using Homebrew on macOS and Linux systems.

```bash
$ brew install mcp-publisher
```

--------------------------------

### Create New Publishing Guide

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

This snippet represents a new publishing guide file for a custom registry, following the pattern of existing guides like `publish-npm.md`. It should include instructions for preparing packages and any specific validation requirements for the custom registry.

```markdown
# Publishing to MyCustomRegistry

This guide explains how to prepare and publish packages to the MyCustomRegistry.

## Prerequisites

- Ensure you have the `mcp-cli` installed and configured.
- Your package must adhere to the MyCustomRegistry's specific validation rules.

## Preparing Your Package

1. **Metadata**: Ensure your package includes the necessary metadata as defined by MyCustomRegistry.
2. **Validation**: Run local validation checks if available for MyCustomRegistry.

## Publishing Steps

Use the `mcp-cli` to publish your package:

```bash
mcp-cli publish mycustomregistry --package /path/to/your/package --version 1.0.0
```

Replace `/path/to/your/package` with the actual path to your package directory or artifact.

## Specific Validation Requirements

MyCustomRegistry requires the following:

- **Unique Naming**: Package names must be unique within the registry.
- **License Information**: A valid SPDX license identifier must be included in the package metadata.
- **Security Scan**: Packages must pass a security vulnerability scan.

Refer to the [MyCustomRegistry documentation](https://docs.mycustomregistry.example.com/validation) for detailed requirements.

```

--------------------------------

### MCP Server Configuration with Fixed Package Arguments (NuGet)

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json.md

This JSON configuration defines an MCP server using a NuGet package and specifies fixed command-line arguments required to start the server. The `packageArguments` field, containing `positional` arguments, instructs the MCP client on how to correctly invoke the server application, ensuring necessary parameters like 'mcp start' are passed.

```json
{
  "name": "io.github.joelverhagen/knapcode-samplemcpserver",
  "description": "Sample NuGet MCP server for a random number and random weather",
  "version": "0.4.0-beta",
  "packages": [
    {
      "registryType": "nuget",
      "registryBaseUrl": "https://api.nuget.org",
      "identifier": "Knapcode.SampleMcpServer",
      "version": "0.4.0-beta",
      "transport": {
        "type": "stdio"
      },
      "packageArguments": [
        {
          "type": "positional",
          "value": "mcp"
        },
        {
          "type": "positional",
          "value": "start"
        }
      ]
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "nuget-publisher",
      "version": "2.1.0",
      "build_info": {
        "timestamp": "2023-11-15T14:22:00Z",
        "pipeline_id": "nuget-build-456"
      }
    }
  }
}
```

--------------------------------

### Remote Server Versioning Without Package Dependencies (JSON)

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/explanations/versioning.md

This JSON example shows how to version remote servers that do not have associated package dependencies. It includes options for versioning strategies such as API versioning, semantic versioning, and date-based versioning.

```json
{
  "version": "2.1.0",
  "remotes": [
    {
      "transport_type": "sse",
      "url": "https://api.myservice.com/mcp/v2.1"
    }
  ]
}
```

--------------------------------

### Install MCP Publisher CLI (Windows PowerShell)

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

Installs the MCP Publisher CLI on Windows using PowerShell. It downloads pre-built binaries and extracts the executable to a location within the system's PATH.

```powershell
$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }; Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_windows_$arch.tar.gz" -OutFile "mcp-publisher.tar.gz"; tar xf mcp-publisher.tar.gz mcp-publisher.exe; rm mcp-publisher.tar.gz
# Move mcp-publisher.exe to a directory in your PATH
```

--------------------------------

### JavaScript Examples of Allowed Non-Semantic Versions

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/explanations/versioning.md

This JavaScript snippet shows examples of non-semantic version strings that are still allowed by the MCP registry. These include versions prefixed with 'v' and date-based versioning.

```javascript
"v1.0"           // Version with prefix
"2021.03.15"     // Date-based versioning
```

--------------------------------

### Example MCP Server JSON Configuration

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

A sample `server.json` file for an MCP server. It includes schema information, server name, description, version, and package deployment details for npm.

```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "io.github.yourname/your-server",
  "description": "A description of your MCP server",
  "version": "1.0.0",
  "packages": [
    {
      "registry_type": "npm",
      "identifier": "your-package-name",
      "version": "1.0.0"
    }
  ]
}
```

--------------------------------

### Build and Test MCP Publisher Tool Locally

Source: https://github.com/modelcontextprotocol/registry/blob/main/cmd/publisher/README.md

This snippet outlines the steps to build the MCP Publisher tool and set up a local development environment with a registry. It involves using make commands to build the binary and start a local registry using docker-compose. Subsequently, it demonstrates initializing, logging in, and publishing a server to the local registry.

```bash
# Build the tool
make publisher

# Test locally 
make dev-compose  # Start local registry
./bin/mcp-publisher init
./bin/mcp-publisher login none --registry=http://localhost:8080
./bin/mcp-publisher publish --registry=http://localhost:8080
```

--------------------------------

### Install mcp-publisher CLI using Homebrew

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/cli/commands.md

Installs the `mcp-publisher` CLI tool on macOS and Linux systems using the Homebrew package manager. This is the primary method for obtaining the CLI.

```bash
brew install mcp-publisher
```

--------------------------------

### Server with Custom Installation Path

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json.md

Configuration for an MCP server that does not follow standard packaging. It uses the `websiteUrl` field to provide users with documentation for custom installation or integration into applications.

```APIDOC
## Server with Custom Installation Path

### Description
This configuration is for MCP servers that have a custom installation path or are embedded within applications without using standard packages. The `websiteUrl` field is used to direct users to specific documentation or guides that explain how to set up or integrate the MCP server.

### Method
N/A (Configuration Schema)

### Endpoint
N/A (Configuration Schema)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A (This is a schema definition)

### Request Example
```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
  "name": "io.modelcontextprotocol.anonymous/embedded-mcp",
  "description": "MCP server embedded in a Desktop app",
  "websiteUrl": "https://anonymous.modelcontextprotocol.io/embedded-mcp-guide",
  "version": "0.1.0"
}
```

### Response
N/A (This is a schema definition)

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### MCP Server with Custom Installation Path Configuration (JSON)

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json.md

Defines an MCP server that does not follow standard packaging conventions or is embedded within an application. It uses the `websiteUrl` field to link to external setup documentation.

```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
  "name": "io.modelcontextprotocol.anonymous/embedded-mcp",
  "description": "MCP server embedded in a Desktop app",
  "websiteUrl": "https://anonymous.modelcontextprotocol.io/embedded-mcp-guide",
  "version": "0.1.0"
}

```

--------------------------------

### Port-forwarding MinIO Web Console (Bash)

Source: https://github.com/modelcontextprotocol/registry/blob/main/deploy/README.md

This command forwards the MinIO service to the local machine, allowing access to its web console for managing backups. It requires kubectl to be installed and configured.

```bash
kubectl port-forward -n minio svc/minio 9000:9000 9001:9001
```

--------------------------------

### MCP Server with Custom Installation Path (JSON)

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

This JSON configuration is for an MCP server embedded in an application without a standalone package or public repository. It uses the 'website_url' field to direct users to documentation for custom installation or setup procedures.

```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "io.modelcontextprotocol.anonymous/embedded-mcp",
  "description": "MCP server embedded in a Desktop app",
  "status": "active",
  "website_url": "https://anonymous.modelcontextprotocol.io/embedded-mcp-guide",
  "version": "0.1.0"
}
```

--------------------------------

### Basic Example: List Servers Response (JSON)

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

Illustrates the expected JSON response format when listing servers from the Model Context Protocol Registry. This includes server details, count, and pagination metadata.

```json
{
  "servers": [
    {
      "name": "io.modelcontextprotocol/filesystem",
      "description": "Filesystem operations server",
      "status": "active",
      "version": "1.0.2"
    }
  ],
  "metadata": {
    "count": 10,
    "next_cursor": "eyJ..."
  }
}
```

--------------------------------

### Server Configuration (server.json)

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/guides/publishing/publish-server.md

Examples and explanations for configuring the server.json file for both packages and remote deployments.

```APIDOC
## Server Configuration (server.json)

### Example server.json (Packages)

```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
  "name": "io.github.username/server-name",
  "description": "A server that provides MCPB package functionality",
  "version": "1.0.0",
  "packages": [
    {
      "registryType": "mcpb",
      "identifier": "https://github.com/you/your-repo/releases/download/v1.0.0/server.mcpb",
      "version": "1.0.0",
      "fileSha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}
```

### File Hash Validation

- **Authors** are responsible for generating correct SHA-256 hashes when creating server.json.
- **MCP clients** validate the hash before installing packages to ensure file integrity.
- **The official registry** stores hashes but does not validate them.
- **Subregistries** may choose to implement their own validation.

### Remote Deployment Configuration

Add the `remotes` field to your `server.json`:

```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
  "name": "com.yourcompany/api-server",
  "description": "Cloud-hosted MCP server for API operations",
  "version": "2.0.0",
  "remotes": [
    {
      "type": "sse",
      "url": "https://mcp.yourcompany.com/sse"
    }
  ]
}
```

### Multiple Transport Options

```json
{
  "remotes": [
    {
      "type": "sse",
      "url": "https://mcp.yourcompany.com/sse"
    },
    {
      "type": "streamable-http", 
      "url": "https://mcp.yourcompany.com/http"
    }
  ]
}
```

### URL Validation Requirements

- For `com.yourcompany/*` namespaces: URLs must be on `yourcompany.com` or its subdomains.
- For `io.github.username/*` namespaces: No URL restrictions.

### Authentication Headers (Optional)

```json
{
  "remotes": [
    {
      "type": "sse",
      "url": "https://mcp.yourcompany.com/sse",
      "headers": [
        {
          "name": "X-API-Key", 
          "description": "API key for authentication",
          "isRequired": true,
          "isSecret": true
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Server with Custom Installation Path

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

Describes an MCP server that does not follow standard packaging conventions and may be embedded within applications. It uses the `website_url` field to provide users with documentation on custom installation procedures.

```APIDOC
## Server with Custom Installation Path

### Description
This configuration is for MCP servers that have custom installation paths or are embedded within applications without using standard packages. The `website_url` field directs users to specific setup documentation.

### Method
N/A (This is a configuration definition, not an API endpoint)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "io.modelcontextprotocol.anonymous/embedded-mcp",
  "description": "MCP server embedded in a Desktop app",
  "status": "active",
  "website_url": "https://anonymous.modelcontextprotocol.io/embedded-mcp-guide",
  "version": "0.1.0"
}
```
```

--------------------------------

### Alignment Example with Registry-Only Updates in JSON

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

An example demonstrating alignment where server metadata changes (e.g., prerelease tag) without a corresponding package update. It highlights that prerelease versions are published before the stable release.

```json
{
  "version": "1.2.3-1",
  "packages": [{
    "registry_type": "npm",
    "identifier": "@myorg/server",
    "version": "1.2.3"
  }]
}
```

--------------------------------

### Complex Docker Server Configuration Example

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

This JSON defines an MCP server packaged as a Docker image for database operations. It supports multiple database types and allows for complex configurations including runtime arguments, package arguments, and environment variables. This example showcases advanced customization options for Docker-based MCP servers.

```json
{
  "name": "io.github.example/database-manager",
  "description": "MCP server for database operations with support for multiple database types",
  "repository": {
    "url": "https://github.com/example/database-manager-mcp",
    "source": "github",
    "id": "ghi789jk-lmno-1234-pqrs-tuvwxyz56789"
  },
  "version": "3.1.0",
  "packages": [
    {
      "registry_type": "oci",
      "registry_base_url": "https://docker.io",
      "identifier": "example/database-manager-mcp",
      "version": "3.1.0",
      "transport": {
        "type": "stdio"
      },
      "runtime_arguments": [
        {
          "type": "named",
          "name": "--network",
          "value": "host",
          "description": "Use host network mode"
        },
        {
          "type": "named",
          "name": "-e",
          "value": "DB_TYPE={db_type}",
          "description": "Database type to connect to",
          "is_repeated": true,
          "variables": {
            "db_type": {
              "description": "Type of database",
              "choices": [
                "postgres",
                "mysql",
                "mongodb",
                "redis"
              ],
              "is_required": true
            }
          }
        }
      ],
      "package_arguments": [
        {
          "type": "named",
          "name": "--host",
          "description": "Database host",
          "default": "localhost",
          "is_required": true
        },
        {
          "type": "named",
          "name": "--port",
          "description": "Database port",
          "format": "number"
        },
        {
          "type": "positional",
          "value_hint": "database_name",
          "description": "Name of the database to connect to",
          "is_required": true
        }
      ],
      "environment_variables": [
        {
          "name": "DB_USERNAME",
          "description": "Database username",
          "is_required": true
        },
        {
          "name": "DB_PASSWORD",
          "description": "Database password",
          "is_required": true,
          "is_secret": true
        },
        {
          "name": "SSL_MODE",
          "description": "SSL connection mode",
          "default": "prefer",
          "choices": [
            "disable",
            "prefer",
            "require"
          ]
        }
      ]
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "docker-buildx",
      "version": "0.12.1",
      "build_info": {
        "docker_version": "24.0.7",
        "timestamp": "2023-12-08T14:30:00Z",
        "platform": "linux/amd64,linux/arm64",
        "registry": "docker.io",
        "image_digest": "sha256:1a2b3c4d5e6f7890"
      }
    }
  }
}
```

--------------------------------

### Multi-Package Versioning

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/explanations/versioning.md

This section covers scenarios with multiple packages, potentially having different versions. It details the JSON structure for such configurations and emphasizes using the server version to denote the overall release status.

```APIDOC
## Multi-Package Versioning

### Description
Handles versioning when a registry is associated with multiple packages, each potentially having a different version. The server version serves as the overall release indicator.

### Method
POST (Assumed, as this describes data structure)

### Endpoint
/modelcontextprotocol/registry (Assumed)

### Request Body
- **version** (string) - Required - The overall server version indicating the release status.
- **packages** (array) - Required - A list of packages associated with the registry.
  - **registryType** (string) - Required - The type of registry (e.g., 'npm', 'oci').
  - **identifier** (string) - Required - The package identifier.
  - **version** (string) - Required - The version of the package.

### Request Example
```json
{
  "version": "1.3.0",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@myorg/server",
      "version": "1.3.0"
    },
    {
      "registryType": "oci",
      "identifier": "myorg/server",
      "version": "1.2.5"
    }
  ]
}
```

### Response
#### Success Response (200)
Indicates successful processing of the multi-package registry update.

#### Response Example
(No example provided in source text)
```

--------------------------------

### Configure Server with Authentication Headers

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

Example server.json configuration for an MCP server that includes authentication headers for its remote connections. This example shows how to specify required API key headers for SSE connections, enhancing security.

```json
{
  "remotes": [
    {
      "type": "sse",
      "url": "https://mcp.yourcompany.com/sse",
      "headers": [
        {
          "name": "X-API-Key",
          "description": "API key for authentication",
          "is_required": true,
          "is_secret": true
        }
      ]
    }
  ]
}
```

--------------------------------

### GitHub Actions Workflow for MCP Server Publishing (YAML)

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/guides/publishing/github-actions.md

This YAML workflow automates the publishing of MCP servers to a registry. It includes steps for checking out code, setting up the environment, installing dependencies, running tests, building the package, publishing to a primary registry (like npm), and publishing to the MCP Registry using the MCP Publisher tool. It requires specific permissions for OIDC authentication and can be triggered by version tags.

```yaml
name: Publish to MCP Registry

on:
  push:
    tags: ["v*"]  # Triggers on version tags like v1.0.0

jobs:
  publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write  # Required for OIDC authentication
      contents: read

    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Setup Node.js  # Adjust for your language
        uses: actions/setup-node@v5
        with:
          node-version: "lts/*"

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm run test --if-present

      - name: Build package
        run: npm run build --if-present

      - name: Publish to npm
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

      - name: Install MCP Publisher
        run: |
          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.1.0/mcp-publisher_1.1.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher

      - name: Login to MCP Registry
        run: ./mcp-publisher login github-oidc

      - name: Publish to MCP Registry
        run: ./mcp-publisher publish
```

--------------------------------

### Authentication Methods

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/guides/publishing/publish-server.md

Guides users through the authentication process for publishing servers using either GitHub or DNS authentication.

```APIDOC
## Authentication Methods

### GitHub Authentication (for io.github.* namespaces)

```bash
mcp-publisher login github
```

### DNS Authentication (for custom domains)

1. Generate keypair:
   ```bash
   openssl genpkey -algorithm Ed25519 -out key.pem
   ```
2. Get public key for DNS record:
   ```bash
   echo "yourcompany.com. IN TXT \"v=MCPv1; k=ed25519; p=$(openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64)\""
   ```
3. Add the TXT record to your DNS, then login:
   ```bash
   mcp-publisher login dns --domain yourcompany.com --private-key $(openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n')
   ```
```

--------------------------------

### Set up PostgreSQL Docker Container for Testing

Source: https://github.com/modelcontextprotocol/registry/blob/main/scripts/mirror_data/README.md

This command starts a PostgreSQL Docker container named 'test-postgres' and maps port 5433 to the container's 5432. It sets the password to 'testpass' and the database name to 'registry_test'.

```bash
docker run -d --name test-postgres \
  -p 5433:5432 \
  -e POSTGRES_PASSWORD=testpass \
  -e POSTGRES_DB=registry_test \
  postgres:16
```

--------------------------------

### MCP Bundle (MCPB) Package Example

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/server-json/generic-server-json.md

An example of an MCP Bundle (MCPB) package hosted on GitHub Releases, including integrity verification via SHA-256 hash. This format is directly executable by MCP clients supporting MCPB.

```APIDOC
## MCP Bundle (MCPB) Package Example

### Description
This section provides an example of an MCP Bundle (MCPB) package. MCPB packages are designed for direct execution by MCP clients and can be hosted on platforms like GitHub Releases. This example demonstrates the structure, including the package name, description, repository information, version, and specific package details like registry type, URL, SHA-256 hash for integrity, and transport mechanism.

### Method
N/A (Configuration Schema)

### Endpoint
N/A (Configuration Schema)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A (This is a schema definition)

### Request Example
```json
{
  "name": "io.modelcontextprotocol/text-editor",
  "description": "MCP Bundle server for advanced text editing capabilities",
  "repository": {
    "url": "https://github.com/modelcontextprotocol/text-editor-mcpb",
    "source": "github"
  },
  "version": "1.0.2",
  "packages": [
    {
      "registryType": "mcpb",
      "registryBaseUrl": "https://github.com",
      "identifier": "https://github.com/modelcontextprotocol/text-editor-mcpb/releases/download/v1.0.2/text-editor.mcpb",
      "version": "1.0.2",
      "fileSha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce",
      "transport": {
        "type": "stdio"
      }
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "mcpb-publisher",
      "version": "1.0.0",
      "build_info": {
        "timestamp": "2023-12-02T09:15:00Z",
        "bundle_format": "mcpb-v1"
      }
    }
  }
}
```

### Response
N/A (This is a schema definition)

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Run Development Environment with Docker Compose

Source: https://github.com/modelcontextprotocol/registry/blob/main/README.md

Starts the full development environment for the MCP registry using Docker Compose. This includes the registry server, PostgreSQL database, and seed data. The database uses ephemeral storage and is reset on each restart. Configuration can be adjusted via environment variables specified in `.env.example`.

```bash
# Start full development environment
make dev-compose
```

--------------------------------

### MCP Bundle (MCPB) Package Example

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

Illustrates an MCP Bundle (MCPB) package hosted on GitHub Releases. It includes integrity verification via SHA-256 hash and is designed for direct download and execution by MCP clients.

```APIDOC
## MCP Bundle (MCPB) Package Example

### Description
This example demonstrates an MCP Bundle (MCPB) package, which is hosted on GitHub Releases. It features a SHA-256 hash for integrity verification and can be executed directly by MCP clients that support the MCPB format.

### Method
N/A (This is a configuration definition, not an API endpoint)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
```json
{
  "name": "io.modelcontextprotocol/text-editor",
  "description": "MCP Bundle server for advanced text editing capabilities",
  "repository": {
    "url": "https://github.com/modelcontextprotocol/text-editor-mcpb",
    "source": "github"
  },
  "version": "1.0.2",
  "packages": [
    {
      "registry_type": "mcpb",
      "registry_base_url": "https://github.com",
      "identifier": "https://github.com/modelcontextprotocol/text-editor-mcpb/releases/download/v1.0.2/text-editor.mcpb",
      "version": "1.0.2",
      "file_sha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce",
      "transport": {
        "type": "stdio"
      }
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "mcpb-publisher",
      "version": "1.0.0",
      "build_info": {
        "timestamp": "2023-12-02T09:15:00Z",
        "bundle_format": "mcpb-v1"
      }
    }
  }
}
```
```

--------------------------------

### Example MCP Publisher Token Storage Format

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/cli/commands.md

Illustrates the JSON structure used for storing authentication tokens locally in `~/.mcp_publisher_token`. Includes the token, registry URL, and expiration timestamp.

```json
{
  "token": "jwt-token-here",
  "registry_url": "https://registry.modelcontextprotocol.io",
  "expires_at": "2024-12-31T23:59:59Z"
}
```

--------------------------------

### Build and Use MCP Publisher CLI

Source: https://github.com/modelcontextprotocol/registry/blob/main/README.md

Builds the latest MCP publisher command-line interface (CLI) using `make publisher`. After building, the CLI is available in the `./bin/mcp-publisher` path and can be executed directly to publish MCP servers. More detailed usage instructions can be found in the publisher guide.

```bash
# Build the latest CLI
make publisher

# Use it!
./bin/mcp-publisher --help
```

--------------------------------

### MCP Registry API Server List Filtering Example

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/reference/api/official-registry-api.md

Demonstrates how to filter the server list using multiple query parameters for efficient discovery and synchronization. This example shows filtering by a search term, update timestamp, and version.

```http
GET /v0/servers?search=filesystem&updated_since=2025-08-01T00:00:00Z&version=latest
```

--------------------------------

### JSON: Example of Multi-Package Versioning

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

Demonstrates how to represent different versions of underlying packages within a single release. It specifies the overall release version and lists individual package identifiers and their respective versions, categorized by registry type.

```json
{
  "version": "1.3.0",
  "packages": [
    {
      "registry_type": "npm",
      "identifier": "@myorg/server",
      "version": "1.3.0"
    },
    {
      "registry_type": "oci",
      "identifier": "myorg/server",
      "version": "1.2.5"
    }
  ]
}
```

--------------------------------

### JSON Structure for Semantic Version

Source: https://github.com/modelcontextprotocol/registry/blob/main/docs/explanations/versioning.md

This JSON structure demonstrates the basic requirement for a server version, adhering to semantic versioning (MAJOR.MINOR.PATCH). It's a simple object with a 'version' string property.

```json
{
  "version": "1.2.3"
}
```

--------------------------------

### Configure Server with Multiple Transport Options

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

Example server.json demonstrating multiple transport options for an MCP server. This configuration includes both Server-Sent Events (SSE) and Streamable HTTP as connection methods, allowing clients to choose their preferred transport.

```json
{
  "remotes": [
    {
      "type": "sse",
      "url": "https://mcp.yourcompany.com/sse"
    },
    {
      "type": "streamable-http",
      "url": "https://mcp.yourcompany.com/http"
    }
  ]
}
```

--------------------------------

### NuGet Package Configuration Example

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

This JSON defines a NuGet package for an MCP server that generates random numbers and weather. It specifies the package details, repository information, and environment variables required for the server. The 'dnx' runtime hint indicates the tool used for execution.

```json
{
  "name": "io.github.joelverhagen/knapcode-samplemcpserver",
  "description": "Sample NuGet MCP server for a random number and random weather",
  "repository": {
    "url": "https://github.com/joelverhagen/Knapcode.SampleMcpServer",
    "source": "github",
    "id": "example-nuget-id-0000-1111-222222222222"
  },
  "version": "0.5.0",
  "packages": [
    {
      "registry_type": "nuget",
      "registry_base_url": "https://api.nuget.org",
      "identifier": "Knapcode.SampleMcpServer",
      "version": "0.5.0",
      "runtime_hint": "dnx",
      "transport": {
        "type": "stdio"
      },
      "environment_variables": [
        {
          "name": "WEATHER_CHOICES",
          "description": "Comma separated list of weather descriptions to randomly select.",
          "is_required": true,
          "is_secret": false
        }
      ]
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "dotnet-publisher",
      "version": "8.0.100",
      "build_info": {
        "dotnet_version": "8.0.0",
        "timestamp": "2023-12-10T12:15:00Z",
        "configuration": "Release",
        "target_framework": "net8.0",
        "build_number": "20231210.1"
      }
    }
  }
}
```

--------------------------------

### MCP Bundle (MCPB) Package Example (JSON)

Source: https://github.com/modelcontextprotocol/registry/blob/main/complete.md

This JSON defines an MCP Bundle (MCPB) package for text editing capabilities. It is hosted on GitHub Releases, includes a SHA-256 hash for integrity verification, and is designed for direct execution by MCP clients supporting the MCPB format.

```json
{
  "name": "io.modelcontextprotocol/text-editor",
  "description": "MCP Bundle server for advanced text editing capabilities",
  "repository": {
    "url": "https://github.com/modelcontextprotocol/text-editor-mcpb",
    "source": "github"
  },
  "version": "1.0.2",
  "packages": [
    {
      "registry_type": "mcpb",
      "registry_base_url": "https://github.com",
      "identifier": "https://github.com/modelcontextprotocol/text-editor-mcpb/releases/download/v1.0.2/text-editor.mcpb",
      "version": "1.0.2",
      "file_sha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce",
      "transport": {
        "type": "stdio"
      }
    }
  ],
  "_meta": {
    "io.modelcontextprotocol.registry/publisher-provided": {
      "tool": "mcpb-publisher",
      "version": "1.0.0",
      "build_info": {
        "timestamp": "2023-12-02T09:15:00Z",
        "bundle_format": "mcpb-v1"
      }
    }
  }
}
```