fix(mcpserver): advertise capabilities only for registered primitives

[Zelys-DFKH]

Summary

• MCPServer.__init__ unconditionally passes non-None list handlers to
  the lowlevel Server, causing get_capabilities() to always advertise
  tools, resources, and prompts, even when none are registered.
• Adds an optional capability_filter parameter to the lowlevel Server
  that post-processes the computed ServerCapabilities.
• MCPServer passes a filter that suppresses each entry when the
  corresponding manager is empty at capability-computation time.

Motivation and Context

Per the MCP schema spec and lifecycle docs, a ServerCapabilities entry should appear only when the server actually offers that primitive. Currently, an empty MCPServer advertises all three, and a server with only one tool still advertises resources and prompts it doesn't have.

The filter runs when create_initialization_options() is called at the start of run(), after all @mcp.tool() / @mcp.resource() / @mcp.prompt() decorators have been applied. Every transport path (stdio, SSE, streamable HTTP) calls server.create_initialization_options() → get_capabilities(), so the filter applies without any per-transport changes.

How Has This Been Tested?

Six new tests in tests/server/mcpserver/test_server.py cover: empty server, tool-only, resource-only, resource-template-only, prompt-only, and all-registered cases.

uv run --frozen pytest tests/server/mcpserver/test_server.py -v

Full suite: ./scripts/test — 100% branch coverage.

Breaking Changes

None. Servers that previously over-advertised will now send correct capability sets.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Closes #2473

[Zelys-DFKH]

You're right, and thanks for laying it out so clearly.

The MUST prose settles it. tools.mdx 38, resources.mdx 32 and prompts.mdx 30 all tie the requirement to whether the server supports the primitive, not to how many it holds. I leaned on the schema.ts field comment ("offers any tools to call") and treated it as the whole story.

And I half-saw this at the time, then talked myself out of it. In #2473 I waved off post-run() additions with "post-handshake capability changes aren't supported by the spec regardless", which conflates two things. The capability set is fixed at handshake; the list isn't, and listChanged exists precisely so it can change. My filter switches that off. It only bites a server starting with zero of a primitive, so tutorial003 survives, but that's a narrower regression rather than none.

The two artifacts genuinely disagree, so I'd rather a maintainer called it. schema.ts says "offers any", the prose says "supports". If the prose governs, the fix for #2473 isn't a cardinality filter at all. If the filter stays, it should be opt-in instead of wired unconditionally.

I'll rework it whichever way it lands. Needs a rebase regardless, so I'll wait on the shape.

[maxisbey]

Thanks for the PR, and sorry it sat here without a proper review.

We're closing most of the open PR backlog. v2 is out and changed a lot of the SDK, so many older PRs no longer apply as written, and we're a small team that realistically doesn't have the capacity to work through the rest.

If this still matters to you on v2, the most useful thing you can do is open an issue (or comment on the existing one) with your use case and a repro. Hearing why it matters to you is what we use to decide what to prioritise.

_{AI Disclaimer}