Repository navigation
Add support for grouping tools in MCP Python SDK #829
Description
Is your feature request related to a problem? Please describe.
HI , I was creating a mcp server for superset and find the use of tool grouping.
right now, every tool registered via @mcp.tool() is listed flat, there’s no way to organize or surface related tools together in the SDK or in UIs. As the number of tools grows, it becomes hard to discover and manage them.
Describe the solution you'd like
Extend the @mcp.tool() decorator (and underlying registration) to accept an optional group parameter. Store this on each Tool instance and include it in the metadata returned by list_tools(). For example:
@mcp.tool(group="dashboard")
def get_dashboard_data(a: int, b: int) -> int:
pass
@mcp.tool(group="chart")
def get_chart_data(a: str, b: str) -> str:
pass Describe alternatives you've considered
-
Maintaining separate python modules or naming conventions to imply grouping—but this is brittle and pushes discovery responsibility onto users.
-
Building an external registry or YAML file mapping tools to categories, but this duplicates information and diverges from the code.
Additional context
You should be able to register the same tool under multiple groups.
I’d like to open a PR to add this capability, since I’m building an MCP server, implementing grouping will also deepen my understanding of the SDK
Activity
ChengyanOo commentedon Jun 4, 2025
Hi @Agent-Hellboy,
I think this will be a great feature, but it's not necessarily true that maintaining your tools with individual Python modules or scripts is a bad practice. In fact, I believe that's how GitHub's MCP server was built — GitHub MCP.
On top of that, using the MCP Resource (YAML) to manage tool sets could provide users with a central configuration file, making it easier to manage everything in one place. Why do you think it would lead to duplication?
scottslewis commentedon Sep 29, 2025
@Agent-Hellboy I think you are on the right track here...coming from the programmer's view of how to create and add groupings of tools (python decorator enhancement. I've been working on something similar...using annotated classes as a way to specify groups (not required to be classes for group...i.e. could have programmer/tool interface same as yours).
https://github.com/ECF/MCPToolGroups
I think that what this requires, however, is an addition to the mcp protocol...to handle a new entity in the schema: ToolGroup. Here's my current proposed addition to the specification json schema:
https://github.com/scottslewis/modelcontextprotocol/blob/main/schema/draft/schema.json#L2617
What this adds to your proposal is the inclusion of a 'description', and 'title' ToolGroup properties that provide group meta-data...i.e. title intended for use mainly by devs/humans, and 'description' intended for model usage (_meta for extensibilitiy).
I've started this discussion: modelcontextprotocol/modelcontextprotocol#1567
I hope you will join it!
felixweinberger commentedon Oct 6, 2025
Hi, thanks for submitting this - as pointed out by @scottslewis above this proposal has gone through various iterations as a SEP on the protocol itself, so I'll close this for now to consolidate conversation there.
scottslewis commentedon Oct 6, 2025
For all info:
In cooperation with the previous efforts around protocol enhancement to support tool groups, I've started a new technical discussion.
To save eveyone from reading the whole discussion: the proposal started out focusing on ToolGroups, but given this input from the authors of the previous PEP, it has since migrated to be a more general grouping proposal (for tools, resources, and prompts...at least potentially).
The proposed schema additions from me, incorporating (I think) all the input from the discussions, including generalization to usage for not just tools, is here and subsequent comments.
Also FYI, @cliffhall has requested the creation of a new discord channel for a 'groups' working group. I don't think that's been created yet, but it is in the works.
Please consider joining this discussion and/or the discord channel once available, and providing your input.
cliffhall commentedon Oct 11, 2025
The Discord working group channel is called
#primitive-grouping-wg. Come join us.