Skip to content

SEP-2084: Primitive Grouping#2084

Closed
chughtapan wants to merge 84 commits intomodelcontextprotocol:mainfrom
chughtapan:groups
Closed

SEP-2084: Primitive Grouping#2084
chughtapan wants to merge 84 commits intomodelcontextprotocol:mainfrom
chughtapan:groups

Conversation

@chughtapan
Copy link
Copy Markdown
Contributor

@chughtapan chughtapan commented Jan 14, 2026

Description

This SEP proposes Groups, a new server capability and primitive, to organize tools, prompts, resources, tasks, and groups themselves, into named collections.

Motivation and Context

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.

An example would be client-side filtering by group, where a client allows the user to choose which groups to interact with and which to ignore. Only primitives included in the selected groups would be presented to an LLM, reducing context overload by omitting functionality that the user knows isn't relevant to the task at hand.

Reference Implementation

  • Spec and docs changes: Draft PR
  • Fully implemented and unit tested in Typescript SDK.
    • Includes documented client and server examples.
    • Check out the TS SDK Draft PR for details.

The reference implementation's example client and server demonstrate how groups, tools, prompts, and resources can be grouped on the server, and the client can filter them by group. It manually demonstrates how an agent using the server could easily reduce the tokens placed into an LLM's context by only including the primitives in one or more groups rather than providing the full list.

Note: For the sake of simplicity, Tasks and Resource Templates are not included in the demo, but the reference implementation supports grouping of both.

Group-aware Client / Server Example

The Menu

=======================
Groups filtering client
=======================
Starting stdio server: pnpm tsx /Users/cliffhall/Projects/mcp-typescript-sdk/examples/server/src/groupsExample.ts
Groups example MCP server running on stdio.

Fetched: 7 groups, 10 tools, 5 resources, 5 prompts.
Available groups: calendar, communications, documents, email, spreadsheets, todos, work
Group display depth: 2 (max: 2)

Commands:
 all (a)                 List all groups, tools, resources, and prompts
 depth (d) [n]           Show or set group display depth (1..max)
 groups (g/enter)        List available groups 
 help (h)                Show this help
 exit (e)                Quit
 <groups...>             Filter by one or more groups (comma or space-separated)

Enter a command or a list of groups to filter by: 

List All Primitives

This is an exhaustive list of all the primitives defined by the example.

Enter a command or a list of groups to filter by: all

Groups:
- calendar — Scheduling operations and event management.
- communications — Tools, resources, and prompts related to messaging and scheduling.
- documents — Document drafting, editing, and summarization workflows.
- email — Email composition and inbox-oriented operations.
- spreadsheets — Spreadsheet-like operations: create sheets, add rows, and do quick calculations.
- todos — Task capture and lightweight task management.
- work — Tools, resources, and prompts related to day-to-day work.

Tools:
- calendar_create_event — Create a calendar event.
- calendar_list_upcoming — List upcoming calendar events (demo).
- documents_create — Create a document draft.
- documents_summarize — Summarize a document (demo).
- email_search_inbox — Search the inbox by query string.
- email_send — Send an email message.
- spreadsheets_add_row — Add a row to a spreadsheet.
- spreadsheets_create — Create a new spreadsheet.
- todos_add — Add a todo item.
- todos_complete — Mark a todo item complete.

Resources:
- calendar_overview — A short overview of calendar-related concepts and workflows.
- documents_overview — A short overview of document workflows.
- email_overview — A short overview of email etiquette and structure.
- spreadsheets_overview — A short overview of spreadsheet structure and best practices.
- todos_overview — A short overview of task management basics.

Prompts:
- calendar_meeting_agenda — Draft a short agenda for an upcoming meeting.
- documents_write_outline — Create an outline for a document on a topic.
- email_thank_contributor — Compose an email thanking someone for their recent contributions.
- spreadsheets_quick_analysis — Suggest a simple spreadsheet layout for tracking a metric.
- todos_plan_day — Turn a list of tasks into a simple day plan.

Filtering by Group

List a Parent Group's Contents

Enter a group name and see all the primitives it contains. Note that client display depth defaults to 2, so the contents of the parent group and all of its child groups are shown.

Enter a command or a list of groups to filter by: communications

Groups:
- calendar — Scheduling operations and event management.
- email — Email composition and inbox-oriented operations.

Tools:
- calendar_create_event — Create a calendar event.
- calendar_list_upcoming — List upcoming calendar events (demo).
- email_search_inbox — Search the inbox by query string.
- email_send — Send an email message.

Resources:
- calendar_overview — A short overview of calendar-related concepts and workflows.
- email_overview — A short overview of email etiquette and structure.

Prompts:
- calendar_meeting_agenda — Draft a short agenda for an upcoming meeting.
- email_thank_contributor — Compose an email thanking someone for their recent contributions.

Filter all by a leaf group

Listing the contents of a group that has no groups as children.

Enter a command or a list of groups to filter by: todos

Tools:
- todos_add — Add a todo item.
- todos_complete — Mark a todo item complete.

Resources:
- todos_overview — A short overview of task management basics.

Prompts:
- todos_plan_day — Turn a list of tasks into a simple day plan.

Adjusting Client Display Depth

The example server only defines groups to a depth of 2. The client will find the deepest group and default to that number for display depth.

Client Display Depth: 1

Only shows the contents of the group but not of any child groups it contains.

Enter a command or a list of groups to filter by: depth 1
Group display depth set to 1 (max: 2).

Enter a command or a list of groups to filter by: work

Groups:
- documents — Document drafting, editing, and summarization workflows.
- spreadsheets — Spreadsheet-like operations: create sheets, add rows, and do quick calculations.
- todos — Task capture and lightweight task management.

Client Display Depth: 2

Shows the contents of the group and of all child groups it contains.

Enter a command or a list of groups to filter by: d 2
Group display depth set to 2 (max: 2).

Enter a command or a list of groups to filter by: work

Groups:
- documents — Document drafting, editing, and summarization workflows.
- spreadsheets — Spreadsheet-like operations: create sheets, add rows, and do quick calculations.
- todos — Task capture and lightweight task management.

Tools:
- documents_create — Create a document draft.
- documents_summarize — Summarize a document (demo).
- spreadsheets_add_row — Add a row to a spreadsheet.
- spreadsheets_create — Create a new spreadsheet.
- todos_add — Add a todo item.
- todos_complete — Mark a todo item complete.

Resources:
- documents_overview — A short overview of document workflows.
- spreadsheets_overview — A short overview of spreadsheet structure and best practices.
- todos_overview — A short overview of task management basics.

Prompts:
- documents_write_outline — Create an outline for a document on a topic.
- spreadsheets_quick_analysis — Suggest a simple spreadsheet layout for tracking a metric.
- todos_plan_day — Turn a list of tasks into a simple day plan.

Breaking Changes

None

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

Additional context

N/A

This SEP introduces a new server capability called Groups, which organizes MCP primitives into named collections for better client workflows and access control. It includes specifications for group capabilities, schema, discovery methods, and notifications.
Added a new 'groups' property to the primitive definition for better organization of primitives within groups.
Updated the SEP-0000 document to clarify the grouping of primitives and added acknowledgements.
Added a section on security implications to the document.
@cliffhall cliffhall self-assigned this Jan 14, 2026
@cliffhall cliffhall added SEP draft SEP proposal with a sponsor. labels Jan 14, 2026
@localden localden changed the title Primitive Groups SEP: Primitive Groups Jan 14, 2026
@cliffhall cliffhall changed the title SEP: Primitive Groups SEP-2084: Primitive Groups Jan 16, 2026
@cliffhall cliffhall changed the title SEP-2084: Primitive Groups SEP-2084: Primitive Grouping Jan 16, 2026
…cknowledgement with Pat White's github. Tweaked a
@localden localden moved this from In Review to Review Batch in SEP Review Pipeline Feb 4, 2026
@dsp-ant dsp-ant added rejected and removed in-review SEP proposal ready for review. labels Feb 5, 2026
@dsp-ant
Copy link
Copy Markdown
Member

dsp-ant commented Feb 5, 2026

As per #2204, this was rejected by Core Maintainers. The main feedback was that the ecosystem around searching tools is quickly evolving and it's unclear what mechanism is the right one in the longrun. The Core maintainers take a careful stance here to not too early standardize a pattern while the patterns in the de-facto implementations are still evolving. This does not mean that this proposal is not good, it just means it might be too early for it.

@cliffhall cliffhall closed this Feb 5, 2026
@cliffhall cliffhall deleted the groups branch February 5, 2026 17:52
@scottslewis
Copy link
Copy Markdown

The main feedback was that the ecosystem around searching tools is quickly evolving and it's unclear what mechanism is the right one in the longrun

I would like to add that after 4 months of participation (work) by the working group members...e.g. dev community input of use cases, meetings, discussions as referenced, draft creation, experiments, comments above by @bdoyle0182 and others...particularly around/with server-side use cases for primitive grouping, was ignored by the authors of SEP-2084, who emphasized client side search in this proposal...only to be rejected by the core maintainers.

@renatomarinho
Copy link
Copy Markdown

Spec feedback: #2204

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.