Add optional tool metadata to Server Card for offline discovery

[vyshnavigadamsetti]

One thing we keep running into with the current spec direction: without tool definitions in the card, the card doesn't really tell you what a server does.

The spec defers primitives because servers are dynamic, but there's a whole class of consumers that will never connect to a live MCP server like registries, developer portals, agent orchestrators planning tool routing. For them the card ends up like an API catalog that lists URLs but no operations.

The OpenAPI parallel feels apt here: static documentation of what a server supports, used for discovery not execution. That model works well in practice and I think the same approach can work for MCP tools.

The fix seems straightforward: add optional tools, resources, and prompts arrays using the existing MCP types. Dynamic servers just don't set them. Clients still use tools/list at runtime as the source of truth. The static list is for discovery, not execution.

We built an open-source renderer that already visualizes static tool definitions from card JSON and it works really well in practice. Happy to demo if helpful.

Related: SEP-2127 comment

[S-Reagan]

Really like this direction, and the OpenAPI-for-discovery framing makes sense to me. The optional + opt-out + "tools/list stays the source of truth" model is exactly right, so no concerns there.

The one thing I'd add comes from the gateway/aggregator side, because "dynamic servers just don't set them" isn't quite cost-free for us. We run a gateway in front of ~1,100 servers where the tool list is per-caller: it shifts with the user's RBAC scope, per-integration credential state, usage-based discovery, and tool-scanning, so we genuinely can't publish an honest static list. That part's fine. But if static servers populate rich tool arrays and dynamic ones just leave the field empty, then in the exact consumers this is for (registries, portals, orchestrators) the dynamic servers render as empty or featureless next to the static ones. "Absent" is ambiguous too: a consumer can't tell "no tools" from "didn't bother" from "dynamic."

So my one real ask is to make dynamic a first-class value for these fields, not just "set it or don't." Let a server positively say "I have tools, they're dynamic, fetch them at runtime" as a distinct signal from an empty list and from a static list. Then a registry or orchestrator has something accurate to show and route on, and dynamic servers aren't quietly penalized for being honest. I think this came up as a sticking point on the original SEP, so not a new idea, just a vote for it.

One related thing worth keeping in mind: for a gateway especially, a static tool list at a .well-known endpoint is also a public recon surface, and tool descriptions are exactly the prompt-injection/poisoning vector. So even if the field existed we wouldn't populate it, which is another reason the dynamic marker matters: it lets us signal capability without publishing the actual surface.

Happy to be a dynamic/gateway test case if it helps figure out what these servers should expose instead. My guess is capability booleans, maybe counts or categories, and a pointer to live listing, rather than full tool defs. Either way, glad to weigh in early.

[vyshnavigadamsetti]

@pavelkornev @maiargu