Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/reference/api/openapi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -1005,6 +1005,11 @@ components:
type: array
items:
$ref: '#/components/schemas/RemoteTransport'
serverCard:
type: string
format: uri
description: "Optional URL of the server's MCP Server Card (SEP-2127). When present, clients SHOULD fetch this document to verify that the endpoint identifies itself as this server name, instead of inferring the card location from the remote URL."
example: "https://example.com/mcp/server-card"
_meta:
type: object
description: "Extension metadata using reverse DNS namespacing for vendor-specific data"
Expand Down
20 changes: 20 additions & 0 deletions docs/reference/server-json/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,26 @@ Changes to the server.json schema and format.

This section tracks changes that are in development and not yet released. The draft schema is available at [`server.schema.json`](./draft/server.schema.json) in this repository.

### Added

#### Optional `serverCard` URL

`server.json` can now point at the server's MCP Server Card (SEP-2127) explicitly:

```json
{
"name": "com.example/weather",
"remotes": [{ "type": "streamable-http", "url": "https://api.example.com/mcp" }],
"serverCard": "https://api.example.com/mcp/server-card"
}
```

Today a client that wants to check whether an endpoint identifies as the server it
claims must guess `<remote-url>/server-card`. That guess is ambiguous in two ways:
a card may be published elsewhere, and on shared hosting `<endpoint>/server-card`
can be the platform's card rather than the tenant's. An explicit URL resolves both.
The field is optional and no existing entry changes meaning.

### Changed

#### Transport URL Pattern Now Accepts Template Variables
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/server-json/draft/server.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -469,6 +469,12 @@
"$ref": "#/definitions/Repository",
"description": "Optional repository metadata for the MCP server source code. Recommended for transparency and security inspection."
},
"serverCard": {
"description": "Optional URL of the server's MCP Server Card (SEP-2127). When present, clients SHOULD fetch this document to verify that the endpoint identifies itself as this server name, instead of inferring the card location from the remote URL.",
"example": "https://example.com/mcp/server-card",
"format": "uri",
"type": "string"
},
"title": {
"description": "Optional human-readable title or display name for the MCP server. MCP subregistries or clients MAY choose to use this for display purposes.",
"example": "Weather API",
Expand Down
51 changes: 51 additions & 0 deletions internal/validators/validators.go
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,10 @@ func ValidateServerJSON(serverJSON *apiv0.ServerJSON, opts ValidationOptions) *V
websiteResult := validateWebsiteURL(ctx.Field("websiteUrl"), serverJSON.WebsiteURL)
result.Merge(websiteResult)

// Validate server card URL if provided
serverCardResult := validateServerCardURL(ctx.Field("serverCard"), serverJSON.ServerCard)
result.Merge(serverCardResult)

// Validate title if provided
titleResult := validateTitle(ctx.Field("title"), serverJSON.Title)
result.Merge(titleResult)
Expand Down Expand Up @@ -236,6 +240,53 @@ func validateWebsiteURL(ctx *ValidationContext, websiteURL string) *ValidationRe
return result
}

// validateServerCardURL checks an optional MCP Server Card URL (SEP-2127).
// A card is only meaningful as a verification target if it is fetched over
// HTTPS, so unlike generic remote URLs this field rejects http.
func validateServerCardURL(ctx *ValidationContext, raw string) *ValidationResult {
result := &ValidationResult{Valid: true, Issues: []ValidationIssue{}}

// Skip validation if not provided (optional field)
if raw == "" {
return result
}

if !IsValidURL(raw) {
result.AddIssue(NewValidationIssue(
ValidationIssueTypeSemantic,
ctx.String(),
fmt.Sprintf("invalid serverCard URL: %s", raw),
ValidationIssueSeverityError,
"invalid-server-card-url",
))
return result
}

parsedURL, err := url.Parse(raw)
if err != nil || parsedURL.Scheme != SchemeHTTPS {
result.AddIssue(NewValidationIssue(
ValidationIssueTypeSemantic,
ctx.String(),
fmt.Sprintf("serverCard must use https scheme: %s", raw),
ValidationIssueSeverityError,
"server-card-invalid-scheme",
))
return result
}

if i := strings.IndexAny(raw, "\"'<> \t\n\r"); i >= 0 {
result.AddIssue(NewValidationIssue(
ValidationIssueTypeSemantic,
ctx.String(),
fmt.Sprintf("serverCard contains an invalid character %q at position %d: %s", raw[i], i, raw),
ValidationIssueSeverityError,
"server-card-invalid-characters",
))
}

return result
}

func validateTitle(ctx *ValidationContext, title string) *ValidationResult {
result := &ValidationResult{Valid: true, Issues: []ValidationIssue{}}

Expand Down
45 changes: 45 additions & 0 deletions internal/validators/validators_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -490,6 +490,51 @@ func TestValidate(t *testing.T) {
},
expectedError: "",
},
{
name: "server with valid serverCard",
serverDetail: apiv0.ServerJSON{
Schema: model.CurrentSchemaURL,
Name: "com.example/test-server",
Description: "A test server",
Repository: &model.Repository{
URL: "https://github.com/owner/repo",
Source: "github",
},
Version: "1.0.0",
ServerCard: "https://api.example.com/mcp/server-card",
},
expectedError: "",
},
{
name: "server with serverCard over http",
serverDetail: apiv0.ServerJSON{
Schema: model.CurrentSchemaURL,
Name: "com.example/test-server",
Description: "A test server",
Repository: &model.Repository{
URL: "https://github.com/owner/repo",
Source: "github",
},
Version: "1.0.0",
ServerCard: "http://api.example.com/mcp/server-card",
},
expectedError: "serverCard must use https scheme: http://api.example.com/mcp/server-card",
},
{
name: "server with invalid serverCard URL",
serverDetail: apiv0.ServerJSON{
Schema: model.CurrentSchemaURL,
Name: "com.example/test-server",
Description: "A test server",
Repository: &model.Repository{
URL: "https://github.com/owner/repo",
Source: "github",
},
Version: "1.0.0",
ServerCard: "not-a-url",
},
expectedError: "invalid serverCard URL: not-a-url",
},
{
name: "server with invalid websiteUrl - no scheme",
serverDetail: apiv0.ServerJSON{
Expand Down
1 change: 1 addition & 0 deletions pkg/api/v0/types.go
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,7 @@ type ServerJSON struct {
Icons []model.Icon `json:"icons,omitempty" doc:"Optional set of sized icons that the client can display in a user interface."`
Packages []model.Package `json:"packages,omitempty" doc:"Array of package configurations"`
Remotes []model.Transport `json:"remotes,omitempty" doc:"Array of remote configurations"`
ServerCard string `json:"serverCard,omitempty" format:"uri" doc:"Optional URL of the server's MCP Server Card (SEP-2127). Clients SHOULD fetch this to verify the endpoint identifies as this server name." example:"https://example.com/mcp/server-card"`
Meta *ServerMeta `json:"_meta,omitempty" doc:"Extension metadata using reverse DNS namespacing for vendor-specific data"`
}

Expand Down
Loading