From 843783ac18ad4e39c27e21e15b4789ba03a96800 Mon Sep 17 00:00:00 2001
From: adam jones <adamj+git@anthropic.com>
Date: Fri, 3 Oct 2025 17:34:20 +0100
Subject: [PATCH] docs: make streamable-http the primary transport in examples
 (#602)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary
Changes `streamable-http` to be the recommended and primary transport
type in documentation examples, while keeping SSE as a secondary option
during the preview period.

## Changes
- ✅ Update all primary remote server examples to use `streamable-http`
- ✅ Reorder multi-transport examples to show `streamable-http` first
- ✅ Add note that SSE is deprecated but still supported during preview
- ✅ Update transport protocol requirements text to indicate
`streamable-http` (recommended) and `sse` (deprecated)

## Context
As noted in issue #487, the docs were using SSE as the primary example
despite it being deprecated in the MCP specification (2025-06-18) in
favor of streamable HTTP. This PR aligns the documentation with the spec
while maintaining backward compatibility information for the preview
period.

Per maintainer feedback on the issue:
- SSE is still supported during the preview phase
- Eventually SSE support will be removed
- The community would benefit from consistent messaging about the
preferred transport

## Files Changed
- `docs/guides/publishing/publish-server.md` - Main publishing guide
- `docs/reference/server-json/generic-server-json.md` - Reference
documentation with examples

## Approach
This takes a balanced approach:
- Makes streamable-http the clear primary/recommended option
- Keeps SSE documented as supported during preview (not hidden)
- Adds explicit note about deprecation status
- Minimal changes, focused on examples and ordering

Fixes #487

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>
---
 docs/guides/publishing/publish-server.md      | 20 +++++++++----------
 .../server-json/generic-server-json.md        | 12 +++++------
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/docs/guides/publishing/publish-server.md b/docs/guides/publishing/publish-server.md
index 67e288d..c4f7c4f 100644
--- a/docs/guides/publishing/publish-server.md
+++ b/docs/guides/publishing/publish-server.md
@@ -371,7 +371,7 @@ Add the `remotes` field to your `server.json` (can coexist with `packages`):
 ### Requirements
 
 - **Service endpoint**: Your MCP server must be accessible at the specified URL
-- **Transport protocol**: Choose from `sse` (Server-Sent Events) or `streamable-http`
+- **Transport protocol**: Choose from `streamable-http` (recommended) or `sse` (deprecated)
 - **URL validation**: For domain namespaces only (see URL requirements below)
 
 ### Example server.json
@@ -384,8 +384,8 @@ Add the `remotes` field to your `server.json` (can coexist with `packages`):
   "version": "2.0.0",
   "remotes": [
     {
-      "type": "sse",
-      "url": "https://mcp.yourcompany.com/sse"
+      "type": "streamable-http",
+      "url": "https://mcp.yourcompany.com/http"
     }
   ]
 }
@@ -399,12 +399,12 @@ You can offer multiple connection methods:
 {
   "remotes": [
     {
-      "type": "sse",
-      "url": "https://mcp.yourcompany.com/sse"
+      "type": "streamable-http",
+      "url": "https://mcp.yourcompany.com/http"
     },
     {
-      "type": "streamable-http", 
-      "url": "https://mcp.yourcompany.com/http"
+      "type": "sse",
+      "url": "https://mcp.yourcompany.com/sse"
     }
   ]
 }
@@ -423,11 +423,11 @@ Configure headers that clients should send when connecting:
 {
   "remotes": [
     {
-      "type": "sse",
-      "url": "https://mcp.yourcompany.com/sse",
+      "type": "streamable-http",
+      "url": "https://mcp.yourcompany.com/http",
       "headers": [
         {
-          "name": "X-API-Key", 
+          "name": "X-API-Key",
           "description": "API key for authentication",
           "isRequired": true,
           "isSecret": true
diff --git a/docs/reference/server-json/generic-server-json.md b/docs/reference/server-json/generic-server-json.md
index d5e2609..549ce79 100644
--- a/docs/reference/server-json/generic-server-json.md
+++ b/docs/reference/server-json/generic-server-json.md
@@ -260,8 +260,8 @@ This will essentially instruct the MCP client to execute `dnx Knapcode.SampleMcp
   "version": "2.0.0",
   "remotes": [
     {
-      "type": "sse",
-      "url": "http://mcp-fs.anonymous.modelcontextprotocol.io/sse"
+      "type": "streamable-http",
+      "url": "http://mcp-fs.anonymous.modelcontextprotocol.io/http"
     }
   ],
   "_meta": {
@@ -531,8 +531,8 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6.
   ],
   "remotes": [
     {
-      "type": "sse",
-      "url": "https://mcp.anonymous.modelcontextprotocol.io/sse",
+      "type": "streamable-http",
+      "url": "https://mcp.anonymous.modelcontextprotocol.io/http",
       "headers": [
         {
           "name": "X-API-Key",
@@ -553,8 +553,8 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6.
       ]
     },
     {
-      "type": "streamable-http",
-      "url": "https://mcp.anonymous.modelcontextprotocol.io/http"
+      "type": "sse",
+      "url": "https://mcp.anonymous.modelcontextprotocol.io/sse"
     }
   ],
   "_meta": {