Add MCP Server Card (SEP-2127) types + handler

Introduce pkg/http/servercard: Go types for an MCP Server Card matching the
current v1 schema in modelcontextprotocol/experimental-ext-server-card, a
constructor for the GitHub MCP Server's card, and a public, no-auth HTTP
handler that serves it at the reserved /server-card location.

The card is remote-only and minimal: it advertises identity (name, title,
description, version), repository, websiteUrl, and a single streamable-http
remote, and deliberately omits tools/resources/prompts and installable
packages. Card identity fields are reused from the registry server.json so
both documents describe the same server.

Serving behavior follows the discovery spec: media type
application/mcp-server-card+json, Accept negotiation, the mandated four CORS
headers (Allow-Origin *, Allow-Methods GET, Allow-Headers Content-Type,
If-None-Match, Expose-Headers ETag), Cache-Control public max-age=3600, and a
strong SHA-256 ETag with If-None-Match/304 conditional handling. Vary: Accept
is set so shared caches key on the negotiated media type.

To support the multi-tenant hosted deployment, the handler exposes a
request-aware ServeCard helper and a Config.RemoteURLFunc hook so the remote
repository can derive a per-request remote URL while reusing identical
ETag/header logic. The card route is wired outside the shared MCP CORS
middleware so its preflight returns the card's CORS set, while unmatched paths
still receive MCP CORS.

supportedProtocolVersions, icons, and per-remote auth metadata are
intentionally omitted to keep the card minimal and accurate: the go-sdk does
not export negotiated protocol versions, and auth is advertised via OAuth
protected-resource-metadata discovery rather than duplicated on the card.

Refs github/copilot-mcp-core#1855, epic github/copilot-mcp-core#1853
Spec: modelcontextprotocol/experimental-ext-server-card

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4a9f522f-6942-4b77-98a4-b2d42f19625d

Author: SamMorrowDrums

pkg/http/server.go

@@ -18,6 +18,7 @@ import (
 	"github.com/github/github-mcp-server/pkg/github"
 	"github.com/github/github-mcp-server/pkg/http/middleware"
 	"github.com/github/github-mcp-server/pkg/http/oauth"
+	"github.com/github/github-mcp-server/pkg/http/servercard"
 	"github.com/github/github-mcp-server/pkg/inventory"
 	"github.com/github/github-mcp-server/pkg/lockdown"
 	"github.com/github/github-mcp-server/pkg/observability"
@@ -218,9 +219,14 @@ func RunHTTPServer(cfg ServerConfig) error {
 			handler.RegisterRoutes(r)
 		},
 		oauthHandler.RegisterRoutes,
+		// The Server Card is public, no-auth metadata that defines its own
+		// complete CORS contract, so it is registered outside the shared MCP
+		// CORS middleware (see newHTTPRouter).
+		servercard.NewHandler(servercard.Config{Version: cfg.Version}).RegisterRoutes,
 	)
 	logger.Info("MCP endpoints registered", "baseURL", cfg.BaseURL)
 	logger.Info("OAuth protected resource endpoints registered", "baseURL", cfg.BaseURL)
+	logger.Info("MCP Server Card endpoint registered", "path", servercard.Path)
 
 	addr := resolveListenAddress(cfg.ListenHost, cfg.Port)
 	httpSvr := http.Server{
@@ -253,12 +259,23 @@ func RunHTTPServer(cfg ServerConfig) error {
 	return nil
 }
 
-func newHTTPRouter(registerMCPRoutes, registerOAuthRoutes func(chi.Router)) chi.Router {
-	r := chi.NewRouter()
-	r.Use(middleware.SetCorsHeaders)
-	r.Group(registerMCPRoutes)
-	r.Group(registerOAuthRoutes)
-	return r
+func newHTTPRouter(registerMCPRoutes, registerOAuthRoutes, registerCardRoutes func(chi.Router)) chi.Router {
+	// MCP and OAuth routes share the MCP CORS middleware, which also decorates
+	// unmatched paths (404s) so browser clients always receive CORS headers.
+	inner := chi.NewRouter()
+	inner.Use(middleware.SetCorsHeaders)
+	inner.Group(registerMCPRoutes)
+	inner.Group(registerOAuthRoutes)
+
+	// The Server Card owns its own CORS contract (If-None-Match preflight,
+	// Expose-Headers: ETag), so it is registered on the bare root router,
+	// outside the shared MCP CORS middleware which short-circuits OPTIONS with a
+	// card-incompatible header set. Every other path falls through to the inner
+	// router; chi static-route precedence keeps /server-card ahead of it.
+	root := chi.NewRouter()
+	root.Group(registerCardRoutes)
+	root.Mount("/", inner)
+	return root
 }
 
 func newOAuthConfig(cfg ServerConfig) *oauth.Config {

pkg/http/server_test.go

@@ -15,6 +15,7 @@ import (
 	"github.com/github/github-mcp-server/pkg/github"
 	"github.com/github/github-mcp-server/pkg/http/middleware"
 	"github.com/github/github-mcp-server/pkg/http/oauth"
+	"github.com/github/github-mcp-server/pkg/http/servercard"
 	"github.com/github/github-mcp-server/pkg/inventory"
 	"github.com/github/github-mcp-server/pkg/utils"
 	"github.com/go-chi/chi/v5"
@@ -103,6 +104,7 @@ func TestHTTPRouterCORSContract(t *testing.T) {
 				http.Error(w, "metadata unavailable", http.StatusInternalServerError)
 			})
 		},
+		func(chi.Router) {},
 	)
 
 	tests := []struct {
@@ -190,6 +192,50 @@ func TestHTTPRouterCORSContract(t *testing.T) {
 	}
 }
 
+// TestHTTPRouterServerCardCORSIsolation verifies that the Server Card endpoint
+// is registered outside the shared MCP CORS middleware, so its OPTIONS preflight
+// returns the card's own CORS contract (which allows If-None-Match and exposes
+// ETag) rather than the MCP header set that short-circuits OPTIONS.
+func TestHTTPRouterServerCardCORSIsolation(t *testing.T) {
+	router := newHTTPRouter(
+		func(r chi.Router) {
+			r.Post("/", func(w http.ResponseWriter, _ *http.Request) {
+				w.WriteHeader(http.StatusNoContent)
+			})
+		},
+		func(chi.Router) {},
+		servercard.NewHandler(servercard.Config{Version: "test"}).RegisterRoutes,
+	)
+
+	// The card's OPTIONS preflight must expose only the card contract.
+	req := httptest.NewRequest(http.MethodOptions, servercard.Path, nil)
+	req.Header.Set("Origin", "https://confer.to")
+	rec := httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusOK, rec.Code)
+	assert.Equal(t, "*", rec.Header().Get("Access-Control-Allow-Origin"))
+	assert.Equal(t, "GET", rec.Header().Get("Access-Control-Allow-Methods"))
+	assert.Contains(t, rec.Header().Get("Access-Control-Allow-Headers"), "If-None-Match")
+	assert.Equal(t, "ETag", rec.Header().Get("Access-Control-Expose-Headers"))
+	assert.NotContains(t, rec.Header().Get("Access-Control-Expose-Headers"), "Mcp-Session-Id")
+
+	// A GET on the card still resolves to the card (not shadowed by the MCP
+	// catch-all) and carries the ETag.
+	req = httptest.NewRequest(http.MethodGet, servercard.Path, nil)
+	rec = httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+	assert.Equal(t, http.StatusOK, rec.Code)
+	assert.NotEmpty(t, rec.Header().Get("ETag"))
+
+	// The MCP route keeps its own CORS contract that exposes Mcp-Session-Id.
+	req = httptest.NewRequest(http.MethodOptions, "/", nil)
+	req.Header.Set("Origin", "https://confer.to")
+	rec = httptest.NewRecorder()
+	router.ServeHTTP(rec, req)
+	assert.Contains(t, rec.Header().Get("Access-Control-Expose-Headers"), "Mcp-Session-Id")
+}
+
 func TestOAuthChallengeMetadataRouteContracts(t *testing.T) {
 	const baseURL = "https://mcp.example.com"
 	oauthCfg := &oauth.Config{
@@ -222,6 +268,7 @@ func TestOAuthChallengeMetadataRouteContracts(t *testing.T) {
 			}
 		},
 		oauthHandler.RegisterRoutes,
+		func(chi.Router) {},
 	)
 
 	for _, path := range resourcePaths {

pkg/http/servercard/card.go

@@ -0,0 +1,147 @@
+// Package servercard provides the GitHub MCP Server's MCP Server Card
+// (SEP-2127) types and a public, no-auth HTTP handler that serves it.
+//
+// A Server Card is a static metadata document that describes a remote MCP
+// server — its identity, repository, and HTTP transport — so clients can
+// discover and connect to it before the protocol handshake. It is remote-only
+// and deliberately does NOT enumerate primitives (tools, resources, prompts)
+// or installable packages; those remain in the MCP Registry document
+// (server.json) and runtime listing.
+//
+// See:
+//   - https://github.com/modelcontextprotocol/experimental-ext-server-card
+//   - https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127
+package servercard
+
+import "net/http"
+
+const (
+	// SchemaURL is the v1 Server Card JSON Schema URI that emitted cards
+	// conform to. The schema is versioned by its `vN` path segment.
+	SchemaURL = "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json"
+
+	// MediaType is the media type used to serve and request a Server Card.
+	MediaType = "application/mcp-server-card+json"
+
+	// Path is the suffix, relative to a server's streamable-HTTP URL, at which
+	// MCP reserves the recommended Server Card location. A server hosted at
+	// `https://host/mcp` therefore serves its card at `https://host/mcp/server-card`.
+	Path = "/server-card"
+
+	// DefaultRemoteURL is the streamable-HTTP endpoint of the hosted GitHub MCP
+	// Server on github.com. The remote repository overrides this per environment.
+	DefaultRemoteURL = "https://api.githubcopilot.com/mcp/"
+)
+
+// Identity fields reused from the MCP Registry document (server.json) so the
+// Server Card and the registry entry describe the same server.
+const (
+	serverName        = "io.github.github/github-mcp-server"
+	serverTitle       = "GitHub"
+	serverDescription = "Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language."
+	repositoryURL     = "https://github.com/github/github-mcp-server"
+	repositorySource  = "github"
+	// repositoryID is the github.com repository ID for github/github-mcp-server.
+	// It is stable across renames but changes if the repository is recreated.
+	repositoryID = "942771284"
+)
+
+// ServerCard is a static metadata document describing a remote MCP server,
+// suitable for pre-connection discovery. It mirrors the ServerCard interface in
+// modelcontextprotocol/experimental-ext-server-card. Server Cards are
+// remote-only and never carry installable packages.
+type ServerCard struct {
+	// Schema is the Server Card JSON Schema URI this document conforms to.
+	Schema string `json:"$schema"`
+	// Name is the server name in reverse-DNS format with exactly one slash.
+	Name string `json:"name"`
+	// Version is the server version, equivalent to Implementation.version.
+	Version string `json:"version"`
+	// Description is a short, human-readable explanation of server functionality.
+	Description string `json:"description"`
+	// Title is an optional human-readable display name.
+	Title string `json:"title,omitempty"`
+	// WebsiteURL optionally links to the server's homepage or documentation.
+	WebsiteURL string `json:"websiteUrl,omitempty"`
+	// Repository optionally describes the server's source code for inspection.
+	Repository *Repository `json:"repository,omitempty"`
+	// Remotes lists the HTTP-based endpoints for connecting to the server.
+	Remotes []Remote `json:"remotes,omitempty"`
+}
+
+// Repository describes the MCP server's source code location.
+type Repository struct {
+	// URL is the repository URL for browsing source and cloning.
+	URL string `json:"url"`
+	// Source is the hosting service identifier (e.g. "github").
+	Source string `json:"source"`
+	// ID is the optional repository identifier owned by the hosting service.
+	ID string `json:"id,omitempty"`
+}
+
+// Remote describes a remote (HTTP-based) MCP server endpoint. Authentication is
+// intentionally not described here: the hosted server advertises its auth
+// requirements via OAuth protected-resource-metadata discovery, so duplicating
+// them on the card would risk drift and cannot capture every accepted mode.
+type Remote struct {
+	// Type is the transport type ("streamable-http" or "sse").
+	Type string `json:"type"`
+	// URL is the endpoint URL.
+	URL string `json:"url"`
+}
+
+// Config controls how the GitHub MCP Server card is built and served.
+type Config struct {
+	// Version is advertised as the card's version and SHOULD match the
+	// runtime serverInfo version. When empty, "0.0.0-dev" is used.
+	Version string
+
+	// RemoteURL is the absolute streamable-HTTP endpoint advertised in the
+	// card's single remote. When empty, DefaultRemoteURL is used. The remote
+	// repository supplies a per-environment URL here.
+	RemoteURL string
+
+	// RemoteURLFunc, when set, derives the streamable-HTTP remote URL from the
+	// incoming request, taking precedence over RemoteURL whenever it returns a
+	// non-empty value. This supports multi-tenant deployments (e.g. proxima)
+	// where the absolute URL varies per request (e.g. from X-Forwarded-Host).
+	//
+	// It is consumed by the Handler when serving a card; NewServerCard ignores
+	// it, since the card constructor is not request-aware.
+	RemoteURLFunc func(*http.Request) string
+}
+
+// NewServerCard builds the GitHub MCP Server's Server Card from cfg.
+func NewServerCard(cfg Config) *ServerCard {
+	version := cfg.Version
+	if version == "" {
+		version = "0.0.0-dev"
+	}
+
+	remoteURL := cfg.RemoteURL
+	if remoteURL == "" {
+		remoteURL = DefaultRemoteURL
+	}
+
+	// supportedProtocolVersions is intentionally omitted: the go-sdk does not
+	// export the list of versions it negotiates, so we cannot advertise it
+	// accurately from the runtime. Omitting it is preferable to publishing a
+	// hand-maintained list that could drift from what the server actually
+	// serves.
+	return &ServerCard{
+		Schema:      SchemaURL,
+		Name:        serverName,
+		Version:     version,
+		Description: serverDescription,
+		Title:       serverTitle,
+		WebsiteURL:  repositoryURL,
+		Repository: &Repository{
+			URL:    repositoryURL,
+			Source: repositorySource,
+			ID:     repositoryID,
+		},
+		Remotes: []Remote{
+			{Type: "streamable-http", URL: remoteURL},
+		},
+	}
+}

pkg/http/servercard/card_test.go

@@ -0,0 +1,96 @@
+package servercard
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// assertCardContract checks the required Server Card fields defined by the
+// experimental-ext-server-card v1 schema, plus the remote-only invariant. It is
+// a focused stand-in for full JSON-Schema validation: the card is small and its
+// shape is stable, so asserting the contract's required fields keeps the tests
+// self-contained without vendoring the upstream schema.
+func assertCardContract(t *testing.T, card *ServerCard) {
+	t.Helper()
+
+	raw, err := json.Marshal(card)
+	require.NoError(t, err)
+
+	var fields map[string]json.RawMessage
+	require.NoError(t, json.Unmarshal(raw, &fields))
+
+	// Required by the schema: $schema, name, version, description.
+	assert.Equal(t, SchemaURL, card.Schema)
+	assert.NotEmpty(t, card.Name)
+	assert.NotEmpty(t, card.Version)
+	require.NotEmpty(t, card.Description)
+	assert.LessOrEqual(t, len(card.Description), 100, "description must respect the schema maxLength")
+	for _, key := range []string{"$schema", "name", "version", "description"} {
+		assert.Contains(t, fields, key, "required field %q must be serialized", key)
+	}
+
+	// Remote-only: a Server Card never enumerates installable packages — those
+	// stay in the registry server.json.
+	assert.NotContains(t, fields, "packages", "Server Card must be remote-only and omit packages")
+	require.Len(t, card.Remotes, 1)
+	assert.Equal(t, "streamable-http", card.Remotes[0].Type)
+}
+
+func TestNewServerCard(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name              string
+		cfg               Config
+		expectedVersion   string
+		expectedRemoteURL string
+	}{
+		{
+			name:              "defaults",
+			cfg:               Config{},
+			expectedVersion:   "0.0.0-dev",
+			expectedRemoteURL: DefaultRemoteURL,
+		},
+		{
+			name:              "explicit version",
+			cfg:               Config{Version: "1.2.3"},
+			expectedVersion:   "1.2.3",
+			expectedRemoteURL: DefaultRemoteURL,
+		},
+		{
+			name:              "per-environment remote URL",
+			cfg:               Config{Version: "1.2.3", RemoteURL: "https://api.example.test/mcp/"},
+			expectedVersion:   "1.2.3",
+			expectedRemoteURL: "https://api.example.test/mcp/",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			card := NewServerCard(tc.cfg)
+
+			// Identity is reused from the registry document (server.json) and
+			// is locked: the AI Catalog derives its urn:air: id from the name.
+			assert.Equal(t, "io.github.github/github-mcp-server", card.Name)
+			assert.Equal(t, "GitHub", card.Title)
+			assert.True(t, strings.HasPrefix(card.Description, "Connect AI assistants to GitHub"))
+			assert.Equal(t, tc.expectedVersion, card.Version)
+			assert.Equal(t, "https://github.com/github/github-mcp-server", card.WebsiteURL)
+
+			require.NotNil(t, card.Repository)
+			assert.Equal(t, "https://github.com/github/github-mcp-server", card.Repository.URL)
+			assert.Equal(t, "github", card.Repository.Source)
+			assert.Equal(t, "942771284", card.Repository.ID)
+
+			assert.Equal(t, tc.expectedRemoteURL, card.Remotes[0].URL)
+
+			assertCardContract(t, card)
+		})
+	}
+}