docs: make streamable-http the primary transport in examples (#602)

## 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>
This commit is contained in:
adam jones 2025-10-03 17:34:20 +01:00 • committed by GitHub
commit 843783ac18
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 16 additions and 16 deletions

View file

@ -371,7 +371,7 @@ Add the `remotes` field to your `server.json` (can coexist with `packages`):
### Requirements ### Requirements
- **Service endpoint**: Your MCP server must be accessible at the specified URL - **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) - **URL validation**: For domain namespaces only (see URL requirements below)
### Example server.json ### Example server.json
@ -384,8 +384,8 @@ Add the `remotes` field to your `server.json` (can coexist with `packages`):
"version": "2.0.0", "version": "2.0.0",
"remotes": [ "remotes": [
{ {
"type": "sse", "type": "streamable-http",
"url": "https://mcp.yourcompany.com/sse" "url": "https://mcp.yourcompany.com/http"
} }
] ]
} }
@ -398,13 +398,13 @@ You can offer multiple connection methods:
```json ```json
{ {
"remotes": [ "remotes": [
{
"type": "sse",
"url": "https://mcp.yourcompany.com/sse"
},
{ {
"type": "streamable-http", "type": "streamable-http",
"url": "https://mcp.yourcompany.com/http" "url": "https://mcp.yourcompany.com/http"
},
{
"type": "sse",
"url": "https://mcp.yourcompany.com/sse"
} }
] ]
} }
@ -423,8 +423,8 @@ Configure headers that clients should send when connecting:
{ {
"remotes": [ "remotes": [
{ {
"type": "sse", "type": "streamable-http",
"url": "https://mcp.yourcompany.com/sse", "url": "https://mcp.yourcompany.com/http",
"headers": [ "headers": [
{ {
"name": "X-API-Key", "name": "X-API-Key",

View file

@ -260,8 +260,8 @@ This will essentially instruct the MCP client to execute `dnx Knapcode.SampleMcp
"version": "2.0.0", "version": "2.0.0",
"remotes": [ "remotes": [
{ {
"type": "sse", "type": "streamable-http",
"url": "http://mcp-fs.anonymous.modelcontextprotocol.io/sse" "url": "http://mcp-fs.anonymous.modelcontextprotocol.io/http"
} }
], ],
"_meta": { "_meta": {
@ -531,8 +531,8 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6.
], ],
"remotes": [ "remotes": [
{ {
"type": "sse", "type": "streamable-http",
"url": "https://mcp.anonymous.modelcontextprotocol.io/sse", "url": "https://mcp.anonymous.modelcontextprotocol.io/http",
"headers": [ "headers": [
{ {
"name": "X-API-Key", "name": "X-API-Key",
@ -553,8 +553,8 @@ The `dnx` tool ships with the .NET 10 SDK, starting with Preview 6.
] ]
}, },
{ {
"type": "streamable-http", "type": "sse",
"url": "https://mcp.anonymous.modelcontextprotocol.io/http" "url": "https://mcp.anonymous.modelcontextprotocol.io/sse"
} }
], ],
"_meta": { "_meta": {