Hi @scottslewis, Thanks for starting this: my main unanswered question is that how is this fundamentally different from the original namespaces proposal #993. It seems we are introducing a new concept (groups instead of namespaces) and we will presumably need some kind of list/tool_groups method which the client will use to retrieve the list of groups that the server exports.

Two reasons why this is different from namespaces:

1. ToolGroups have a string name property. That does not require any of the hierarchy of namespaces. It's possible to define a hierarchical name for a ToolGroup as a single string...and it may be a good idea for lots of use cases...or maybe it should be encouraged via convention and/o sdk-implementation...but it's not required by a string property.

2. There are description and title properties/fields, and these are meta-data (for human and model use) about the group that contains 1 or more tools. With these fields, a tool group becomes an entity that can have model and human meaning of it's own beyond providing a unique name for the tools it contains.

Namespaces

I've read #993 and #1300 and comments thanks. Funny you should mention, as I've got another, prior version of the schema where I introduce an optionally-hierarchical 'name'...aka namespace. I think it's better than a single string, as the ToolGroupName entity allows for backward compatible additions (e.g. new optional properties/fields).

For some other of my recent thoughts on namespaces please see here.

Thanks for bringing up namespace so quickly. I debated with myself over presenting name as string or ToolGroupName to start discussion. There are many alternatives wrt naming/namespaces...and tool group hierarchies. ToolGroupName is intended as a first shot.

I don't think that's the main issue here - I think we can debate weather we should call them groups or namespaces, or what types they should be, but what I'm more unsure is about the rest of the protocol surrounding them.

What I really like about this proposal is reusing ToolAnnotations and adding a group annotation in there and making sure those groups have metadata.

What is missing: how does the client discover the group metadata? And if we are going to use a list/ type method for it, we will run into the same problems with getting this accepted as the previous versions did.

My suggestion: Instead of using a list/ method to retrieve the metadata, let's associate them with specific resource URIs. So, instead of making the group annotation have a name: it can have a ResouceURI associated with it. That ResourceURI holds that entire group information - name, title, etc.

That becomes very similar to how MCP-UI is uses the UIResource instead of creating new types. My hope is that by not introducing any new concepts in the base protocol, we can just get this accepted as an extension (see: #1502) and that'll be much easier.

I don't think that's the main issue here - I think we can debate weather we should call them groups or namespaces, or what types they should be, but what I'm more unsure is about the rest of the protocol surrounding them.

You don't seem to appreciate this point

There are description and title properties/fields, and these are meta-data (for human and model use) about the group that contains...1 or more tools. With these fields, a tool group becomes a distinct entity that can have model and human meaning of it's own beyond providing a unique name for the tools it contains.

The description and title metadata are with respect to the group...not the individual tools (which have their own Tool.description and Tool.annotation.title).

Setting aside the name/namespace syntax, ToolGroup.description and title (as proposed and under discussion) is new metadata that is distinct from a given tool's meta-data....i.e. a 'category' (aka group, class, collection, feature, module, etc).

What I really like about this proposal is reusing ToolAnnotations and adding a group annotation in there and making sure those groups have metadata.

Suppose you have two tools: add and multiply. How would you provide a description for an 'arithmetic' group...that contains both add and multiply tools in the same group with the existing Tool schema alone?

What is missing: how does the client discover the group metadata? And if we are going to use a list/ type method for it, we will run into the same problems with getting this accepted as the previous versions did.

I think that's a valid concern...i.e. how any client (model or human ui) discovers the group metadata, but I haven't said anything about that with this proposal to this point. I do think it could be a new message/response (e.g. listGroups), or it could be parseable name (by convention)...e.g. uri as you suggest, or some other convention for group naming that makes sense in most modern programming languages...e.g. module.classname or something else. I know that this functionality has to be there eventually, but without an entity with distinct metadata in the schema, how will client and server communicate about it?

My suggestion: Instead of using a list/ method to retrieve the metadata, let's associate them with specific resource URIs. So, instead of making the group annotation have a name: it can have a ResouceURI associated with it. That ResourceURI holds that entire group information - name, title, etc.

I think that using a uri or part uri to represent the 'name' of a group could be a way to go. However, I think that a full uri doesn't really make sense at the tool/toolgroup level for example. For example, if the full URI were provided for every tool in a single running mcp server, wouldn't that restrict each tool to running on that one server? What if the server's dns name changes? What if another server wants to provide access to that tool (by dynamically adding the tool to it's set of tools), or a proxy is to be used (e.g. gateway)?

Now...let's say we cut the tool name down to just the uri path e.g. /my/groups/arithemetic/add. I can see this working as the name for an arithmetic group name, but there still isn't any way to specify a group description that's distinct from the add tool's description and the path/group name.

I also have concerns about about using a file system path to represent tool group names, as file systems imply lots of capabilities (for example full nesting of directories/groups...groups in groups in groups) that will add complication and may not be worth the complexity...at least at this stage.

As an example alternative than the file system, consider a class. In most programming languages classes (groups of methods) have a module/package name, and then a 'meaningful' name of the class declaration itself...e.g. Arithmetic. The naming of the class is usually partially specified by the language and partially convention...e.g. my.module.Arithmetic, but it's defined by the programmer and generally has to have a fully qualified unique name. It's fully qualified name may or may not have anything to do with the file system (as compared to resources...files/directories, etc).

That becomes very similar to how MCP-UI is uses the UIResource instead of creating new types. My hope is that by not introducing any new concepts in the base protocol, we can just get this accepted as an extension (see: #1502) and that'll be much easier.

If you are just talking about the path segment of URI...ok. But I think that introducing a tool grouping entity is what's needed here...as no matter how that entity is named (path, uri, by convention as described above) there's the description and title (and perhaps other metadata in the future) to represent a single group with more than 1 tool (i.e. the toolgroup) to the llm/model and other clients.

Another advantage of introducing a new entity now is that optional fields/properties can be added in the future without breaking backward compatibility. That was/is part for the intention behind introducing a tool-group specific namespace entity like ToolGroupName

"ToolGroupName": {
            "properties": {
                "segmentName": {
                    "description": "An identifier for a segment of an optionally-hierarchical name",
                    "type": "string"
                },
                "parentName": {
                    "description": "An optional parent toolgroupname segment",
                    "$ref": "#/definitions/ToolGroupName"
                }
            },
            "required": [
                "segmentName"
            ],
            "type": "object"
        }

@scottslewis there's definitely some interesting ideas here - I really like the recursive definition of ToolGroups - but we still need a strategy for some of the other aspects. @cliffhall @patwhite maybe we should all set up some time to chat about how to move forward on this?

@scottslewis there's definitely some interesting ideas here - I really like the recursive definition of ToolGroups - but we still need a strategy for some of the other aspects.

Please publicly articulate other aspects when convenient. I'm not averse to expanding scope if necessary, but process-wise, I would personally prefer to keep things as focused on the specification changes as possible.

question: Obviously, I've been using json for describing schema changes. Would it be better for the process to move to js/typescript? Also, I've been thinking about working on the python and/or the typescript impl. Not going to do that, though, until we've gotten further with the spec piece...unless it will make the spec process move more smoothly.

@cliffhall @patwhite maybe we should all set up some time to chat about how to move forward on this?

Looking forward to it. I suggest that we use the new working group discord channel (tool-groups-wg)...once it's up and running.

Please publicly articulate other aspects when convenient. I'm not averse to expanding scope if necessary, but process-wise, I would personally prefer to keep things as focused on the specification changes as possible.

I don't think I understand how clients retrieve these group metadata from the server.

Please publicly articulate other aspects when convenient. I'm not averse to expanding scope if necessary, but process-wise, I would personally prefer to keep things as focused on the specification changes as possible.

I don't think I understand how clients retrieve these group metadata from the server.

Ok. The first way is without any new mcp spec'd client requests + server responses...just using listTools().

Given ToolGroup in schema, and new type support for generating and parsing json in the respective sdk...like above for the java sdk. (I'm going to refer to the java sdk because I'm currently most familiar with the code that implements mcp servers and clients in that sdk, but I am certain that there are similar spec datatypes...like Tool, ToolAnnotations and all other types...for each of the other sdks).

Given the above in both server and client, the client call to the existing listTools() will return a list of Tool objects.

For each Tool object in the list, if the server has created and set a ToolGroup instance to the Tool....via the Tool.group property/field, then on listTools(), the server will serialize this Tool.group(ToolGroup) to json, the client will receive the json, parse it into a local instance of ToolGroup, and the client will be able to access the same Tool.group() for each Tool, and to the ToolGroup.name, ToolGroup.description and ToolGroup.title meta-data the ToolGroup has.

The ToolGroup.description value will be the description for each ToolGroup, distinct from the description given set for each of the Tools in the ToolGroup, and the model can then use the ToolGroup.description and the Tool.description to help choose which tool it uses for a desired action. The ToolGroup can provide additional 'higher-level' information about each of the Tools it contains. Here's an example in Readme.md using the @McpToolGroup annotation with a description that is: 'Arithmetic operations exposed as mcp tools'. Just an early example.

I've been thinking that ToolGroup.title could be used in the inspector UI...or any other client...to organize, classify, and present groups that hierarchically organize Tools. ToolGroup.title could also be used by a model.

All this works by adding ToolGroup to the schema and a spec-compliant ToolGroup type for each sdk....and using the existing listTools() client request/server response already in protocol.

It may also make sense...either immediately or after some ToolGroup usage to

a) add new client->server request/response messages...e.g. listToolGroups(), and/or listTools(ToolGroup)

b) enhance existing messages with filtering...e.g. listTools(ToolGroup name filter)

I don't think I have a good feel for the use cases for the inspector usage, nor other client (or server) needs for searching and or filtering/querying the mcp server wrt tools/ToolGroups, and so am looking to @chughtapan, @cliffhall, @patwhite and other community input on what use cases are most important here. Also, I do think the existence of ToolGroups in mcp will change things wrt the ability to organize/categorize/present and structure tools. How tool and mcp server and client developers will use this more generally? I'm not sure.

I'm hopeful that everyone's experiences and work #1300 can inform what's done here.

Hi @d0lwl0b . The notion of adding Groupings (of tools, resources, and prompts) supports many use cases...including building a router or gateway...that exposes dynamically created groups of tools, resources, and/or prompts. Groups as defined in the schema proposal above could also support what is described as semantic layering in #1679 by using the Group.description and Group.title fields...in a way similar to Tool.description or Prompt.description, but focused on the group abstraction...e.g. an Arithmetic group containing add, subtract, multiply, divide tools.

I would say the answer to your question is: yes.

We've been hoping for a standardized mechanism to provide stable categories of tools and resources from a governance perspective while retaining the dynamic nature of MCP for future tool evolution. Do you see this groups proposal as the right tool for this problem space?

Absolutely yes. I had not personally considered using categories (aka Groups) for governance and tool and resource indirection...to prevent hard implementation dependencies. Would you be ok with me linking your use case description to this new discussion:

Use Cases for Grouping

Or if you want to post it there yourself that's fine too. I would like to try to use #1772 as a public enumeration of grouping use cases for the primitive-grouping-wg working group. Let me know if you want to do that for you.

A couple of questions

1. This seems from your description that you would be looking for 'server-defined/server-managed' categories/Groups...i.e. a Group of candidate tools that the mcp server can use to respond to clients? Is that right?

2. You mention the need for (server-side) dynamics. By dynamics do you mean the ability to create groups, modify/update them (e.g. adding/removing tools or resources from a given group), and delete groups? On the server I assume (1), or do you mean something else?

My driving use case (dynamic tool grouping) is also based upon server-side dynamic group creation...see Dynamic Tool Groups Use Case Example

If you have any comments or criticisms of this proposal for primitive Groups wrt your use case (e.g. would it allow/limit you to do what you want to do), I would like to hear them.

Yes, feel free to link. I'm new to the SEP process, so if you know how best I can help advocate for this, let me know.

The concrete example is I own an MCP server for a data storage system. Currently I have tools like read_query() which does SQL statements. Through experimentation agents will likely get better results from my system if I switch to the search() and fetch() pattern. My challenge is how to replace one tool with two different tools without breaking clients.

The raw MCP protocol says I can just change my MCP server and agents will automatically adapt to it, because they'll receive a different list of tools on their next tools/list call. But I am seeing upstream agent building solutions starting to let agent developers explicitly allow/disallow individual tools in the agent definition itself. If an agent developer does that, I'm now stuck and can never evolve my MCP server because it would be a breaking change.

I would rather define a tool group called data_retrieval which has one tool (read_query) today. And tomorrow may contain search and fetch. If agent development platforms take a dependency upon the tool group instead of the individual tools, I can now evolve my MCP server without breaking existing agents. And agent developers and administrators can still have the governance controls they need (such as disallowing the schema_modification group of tools while keeping the data_retrieval group).

My groups themselves are not dynamic. My desire is for agent governance to have some stable grouping above the tool level to set controls on.

The concrete example is I own an MCP server for a data storage system. Currently I have tools like read_query() which does SQL statements. Through experimentation agents will likely get better results from my system if I switch to the search() and fetch() pattern. My challenge is how to replace one tool with two different tools without breaking clients.

@jeffandms You can use server instructions (see this recent blog post) to tell the LLM that after doing a search they can do a fetch to get the actual data. You can also put instructions in the _meta of the tool response for search that tells the client that they can retrieve the found item(s) with the fetch tool.

I'm familiar with server instructions, but the need here is a bit different. It is upstream agent toolkits and agent makers who are currently taking direct tool dependencies because of the lack of grouping concepts. They're doing so to provide deterministic governance of the tools. We can argue that the MCP protocol says they shouldn't do that, but in the absence of a better granularity for providing governance they'll continue doing so.

The second an upstream agent or toolkit takes direct dependency upon a tool name, I as an MCP server owner am dead in the water in terms of future iteration. No matter how many meta instructions I provide, if the toolkit/agent only looks at specifically named allow-listed tools, any future iteration by me becomes a breaking change.

Seems like a weird dependency for an agent to take. Tool names can change. Now if the agent tied the tool name to the server version, that could make sense. Each version of the server could introduce tool name changes.

But how does grouping fix that particular problem? Seems like it just moves the problem to group names. If the agent makes a dependency on group name, then you can't refactor the names of your tool groups.

Can you say more about which agents and what you mean by "direct tool dependencies" (e.g., hard coded names?)

I forgot one for prompts

5. Using groups to logically organize prompts around an agentic task or role. Making something conceptually like claude skills native work more natively in mcp where you would have everything you need around a skill / role in a group. I guess this also isn't exclusive to prompts, but would apply to all primitive types.

Hi @bdoyle0182 . First, thanks for use case description. This is wonderful.

I've recently created a discussion at #1772 just for use cases (as this discussion was originally intended for discussion around this proposal specifically). Would you ok me creating a link to your comment here in #1772?

We were just discussing in the working group meeting this morning the need for use cases for grouping that are not for tools specifically, So your use case is timely and most welcome.

Example use cases from me. Note that much of these use cases are for human in the loop -> server interaction rather than autonomous agent -> server interaction which is the guideline for prompt / resource primitivies.

Strongly agree. In my view use cases for grouping should include as many as possible of both human-dev-as-client, as well as aimodel-as-client. I do think of grouping as potentially relevant to both sorts of clients (and Group has Group.title and Group.description also).

As the originator of this proposal, I'm going to respond on this discussion to your questions around whether this proposal addresses some of your questions.

2. Using groups to logically organize a wrapping api. For a company wrapping their product api w/ mcp; they can use groups to more closely resemble the actual underlying api and expected user experience. This is pretty self explanatory but since the github server is used as the common example, actions api would be a group.

I see this as related to what I was trying to convey with this use case description.

3. For client side UX, having hierarchy built into protocol is extremely beneficial for having organized resources / prompts for the user like a file system to sort through. As is today, this can't be accomplished with the protocol because clients can't rely on hierarchy in the primitive name since the way that hierarchy is applied in the name would vary from server to server. With hierarchy in groups, mcp clients (coding agents for example) can start building into their UX a file system like approach for humans to sort through prompts / resources available to them for large servers with lots of prompts or resources. OR if my client is connected to many servers and the combination of many servers causes me to have many prompts and resources in my client.

I will let others comment about client side UX, but I think what you are describing in terms of groups for organization/UX is similar to what I've read in part of the extended discussion on #1300.

This use case I want to call out because it could be tricky to implement in mcp clients with multi-groups, there's more things to consider than a traditional hierarchy where an item is a child of only one parent. Just want to make sure this is considered.

Yes, it's clearly very important, as it's related to by namespaces (usually hierarchically arranged names) and hierarchies. The proposal described in this summary comment declares a recursively-defines field name Group.parent...i.e. the parent field value is of type Group, and defines a relationship to a parent Group.

First, I want to say this is a proposal for how to introduce hierarchy in grouping. A definition like this makes possible a tree/hierarchy of Groups of arbitrary depth. Each Group can be pointed to (with parent ref) by an arbitrary number of (child) Groups. Further, since Tools, Resources, Prompts can also point to a given (uniquely named) Group, a single group with this definition can hold any number of Tools, Resources, or Prompts in any combination.

This is very flexible for representing graphs of Groups, Tools, Resources, Prompts and potentially other things, as a hierarchy of named Groups with optional title, description, and meta. It somewhat resembles a file system, where named directories are analogous to Groups and Tools, Resources, Prompts are kinds of files.

I do really think that probably the most push back you'll get in review is multi-groups as it adds the most potential long term / tail potential complexity to the protocol, where i could see in the future five years from now a situation where people are saying I wish we didn't do something like multi-groups until we knew more on how we wanted to support it.

Yes I agree this is a danger. That's one reason why I think (in this proposal) Group.parent should be (and is) optional, and each group can have it's own (opaque) string Group.name (required of course as in the other mcp primitives). The notion of optional new fields (sender) and ignoring unknown fields (receiver) allows a good deal of protocol flexibility and backward compatibility.

So my personal leaning is build in a way that could support multi-groups as a future enablement but we don't have it in initial release; i can certainly be swayed though.

Yes. Another way (other than the Group.parent field) might be to use the Group.meta mechanism to hold a 'parent' reference. The reason I don't like this is that if meta is used, all schema-defined typing is lost. As I see it, that means that all sdks will have to write a fair amount of duplicate code for handling a meta['parent'] references (and the Group.name, Group.description, and Group.title fields). So in this proposal, I've suggested that the Group.parent -> Group be defined within the Group primitive and we find out through (optional) community usage where the dominant use cases are. OTOH, Group.parent could be removed from the Group schema definition and added to the Group.meta definition, but then every sdk would have to be enhanced appropriately to support it.

4. I don't know if the proposal as is would support this use case because the group model is doing primitive assignment to a group to support multi-groups rather than an inheritance model.

Would you explain what you mean by an inheritance model? I think of the Group.parent field as enabling the creation of tree graphs (like filesystems) and explicitly not complete network graphs (e.g. routes between cities). But you might mean something else by 'inheritance model'.

But if it was a true clean inheritance model, you could abstract shared logic into the group definition itself that could be passed / made available to all primitive children in the group. I think this is okay to ignore if it doesn't fit with the model to leave groups as clean as possible without any logic in them and strictly an organization mechanism.

In this proposal, the Group schema is primarily for serialization of an object graph defined on an mcp server (the source of other mcp primitives...Tool, Resource, Prompt, etc)...to json...sent over the wire to an mcp-client...and deserialized (from json) on the mcp-client.

I was initially not intending to say anything about what the in-memory (or in db/on disk) representation of Group, Tool, Resource, Prompt is...nor what actions (what code) can be run to add/remove/update/etc the Group tree (or it's title, description, tools, resources, prompts, etc) and/or take other actions based upon the primitive object's data. It seems to me that's a design choice,,,i.e. using inheritance in a class hierarchy...for the mcp server and/or client builders...so that they can operate on the graph. But I could be misunderstanding your intended usage of inheritance.

Thanks for the use case descriptions and let me know if you object to me adding this comment as link on #1772.

@bdoyle0182

I was initially not intending to say anything about what the in-memory (or in db/on disk) representation of Group, Tool, Resource, Prompt is...nor what actions (what code) can be run to add/remove/update/etc the Group tree (or it's title, description, tools, resources, prompts, etc) and/or take other actions based upon the primitive object's data. It seems to me that's a design choice,,,i.e. using inheritance in a class hierarchy...for the mcp server and/or client builders...so that they can operate on the graph.

This comment got me thinking about creating an in-memory tree structure on servers (owners and storers of the datastructure) and/or clients (receivers via MCP protocol of the data structure) to and from the json schema/spec-defined model that goes on the wire between client and server.

I created a simple tree model where the root of the tree is a GroupNode (with parent == null), and the top GroupNode has g child GroupNodes (g >= 0), and t child ToolNodes (t >= 0). The classes to represent this tree data structure is here. Note that this model has, for each leaf type (GroupNode, ToolNode, PromptNode) all the appropriate fields (name, title, description, parent for group, toolannotation for ToolNode). I've not yet created a ResourceNode, but that's next.

As a small/simple test of this model, there is a java-based test client that connects to an MCP Server (with the Groups support added as described by the readme), calls listTools() to get back List<Tool. This List (the Tool type is as per the mcp specification), can then be deserialized to produce a List. The tree is then traversed from each ToolNode to find the top node of the tree. Then the (single) top GroupNode is printed out (along with it's child Tools):

This test produces this trace output:

Tree=GroupNode [name=com.composent.ai.mcp.examples.toolgroup.api.ExampleToolGroup, isRoot=true, title=, description=Arithmetic operations exposed as mcp tools, meta=null, childGroups=[], childTools=[
		ToolNode [name=com.composent.ai.mcp.examples.toolgroup.api.ExampleToolGroup.add, title=com.composent.ai.mcp.examples.toolgroup.api.ExampleToolGroup.add, description=computes the sum of the two double precision input arguments a and b, meta=null, inputSchema=JsonSchema[type=object, properties={x={type=number, format=double, description=x is the first argument}, y={type=number, format=double, description=y is the second argument}}, required=[x, y], additionalProperties=null, defs=null, definitions=null], outputSchema=null, toolAnnotation=ToolAnnotationNode [title=, readOnlyHint=false, destructiveHint=true, idempotentHint=null, openWorldHint=true, returnDirect=null]], 
		ToolNode [name=com.composent.ai.mcp.examples.toolgroup.api.ExampleToolGroup.multiply, title=com.composent.ai.mcp.examples.toolgroup.api.ExampleToolGroup.multiply, description=return the product of the two given double precision arguments named a and b, meta=null, inputSchema=JsonSchema[type=object, properties={x={type=number, format=double, description=x is the first argument}, y={type=number, format=double, description=y is the second argument}}, required=[x, y], additionalProperties=null, defs=null, definitions=null], outputSchema=null, toolAnnotation=ToolAnnotationNode [title=, readOnlyHint=false, destructiveHint=true, idempotentHint=null, openWorldHint=true, returnDirect=null]]], childPrompts=[]]

Would you explain what you mean by an inheritance model? I think of the Group.parent field as enabling the creation of tree graphs (like filesystems) and explicitly not complete network graphs (e.g. routes between cities). But you might mean something else by 'inheritance model'.

I am thinking of in terms of Group holding data that can be referenced by its children, parent / child concept of OOP. My one use case thought I had would be rules you want injected to all children prompts of a group. Store this data in the group and then inject it at top of all child prompts. Should this be built into the protocol, no. But maybe consider does the Group primitive allow consumers writing SDK's or servers to leverage the group primitive to do cool things with the OOP tools of the language on the group and its children; or is that something we want or would be interested in building towards if not?

I will let others comment about client side UX, but I think what you are describing in terms of groups for organization/UX is similar to what I've read in part of the extended discussion on #1300.

Yea I think so. Just to elaborate I think that having codified hierarchy around primitives built into the protocol is very important for UX and allowing clients to build around a file system model and have it be portable. You will have clients be more willing to invest in a hierarchical UX if they know its portable to all servers and not how a specific server does hierarchy.

It seems to me that's a design choice,,,i.e. using inheritance in a class hierarchy...for the mcp server and/or client builders...so that they can operate on the graph. But I could be misunderstanding your intended usage of inheritance.

I think this covers it and my above explanation I hope covers what my thought process was, I think we're on the same page. I love that my comment sparked an idea to explore

I am thinking of in terms of Group holding data that can be referenced by its children, parent / child concept of OOP. My one use case thought I had would be rules you want injected to all children prompts of a group. Store this data in the group and then inject it at top of all child prompts. Should this be built into the protocol, no. But maybe consider does the Group primitive allow consumers writing SDK's or servers to leverage the group primitive to do cool things with the OOP tools of the language on the group and its children; or is that something we want or would be interested in building towards if not?

Yeah I would say this is something that at least some of us would be interested in building towards. The *Node classes defined here (i.e. GroupNode, ToolNode, ResourceNode, PromptNode) represent a simple in-memory model that can be serialized to mcp spec Group, Tool, Resource entities, and deserialized from a GTMP json object graph to be used in either a mcp server or client. This is just a protobype model, but it's intended to support (via subclasses?) mcp server and client devs creating their own models, with their own/private/custom members for it's in-memory/in-process model.

I think this covers it and my above explanation I hope covers what my thought process was, I think we're on the same page. I love that >my comment sparked an idea to explore

Yes! Thanks.

I think such an id in the schema could make the spec-defined type/schema structure far more complicated and opaque for sdks (id vs. typed ref vs. actual serialized instance). But there are tradeoffs either way.

Ids for things are a normal part of computing in general. Adding an id to a group doesn't make it "complicated and opaque" any more than the use of primary keys in SQL.

My opinion is that if the recursive definition can be implemented across langs (e.g. jsog), without breaking the sdk's backs (or maybe with the primitive-grouping-wg assistance), then it could be worth keeping for the simplicity and generality (i.e. hierarchical trees of Groups and other primitives).

It doesn't scale. Imagine just 100 groups each with 10 children. That is 10 x 100 + 100 = 1100 definitions of the 100 top level groups included in the response.

So @cliffhall ...in terms of scaling, you can make the same argument about the schema-defined types for Tools, Prompts, and Resources...i.e. it doesn't scale. As example, forget about Groups/grouping. 10,000,000 tools, all sent in response to a single listTools() doesn't work. Right?

One appeal of hierarchical groups, IMHO, is that it provides a way to group and summarize sets of Tools, Resources, Prompts...like directories on a file system, or organization/schema of a DB. Yes, such organizations can get large by themselves (of course), and there will likely have to be new additional client->server protocol (e.g. listGroups() or filtering Tools by groups, or by user/role, etc)...or server-side dynamic construction of a set of groups *for this user/application/use case" rather than a single, statically defined, set of groups.

To me a recursive definition of Groups give a very flexible and powerful structure to start with (for server builders to build upon without re-implementing the same proprietary categories of other primitives, as the server and gateway product implementers are already doing (e.g. namespaces in Azure MCP).

Just for the record, the current declaration of Group in this proposal can support any set of namespaces, as Group.name is just a string (can be...but doesn't have to be hierarchical). FWIW, this tool grouping example, only a single Group instance is defined, but that instance has name/namespace that is hierarchical and guaranteed to be unique (e.g. com.composent.ai.mcp.examples.toolgroup.api.ExampleToolGroup).

Also...btw...the mechanism used in the Java impl I describe scales just as well as an 'id' to group (in fact that's what it is in jgog/Jackson JsonIdentityInfo)...it's just addition a synthetic @id and @ref...to avoid serializing a given Group over and over again (which will be the default for most json generators/parsers...and that's what pydantic and Jackson do, for example).

So what I'm saying is: I agree that serializing every Group each time in stream doesn't scale well, that's why I suggest impls/sdk use something like jsog (json object graph)...to only send the unique Group instances that the server wants sent, rather than n copies. That's much less likely to cause a problem, since the server gets to decide (at runtime) what Groups are actually sent.

agree with cliff here. the full tree can't be included over the wire.

Why would a server implementer ever send the 'full tree' if they didn't have to? Think of it like a web app. The server is never going to send the entire database contents or even the full in-server-memory version to a web client. It will send pieces of it, however, based upon the application needs (e.g. web based filesystem browsers).

So what I'm saying is...there is nothing about this recursive definition that requires that any 'full tree' be sent over the wire. It just says that the server can create groupings...analogous to directories, that a) allow model clients (llms) to have descriptions and titles associated with sets of other primitives; b) the organization can be created and communicated based upon user, role, apps, etc...on server to communicate at runtime. There's nothing about this design that requires sending a 'full tree'...or even any tree.

both from scale perspective and it isn't really adding any utility anyways by having the tree in the schema def

I disagree with this. The schema defines the types...and their fields...that are put on the wire. But in all the implementations I've looked at the schema entities also come from types (classes generally, but can also be structs/record/etc). As to get onto the stream, the server has to populate the in memory representation (as opposed to db, or disk or whatever) and serialized it. That in memory representation is also defined by the schema-declared types (Tool, Resource, Prompt, ToolArgs, Annotations, Icons, etc). Both the client and server use these data structures in memory (e.g. the llm clients use the contents of description) to choose what to do at runtime.

In my opinion, it would/will be much better for sdk users to have these classes...including Group to work with...rather than to re-implement...with exactly the same schema-defined structure) by/for every application (as part of the sdk). Especially since the structure of these types is tightly connected to the json schema/protocol and the classes/types that represent them in server and client memory.

Imagine if a Group was put on the meta data structure (no typing information). Then, every implementation and every language would have to re-implement the parsed dictionary/named field to -> Group type with description, title fields, etc. By having the Group schema definition they can just deserialize the json stream to a Group instance and use it in their client and/or server-side code.

So just to be clear:

a) I'm not suggesting that the 'entire tree' be automatically serialized and sent to a client; I agree that doesn't scale. But there's nothing about this proposal that requires serializing the entire tree.

b) Each application-app-and-request-specific tree, however, can be serialized efficiently by using an object graph (where there are ref that can be serialized and deserialized via something like a jsog (javascript object graph) implementation.

Ids for things are a normal part of computing in general.

Yes, I understand that. I"m not saying or implying otherwise. Ids can be very useful (please see below).

Adding an id to a group doesn't make it "complicated and opaque" any more than the use of primary keys in SQL.

Actually I think history and evidence shows that objects are a better/preferred by runtime representation than a record(s) from a database. Of course any server-side webapp could be written with the app 'model' represented by a set of relevant records from a database. But most languages these days prefer types/classes/objects with a defined in memory structure...which can be called an object graph.

And btw...jsog/@JsonIdentityInfo dynamically puts a unique id onto the json output stream...maintaining object uniqueness...and the jsog parser reads from that stream and creates the object graph (and removes the @id and @ref from stream, and replaces the @ref with the actual object in-memory instance. This is something that would have to be done at the application level if a string 'parentid' were put in the schema in place of the Group.parent schema reference. With the Group.parent -> Group it can be done (efficiently by jsog) by the sdk, while maintaining cross-language interoperability.

I don't want you wasting your time writing out novels to defend yourself. My opinion is just on any sort of recursion / hierarchy included in the data sent over the wire which is just going off what was said in this thread on how the json spec was initially interpreted. I just think there's confusion on that, otherwise i don't see any concern beyond that if that's not actually the case

I don't want you wasting your time writing out novels to defend yourself. My opinion is just on any sort of recursion / hierarchy included in the data sent over the wire which is just going off what was said in this thread on how the json spec was initially interpreted. I just think there's confusion on that, otherwise i don't see any concern beyond that

Please...I'm not trying to defend myself. I'm just trying to be as transparent as possible about what is being proposed, and get as much community consensus about tradeoffs as possible. Questions about scalability, handling cycles/object graph representation efficiently, use of object models vs. other data models, tooling, dev API, sdk vs. schema, etc...are all completely fair game.

I'm also happy to discuss this in other forums...e.g. meetings etc...and or give presentations, q & a, etc...if people prefer...I just like to have technical discussions in prose + links as a fallback so that other community members participate without having to go through lots of dialog. And although I'm flattered that anyone refers to this stuff as 'a novel', I will try to be less verbose...hopefully while being thorough.

So please keep the questions coming and I'll do my best to answer them...not to defend myself...but rather to get to the best outcome for the (dev) community that we can jointly get.

I just meant I don't want you feeling the need to waste time overly explaining yourself over a confusion :)

We also discussed making name unique so that an id is not required. This is probably the most pragmatic.

Yes. I found this in the online docs about Tool Names. According to these docs, tool names (at least) should be unique.

With Group as a new primitive we could also require uniqueness for the Group.name, but relax the uniqueness requirement slightly for all primitives, to allow for 'fully qualified' names (i.e. Group as filesystem directory/packages/modules/bags/containers).

Scott Lewis's Group primitive proposal addresses technical organization but misses the critical need for user-centric filtering. I strongly recommend prioritizing Concern-Based Filtering over protocol-level groups.

This is the wrong discussion/forum for your recommendation. Please consider producing an SEP for user-centric filtering, building a consensus around it, and proposing via the SEP process.

I also disagree with your prioritization of user-centric filtering over a server-side Group entity. As you've articulated user-centric filtering, it appears to me it would require large scale changes to the MCP protocol, and therefore break protocol backward compatibility. If this is incorrect, I suggest you provide a schema specification in a proposal, along with a reference implementation so that the specifics of user-centric filtering as you've defined it...can be discussed in the appropriate forum. This is not the correct forum for that discussion.

Thank you for your reply. I agree with your point that this discussion is about the Group primitive proposal, and that a detailed proposal on user‑centric filtering should be created as a separate SEP and submitted through the formal process. I appreciate your advice regarding the SEP creation process.

Let me clarify the intent of my comment. I understand that the Group primitive proposal (by Scott Lewis and colleagues) focuses on technical organization. However, I believe technical organization alone is insufficient and misses the critical need for user‑centric filtering.

"Group primitive proposal addresses technical organization but misses the critical need for user‑centric filtering."

User‑centric filtering enables users to express their needs in natural terms (security, cost, performance, etc.). This is a user‑interface‑oriented approach, distinct from technical organization for developers.

I also share my view on the implementation approach for Groups: "I consider the Group approach as one possible implementation method inside an MCP server, but it should not be adopted into the MCP Protocol because other methods should not be excluded."

Groups are one way to organize tools inside a server; fixing them as a protocol standard would risk excluding other implementation methods. Instead, we should standardize high‑level interfaces like user‑centric filtering and allow flexibility in server‑internal implementation details.

Regarding the technical concern that user‑centric filtering would require large‑scale protocol changes: I argue it does not. The changes are minimal, essentially adding two steps to the workflow while keeping everything else as default processing:

1. MCP Server → Provides: A declaration of available concerns, e.g., ["security": "high|medium|low", "cost": "minimal|moderate|high"]
2. MCP Host → Sets: The user’s concern preferences, e.g., {"security": "high", "cost": "minimal"}
3. MCP Server → Returns: A subset of tools/resources/prompts that match the high‑security and minimal‑cost requirements (default behavior).

Only steps 1 and 2 are additions; step 3 is the existing default behavior of returning tools/resources/prompts, now filtered according to the host’s stated concerns. This can be realized by extending the existing metadata of Tools, Resources, and Prompts, introducing incremental client‑side filtering logic, and maintaining backward compatibility through optional fields.

As next steps, I will:

1. Create an SEP for user‑centric filtering and follow the formal proposal process.
2. Continue an open discussion on the complementary potential of the Group primitive proposal and user‑centric filtering.
3. Further explore how both approaches can contribute to solving the Context Overflow problem.

While I acknowledge that the proposed Group primitive may help address Context Overflow, I wanted to emphasize the importance of a user‑centric perspective. I look forward to future collaboration and constructive discussion.

Best regards,

However, I believe technical organization alone is insufficient and misses the critical need for user‑centric filtering.

Insufficient for what?

In my view, 'technical organization' of existing primitives (Tools, Prompts, Resources) is and should be up to the MCP server developer(s). What I and others have been hearing is that server-side organizational/grouping use cases are currently very important to them...e.g. for gateways, scaling, server-side organization use cases, workflow abstractions, user and/or model-specific collections, etc.

Thus the desire to provide as simple-as-possible notion of primitive group/grouping/categorization/organization for mcp-server-defined groups. Not as some sort of 'final architecture for organization/search/persistence/discovery', but rather as an incremental enhancement that MCP server (and client) developers can use (or not)...i.e. their choice.

"Group primitive proposal addresses technical organization but misses the critical need for user‑centric filtering."

I don't agree with 'critical need for user-centric filtering'.

User‑centric filtering enables users to express their needs in natural terms (security, cost, performance, etc.). This is a user‑interface‑oriented approach, distinct from technical organization for developers.

As I'm sure you are aware, MCP clients can be LLMs (use the description/title/other meta-data on MCP primitives to make choices and in the case of tools take actions), developers (e.g. users of inspector for developing/testing mcp server and client development), and end-users.

Which users are you referring to when you say 'user-centric filtering'?

Groups are one way to organize tools inside a server; fixing them as a protocol standard would risk excluding other implementation methods.

That's not true. As currently specified, if Group primitives are not used by server and client developers then they could easily be deprecated and disappear without breaking compatibility. If they are used...because they provide value to the mcp server and/or client developer...then establishment as a primitive was justified (like the existing primitives).

Instead, we should standardize high‑level interfaces like user‑centric filtering and allow flexibility in server‑internal implementation details.

Disagree. IMHO, this approach to protocol development and standardization doesn't work in practice, as backward compatibility and interoperability cannot be maintained when changing 'high-level' interfaces, as such interfaces must change/migrate forward without changing the underlying protocol...which frequently turns out to be impossible.

Regarding the technical concern that user‑centric filtering would require large‑scale protocol changes: I argue it >does not. The changes are minimal, essentially adding two steps to the workflow while keeping everything else as >default processing:

I don't buy this. Further, as I've said, I would personally only be convinced that such changes could be done in a backward compatible way by seeing the necessary schema/specification changes to implement it, and a reference implementation that actually works without breaking backward compatibility.

But, as I said previously, this discussion is not the appropriate forum for your proposal(s). I suggest you start a new discussion, or continue on existing discussions.

Hi Scott,

Thank you for your thoughtful comments. I appreciate the opportunity to clarify my perspective.

First, I want to emphasize that we share the same fundamental goal: solving the Context Overflow Problem. Where we may differ is in the approach and scope of the solution.

Regarding your question about "user-centric filtering" and which users I'm referring to: In the MCP context, the primary "user" making actual requests to MCP servers is the LLM (the MCP client). When I say "user-centric filtering," I'm referring to filtering mechanisms that align with the LLM's needs and constraints—such as security requirements, cost considerations, performance characteristics, and other domain-oriented concerns. This is distinct from developer-centric organization (like grouping primitives by technical categories), which serves different purposes.

You're absolutely right that MCP is a protocol defining the interface between MCP Hosts and MCP Servers. As such, it should focus on this interface rather than prescribing server-internal implementation details. The Primitive Groups proposal, while valuable for server-side organization, may not sufficiently address the interface-level requirements for effective filtering from the LLM's perspective.

I agree that server-internal organization using groups or other structures is important for developers. My position is not that such organization is unnecessary, but rather that whether it should be elevated to a protocol-level primitive requires further consideration. The protocol should enable, not enforce, specific implementation patterns.

To address the filtering need more directly, I've submitted a separate proposal: Proposal: Concern-Based Filtering #1936. This approach focuses on:

1. Allowing servers to declare available Concerns (e.g., security, cost, performance, data-privacy)
2. Enabling hosts to configure preferences for those Concerns
3. Having servers return subsets of primitives that match the configured Concerns

The key advantages of this approach are:

• It operates at the protocol interface level without dictating server-internal implementation
• It provides a user-centric (LLM-centric) filtering mechanism based on domain-oriented concerns
• It requires minimal, backward-compatible protocol changes
• It complements rather than replaces technical organization mechanisms

I believe Concern-Based Filtering addresses the "the Context Overflow Problem", while maintaining the protocol's focus on the host-server interface. The proposal includes detailed specifications, and backward-compatibility analysis.

I'd welcome your feedback on Proposal #1936, particularly regarding:

1. Whether the Concern-Based approach adequately addresses the filtering needs
2. Any technical concerns about the proposed protocol extensions
3. Suggestions for improvement or alternative approaches

Thank you again for engaging in this important discussion about MCP's evolution.

Best regards,

Hi Scott,

First, I want to emphasize that we share the same fundamental goal: solving the Context Overflow Problem. Where >we may differ is in the approach and scope of the solution.

I think we differ also in the assumption that there is 'a solution' to problems of context size. To me, that's because context can amount to: 'everything else that could possibly be relevant'. The trick is figuring out what is relevant in a given instance (e.g. is it the 'concerns' of the LLM client? or is it the descriptions of the tools/actions that the server 'knows' about?). My own guess is that it's mostly going to be some use-case-driven combination of both.

stuff deleted
cost considerations, performance characteristics, and other domain-oriented concerns. This is distinct from
developer-centric organization (like grouping primitives by technical categories), which serves different purposes.

Agreed...it serves different purposes. From your previous comments you seem to believe that there is somehow 'more importance' to the LLM-centric 'needs'. Given today's LLM behavior and our own lack of understanding of what the models are doing, I don't think we have a very good understanding of what these informational/context concerns are...to the point where we are all sort of guessing about what LLMs 'need' to be helpful. My $0.03.

You're absolutely right that MCP is a protocol defining the interface between MCP Hosts and MCP Servers. As such, > it should focus on this interface rather than prescribing server-internal implementation details.

I strongly disagree that the introduction of a Group primitive (alongside Tools, Resources, Prompts, Tasks, etc) constitutes 'server-internal implementation details'. IMHO the 'description' property (for Tools, Resources, Prompts, Tasks, and Groups, etc) is essential to MCP...as it allows the server implementers to convey model-relevant information (in text) to model, dev, or end-user via the protocol.

And for Groups (collections of the other primitives), the description property allows abstraction...e.g. Animals -> Mammals -> Humans, etc. or Task1 -> Task2, or Process 1 -> Process 2. Abstraction/grouping could be invaluable for e.g. Workflows (server-specific groupings of Tasks and Tools?).

The Primitive Groups proposal, while valuable for server-side organization, may not sufficiently address the >interface-level requirements for effective filtering from the LLM's perspective.

Although I agree with this statement, in my view it's not an either-or situation. As created, IMHO MCP is basically all about communicating server-side organization (e.g. descriptions of TPRs) so that current LLMs can use that information.

As hinted at before, I don't envy trying to figure out 'the LLM's perspective' at this point in model development. But please don't assume that server/data organization is somehow an 'implementation detail'. Consider http servers, for example.

I agree that server-internal organization using groups or other structures is important for developers. My position is > not that such organization is unnecessary, but rather that whether it should be elevated to a protocol-level primitive > requires further consideration. The protocol should enable, not enforce, specific implementation patterns.

I agree that the protocol should enable server development. In my view that's exactly what the Group primitive does...enable. There is nothing in the Group primitive that 'enforces' anything. Server developers are free to use it, or not...as its use is optional (as is the case with the other primitives as well).

But without Group.description there is no way for collections of Tools (for example) to be described and communicated to the model/developer/user mcp clients. All the current Group primitive proposal does is optionally add the Group type/properties to the protocol, so that server-created Groups (if any) can be communicated to clients.

BTW, wrt enabling mcp server developers, here's an interesting perspective:

https://www.oreilly.com/radar/what-mcp-and-claude-skills-teach-us-about-open-source-for-ai/

@cliffhall , @chughtapan , @LucaButBoring , @a-akimov, @bdoyle0182

Regarding use cases and examples of using a non-hierarchical (flat) groupings...

This example (see readme.md) creates a non-hierarchical toolgroup defined by a annotation named @McpToolGroup. It does not use hierarchical grouping (Group.parent) at all. I had forgotten this aspect, and should have brought up during discussion earlier.

This non-hierarchical example was driven by the 'mcp-gateway' use case described here

Note that the Group.name is in a hierarchical (class) namespace...i.e. com.composent.ai.mcp.examples.toolgroup.api.ExampleToolGroup (the fully qualified class name is the value of Group.name).

Our goal is to group MCP primitives. Skills isn't a primitive.

Following this with interest. I think the tension between Groups and semantic search points to something deeper: neither quite solves the core problem of LLM decision complexity at scale.

My own opinion is that we (collective we) are trying to figure out what kinds of data...about tools, prompts, and resources along collections of those primitives (with size >= 0)...in the form of text 'descriptions' can help an LLM/model wrt reading or writing resources, using/customizing prompts, or calling/invoking tools.

Groups organise tools but don't reduce what the LLM sees at decision time.

Remember...Groups can have descriptions as well. This provides the opportunity to add information relevant to LLM decisions. e.g. description -> "this is a group of tools and tasks for performing an automated stock purchase" (some workflow, or higher-level task.

IMHO, this does provide a means of giving the LLM 'hints' about abstractions...very relevant to humans in deciding what to do. Untried (so far) with LLMs afaik.

Semantic search adds a discovery layer but that's another LLM inference step.

I think of semantic search as the user (or LLM) expressing some desired contraints on relevance...like a person searching for a tool, or searching for a process/higher level concept.

Seems to me that there's no real 'tension' here, in that both structures...e.g. server/world-provided structure (like workflows or categories) and LLM-provided constraints (the current context is this..., I'm trying to meet human request this) are needed to figure out what decisions, actions, additional dialog should occur.

Thanks...I think it does.

FWIW, I just became aware of this work today:

https://www.anthropic.com/engineering/advanced-tool-use

Seems to me this is a mechanism for the 'client side' (LLM or Human client) to specify constraints (aka semantic filters, searching, etc) for fetching and using tools.

IMO, this is not at all incompatible with mcp server-side primitive groups/organization as I clumsily was trying to say here

Seems to me that there's no real 'tension' here, in that both structures...e.g. server/world-provided
structure (like workflows or categories) and LLM-provided constraints (the current context is this..., I'm
trying to meet human request this) are needed to figure out what decisions, actions, additional dialog
should occur.