Recommend changes to server.json schema

[BobDickinson]

Pre-submission Checklist

• I have verified this would not be more appropriate as a feature request in a specific repository
• I have searched existing discussions to avoid duplicates

Your Idea

I am new here, but that being said, I've spent a significant amount of time reviewing the server.json schema with a focus on package and remote configuration elements (how they drive UX rendering and how that UX then produces a server config usable by an MCP client).

I'll start by saying that the configuration support provided by the schema is extremely comprehensive and supports producing high quality dynamically rendered UX driven by the server object. I've worked with these kinds of systems before and built my own, and I think the version here is almost perfect.

That being said, after implementing my own dynamic server configuration UX and hand-reviewing around a hundred currently published servers, I have seen some issues that I think can be addressed by some small changes to the schema as outlined below.

I'm happy to open Issues/PRs and make these changes, but I didn't want to jump in without running this by the maintainers in case I'm missing some context.

Note: When I refer to "the corpus" below I am referring the the set of servers currently published in the official registry. I have many examples from the corpus to support the below claims, but didn't want to list them publicly (it didn't seem cool to call them out, certainly not before adjudicating on the recommendations).

NamedArgument description

registry/docs/reference/server-json/server.schema.json

Line 283 in 76365a6

"description": "A command-line `--flag={value}`.",

I think the intent of this is actualy "--flag {value}". It is a common pattern in MCP servers to use named arguments where the argument name is itself an argument with the value following is another argument. The NamedArgument construct gives us a way to have a single configuration element that produces both arguments, but is easily managed as one element in rendered configuration UX. There would be no good/easy way to do this without the NamedArgument construct.

Consider the very first server config referenced in the MCP docs: https://modelcontextprotocol.io/docs/develop/build-server

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",
        "run",
        "weather.py"
      ]
    }
  }
}

I have spot checked a dozen NamedArgument instances in the corpus and all of them assume the above handling of the named arguments.

If you needed the "--flag={value}" argument form (maybe for container args), the more appropriate config would be a positional arg with a variable (since it only creates a single output argument - from the perspective of the MCP config it is a single argument where the name happens to be included in the argument).

Recommendation: Literally just remove the "=" from the description

Input properties value description

registry/docs/reference/server-json/server.schema.json

Line 197 in 76365a6

"description": "The default value for the input. If this is not set, the user may be prompted to provide a value. If a value is set, it should not be configurable by end users.\n\nIdentifiers wrapped in `{curly_braces}` will be replaced with the corresponding properties from the input `variables` map. If an identifier in braces is not found in `variables`, or if `variables` is not provided, the `{curly_braces}` substring should remain unchanged.\n"

I think the first instance of the word "default" in the description is incorrect and should be removed. The value is not a default value, it is the value, full stop (as implied in the text that follows, if value is provided, the user will not be prompted for a value).

There are four publishers representing dozens of servers in the corpus using value as if it were default (making it impossible to properly configure their servers via a schema-compliant UX), and fixing this language might help with that in the future.

Recommendation: Remove the word "default" at the beginning of the description so it starts "The value for the input".

Value hint

registry/docs/reference/server-json/server.schema.json

Lines 256 to 260 in 76365a6

	"valueHint": {
	"type": "string",
	"description": "An identifier-like hint for the value. This is not part of the command line, but can be used by client configuration and to provide hints to users.",
	"example": "file_path"
	},

I was initially confused by the intent of valueHint (I assumed because of the term "hint" and the text "can be used by client configuration and to provide hints to users" that this was intended to be a placeholder type of value - a hint to that shows the input format, sample value, etc).

I think a slightly updated description would have saved me some confusion, perhaps:

An identifier for the positional argument. It is not part of the command line. It may be used by client configuration as a label identifying the argument. It is also used to identify the value in transport URL variable substitution.

Also, the schema requires at least one of value or valueHint. I was originally not a fan of that constraint (for a positional arg with no valueHint in my UX I would show the description and just "arg" as the label which seemed fine), but given that all current servers comply with this constraint, and that description is optional, I like the idea of the UX being able to rely on either an identifier or a value for a positional arg. So I've talked myself out of advocating to remove this constraint.

Recommendation: UpdatevalueHint description to make it more clear

Placeholder

I originally thought valueHint was supposed to be a UX placeholder and implemented it in my UX as such. Now that I understand that that's not what it is, I'd like to advocate that we add a placeholder attribute to the Input element.

A "placeholder" in UX is typically implemented as a value that shows up in an empty input control and disappears as soon as the user enters data. Its purpose is to describe the expected input format or provide an example.

I think this is a very useful concept for implementing high quality UX and I would argue that it belongs on every Input element (optionally). In the corpus I have seen many examples where publishers incorrectly use default where placeholder would be more appropriate - where the provided default is not a valid value, but just some instructive hint (so the user must edit or remove the default values to arrive at a valid configuration, even if the elements are not required and not used in the configuration).

Recommendation: Add placeholder as optional attribute on Input element

Scope

• Protocol Specification
• SDK Features
• Documentation
• Developer Experience
• Other

[BobDickinson]

I've also applied schema validation to all published servers that have the current schema (just to assess how well the published servers comply and if that might indicate something we need to look at in the schema).

I generated this PR to address SSE servers with {tokens} that were failing (I assume this was a bug since the streamable transports didn't have the uri format constraint that broke the SSE transports): #576

After that, we have:

• 535 servers pass the schema validation (yay!)
• 37 servers not validated because they use an older schema (fine)
• 86 servers failed the registry/url format (I think in all cases because the uri was an empty string)
• 5 servers failed because they specify a version of "latest" which is specifically disallowed in the schema
• 1 server failed with an invalid name (extra path segment)
• 1 server failed because it used an invalid argument format of "integer" (presumably intended "number")
• 1 server failed because status was missing

I don't know why we have all the repository objects with empty strings (esp given that repository isn't required). Is there some publishing script or tool introducing this?

I was coming at this from the angle of can we get to the point where we actually apply the server schema on POST /v0/publish to get better compliance (potentially in addition to the ad hoc validation being done in code now).

I don't really see any area where the schema is being unreasonably strict with respect to the actual published server content (maybe because the ad-hoc validation is catching stuff). The only thing that might prevent me from recommending we apply the schema validation on publish is this empty repository/uri string issue, just because there are so many of them.

[BobDickinson]

Created PR with these recommended changes: #601

[BobDickinson]

PR Merged.