You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -36,62 +38,37 @@ Groups are named collections of MCP primitives: tools, prompts, resources, tasks
36
38
37
39
- A productivity server could organize groups such as Email or Calendar, and present related tools, e.g. Email: ["Draft Email", "Spell Check", "Send Email"], Calendar: ["Add Participants", "Find Open Time", "Create Appointment"]
38
40
- A server with many tools could separate them by functionality such as "Pull Requests", "Issues", "Actions".
39
-
- A server with various reference programming resources could separate them by language, like "Python", "TypeScript, and "Kotlin".
40
-
41
-
#### Groups are overlapping sets NOT hierarchies
42
-
43
-
- Primitives can belong to multiple groups; for instance, if tools are grouped by use case, a `spell_check` tool might appear in both `compose_email` and `compose_document` groups.
44
-
- Since groups are a primitive, they may belong to multiple groups, and so the result is **not a hierarchy** but rather, potentially overlapping sets.
45
-
- Server developers should take care to avoid cyclic graphs — e.g., a group belonging to itself or to a child.
46
-
47
-
#### Transitivity
48
-
49
-
- Primitive A is in group B. Group B is in group C. Is primitive A implicitly in group C also?
50
-
- The Transitivity of groups is a matter of client interpretation.
51
-
- In the TypeScript reference implementation, the `communications` group contains `email` and `calendar` groups.
52
-
- When listing the primitives in the `communications` group, I chose to have it display the contents of both children.
53
-
- So `email_thank_contributor` would appear in both `email` and `communications`.
54
-
- Some clients might wish to only show direct children of a group.
55
-
- If a server contained cyclic graphs, configuring the client to only show the direct children of a group would short circuit the graph traversal, unless the group contains itself as a direct child, which would be an obvious mistake on the server developer's part that would likely never happen in production.
56
-
57
-
#### Visibility of Groups to LLMs
58
-
59
-
- Groups are simply an organizational tool available to the server developer.
60
-
- It is up to clients to decide how to interpret and make use of them, e.g., for deciding what primitives to expose to LLMs or simply ignoring them.
61
-
- Server developers cannot expect that clients will pass any group information to LLMs, although they may.
41
+
- A server with various reference programming resources could separate them by language, like "Python", "TypeScript", and "Kotlin".
62
42
63
43
### Why use Groups?
64
44
65
-
Organizing a server's primitives by functionality or use case enables richer client workflows, wherein certain operations or settings can be applied to multiple primitives concurrently. Some use cases [identified by the community](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/1772) include:
66
-
67
-
#### Client-Side & User Organization
68
-
69
-
-**Client-side Filtering:** Client UIs could display a list of groups and allow users to select/deselect specific groups to interact with or ignore. Primitives from deselected groups would not be presented to the LLM.
70
-
71
-
-**Library Management:** Enabling users to create and manage organized Prompt and Resource libraries that can be shared or reused across different sessions.
45
+
Organizing a server's primitives by functionality or use case enables richer client workflows, wherein certain operations or settings to be applied to multiple primitives concurrently:
72
46
73
-
-**Presentation and Search:** Improving how humans and AI models look up and discover tools. Grouping helps organize the interface so that relevant tools are easier to find among hundreds of options.
47
+
-**Client-side filtering:** Client UIs could display a list of groups and allow users to select/deselect groups to interact with or ignore. Primitives from deselected groups would not be presented to the LLM.
48
+
-**Agentic control:** In-addition to human-affordances, clients can offer agents special tools which enable the LLM to dynamically enable / disable specific groups.
49
+
-**Simplify server instructions:** When describing how to use various primitives in a server, the instructions could refer to them by group name rather than exhaustive lists.
74
50
75
-
-**Workflow-Specific Context:** Providing a model with a "set" of tools and tasks specifically curated for a particular workflow, rather than overwhelming it with every available primitive.
51
+
The [appendix](#community-identified-use-cases) describes many other use cases [identified by the community](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/1772).
76
52
77
-
#### Server-Side & Architectural Patterns
53
+
It is up to clients to decide how to interpret and use groups, and if grouping semantics are exposed to the LLMs or not.
78
54
79
-
-**Gateway Facades:** Using a Gateway Server to wrap various backend services (REST APIs, databases, or legacy systems) into a single cohesive facade. For example, a group might dynamically expose a mix of tools from different MCP servers, APIs, REST services, etc.
55
+
## Protocol Considerations
80
56
81
-
-**Dynamic Orchestration:** Supporting the ability to add or remove groups and tools without restarting the server, which is essential for high-availability gateway environments.
57
+
#### New Primitive or Extension?
82
58
83
-
-**Task Management:** Grouping the new Task primitive alongside tools and prompts to manage long-running workflows, sequencing, and concurrency.
59
+
Groups are implemented as new MCP primitive, alongside the existing ones (i.e., tools, resources, prompts, and tasks). The new primitive will have a similar schema, list method, and list changed notification. Additionally, all MCP primitives, including groups, use a new reserved `_meta` key to list the groups to which they belong. An alternative proposal for implementing groups as an extension over existing primitives was disregarded since it was considered unintuitive.
84
60
85
-
#### Governance & Development Lifecycle
61
+
#### Membership Constraints
86
62
87
-
-**Governance and Security:** Providing a standardized mechanism for server-side governance of who can access specific sets of tools and resources.
63
+
This SEP recommends flexible grouping membership given diversity in potential use-cases:
88
64
89
-
-**Ecosystem Tooling:** Supporting broader developer workflows such as debugging, automated testing, and documentation by grouping related diagnostic tools together.
65
+
1. Primitives **can** belong to multiple groups. This is crucial for key use-cases e.g., if grouping tools by specific workflows, a `spell_check` tool might appear in both `compose_email` and `compose_document` groups.
66
+
2. Groups **may** belong to multiple groups. This results in overlapping sets, **not a hierarchy**.
67
+
3. Clients **may** interpret transitive relationships based on their specific use-cases (see [reference implementation](#transitivity-example)).
68
+
4. Although servers are responsible for avoiding invalid groupings such as self or cyclic memberships, SDKs can help. We argue the maintenance overhead would be modest and consider it acceptable for the additional flexibility, since such features are already implemented in most language compilers / interpreters.
90
69
91
70
## Specification
92
71
93
-
**Recommendation:** Groups are implemented as new MCP primitive, alongside the existing ones (i.e., tools, resources, prompts, and tasks). The new primitive will have a similar schema, list method, and list changed notification. Additionally, all MCP primitives, including groups, use a new reserved `_meta` key to list the groups to which they belong.
94
-
95
72
### Capability
96
73
97
74
Servers that support groups MUST declare the capability during initialization, including whether list change notifications are supported. Group lists can change at runtime, and so support for listChanged notifications for each is included.
@@ -262,16 +239,14 @@ This specification proposal was selected for its ease of understanding since it
262
239
This idea was discarded because it could lead to backward compatibility issues. For instance, if a server returned a tool, resource, etc, with this property to an older client which validated it against a strict schema that did not contain this property, it would most likely cause an error.
263
240
Since this proposal spans all primitives, such a compatibility failure would be unacceptable. We could require SDK developers to implement a "feature flag" that suppresses the top-level groups field in all primitives after protocol version negotiation takes place if there is a mismatch. However, that would be more effort and complexity than simply using a reserved metadata key to pass the primitive's group list, which older clients would simply ignore.
264
241
265
-
-**Primitive's group list as an array of Group instances not names:** A variation of the proposed specification, but the schema would reference the Groups definition instead of declaring a string (group name). This means that full Group instances would appear in the primitive's group list, significantly increasing the token count when passed to an LLM without modification. Also, beacuse groups belong to other groups, every child of a given group would carry a duplicate of the parent instance. There was discussion of mitigating the duplication on the line using libraries that perform a marshalling on send/receive, replacing the parent with a pointer to a single copy of the parent instance. This would put an unnecessary burden on SDK developers for no clear benefit, when a client can easily look up a group by name in its cached `groups/list` result.
242
+
-**Primitive's group list as an array of Group instances not names:** A variation of the proposed specification, but the schema would reference the Groups definition instead of declaring a string (group name). This means that full Group instances would appear in the primitive's group list, significantly increasing the token count when passed to an LLM without modification. Also, because groups belong to other groups, every child of a given group would carry a duplicate of the parent instance. There was discussion of mitigating the duplication on the line using libraries that perform a marshalling on send/receive, replacing the parent with a pointer to a single copy of the parent instance. This would put an unnecessary burden on SDK developers for no clear benefit, when a client can easily look up a group by name in its cached `groups/list` result.
266
243
More information on this approach can be found in @scottslewis's [proposal](https://github.com/modelcontextprotocol/modelcontextprotocol/discussions/1567).
267
244
268
245
-**No Grouping of Groups** - A variation of the proposed specification, but Groups cannot have a group list. Avoids any worry of graphs — e.g., a group belonging to itself or to a child. Makes groups a flat list.
269
246
270
247
## Security Implications
271
248
272
-
No serious implications identified.
273
-
274
-
We do wish to point out that use of groups for controlling access to a set of primitives, while a stated use case, could have security implications if groups change dynamically.
249
+
No new implications identified. Offering group information to LLMs presents challenges similar to other primitives, and if servers use groups for access control, that might raise additional implications.
275
250
276
251
## Reference Implementation
277
252
@@ -282,8 +257,46 @@ The reference implementation's example client and server demonstrate how groups,
282
257
283
258
Note: Tasks are not included in the example as they are ephemeral, but the SDK changes do support grouping of tasks.
284
259
260
+
### Transitivity Example
261
+
262
+
- In the TypeScript reference implementation, the `communications` group contains `email` and `calendar` groups.
263
+
- When listing the primitives in the `communications` group, it displays the contents of both children.
264
+
- So `email_thank_contributor` would appear in both `email` and `communications`.
265
+
- Some clients might wish to only show direct children of a group.
0 commit comments