From bec92b848ea19e28fda625412c977164d781985c Mon Sep 17 00:00:00 2001
From: Radoslav Dimitrov <radoslav@stacklok.com>
Date: Fri, 12 Sep 2025 13:01:25 +0300
Subject: [PATCH] Update the docs with info for remote MCP servers (#444)

<!-- Provide a brief summary of your changes -->

## Motivation and Context
<!-- Why is this change needed? What problem does it solve? -->
The following PR updates the publishing docs with information about
remote MCP servers.

Motivated by
https://github.com/modelcontextprotocol/registry/discussions/438
## How Has This Been Tested?
<!-- Have you tested this in a real application? Which scenarios were
tested? -->

## Breaking Changes
<!-- Will users need to update their code or configurations? -->
No
## Types of changes
<!-- What types of changes does your code introduce? Put an `x` in all
the boxes that apply: -->
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update

## Checklist
<!-- Go over all the following points, and put an `x` in all the boxes
that apply. -->
- [ ] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [ ] My code follows the repository's style guidelines
- [ ] New and existing tests pass locally
- [ ] I have added appropriate error handling
- [ ] I have added or updated documentation as needed

## Additional context
<!-- Add any other context, implementation notes, or design decisions
-->

---------

Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com>
---
 docs/guides/publishing/publish-server.md | 99 +++++++++++++++++++++++-
 1 file changed, 96 insertions(+), 3 deletions(-)

diff --git a/docs/guides/publishing/publish-server.md b/docs/guides/publishing/publish-server.md
index 615863a..69bd6d2 100644
--- a/docs/guides/publishing/publish-server.md
+++ b/docs/guides/publishing/publish-server.md
@@ -19,7 +19,16 @@ By the end of this tutorial, you'll have:
 ## Prerequisites
 
 - An MCP server you've already built ([follow this guide if you don't have one already](https://modelcontextprotocol.io/quickstart/server))
-- Your server published to a package registry (npm, PyPI, Docker Hub, etc.)
+
+## Deployment Options
+
+You can make your MCP server available in multiple ways:
+
+- **📦 Package deployment**: Published to registries (npm, PyPI, Docker Hub, etc.) and run locally by clients
+- **🌐 Remote deployment**: Hosted as a web service that clients connect to directly  
+- **🔄 Hybrid deployment**: Offer both package and remote options for maximum flexibility
+
+Learn more about [MCP server architecture](https://modelcontextprotocol.io/docs/concepts/servers) in the official docs.
 
 ## Step 1: Install the Publisher CLI
 
@@ -108,9 +117,13 @@ The `name` field determines authentication requirements:
 - **`io.github.yourname/*`** - Requires GitHub authentication
 - **`com.yourcompany/*`** - Requires DNS or HTTP domain verification
 
-### Add Package Validation
+### Configure Deployment Methods
 
-Your package must include validation metadata to prove ownership.
+Configure your server to support packages, remotes, or both:
+
+#### Package Deployment
+
+Add package validation metadata to prove ownership of your packages.
 
 
 <details>
@@ -289,6 +302,85 @@ The official MCP registry currently only supports artifacts hosted on GitHub or
 
 </details>
 
+#### Remote Deployment
+
+Add the `remotes` field to your `server.json` (can coexist with `packages`):
+
+<details>
+<summary><strong>🌐 Remote Server Configuration</strong></summary>
+
+### Requirements
+
+- **Service endpoint**: Your MCP server must be accessible at the specified URL
+- **Transport protocol**: Choose from `sse` (Server-Sent Events) or `streamable-http`
+- **URL validation**: For domain namespaces only (see URL requirements below)
+
+### Example server.json
+
+```json
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/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
+
+You can offer multiple connection methods:
+
+```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 (but you must authenticate via GitHub)
+
+### Authentication Headers (Optional)
+
+Configure headers that clients should send when connecting:
+
+```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
+        }
+      ]
+    }
+  ]
+}
+```
+
+</details>
+
 ## Step 4: Authenticate
 
 Choose your authentication method based on your namespace:
@@ -357,6 +449,7 @@ See these real-world examples of published servers:
 - **Update your server**: Publish new versions with updated server.json files
 - **Set up CI/CD**: Automate publishing with [GitHub Actions](github-actions.md)
 - **Learn more**: Understand [server.json format](../../reference/server-json/generic-server-json.md) in depth
+- **More examples**: See [remote server configurations](../../reference/server-json/generic-server-json.md#remote-server-example) and [hybrid deployments](../../reference/server-json/generic-server-json.md#server-with-remote-and-package-options) in the schema documentation
 
 ## What You've Accomplished