Skip to content

SEP 2084: Primitive Groups (Schema Changes)#2110

Closed
chughtapan wants to merge 11 commits intomodelcontextprotocol:mainfrom
chughtapan:feature/primitive-groups
Closed

SEP 2084: Primitive Groups (Schema Changes)#2110
chughtapan wants to merge 11 commits intomodelcontextprotocol:mainfrom
chughtapan:feature/primitive-groups

Conversation

@chughtapan
Copy link
Copy Markdown
Contributor

Description

Schema and documentation implementation for SEP 2084 (Primitive Groups). This adds Groups as a new MCP primitive, enabling organization of tools, prompts, resources, tasks, and groups into named collections.

Changes

Schema (schema/draft/schema.ts)

  • Add groups capability to ServerCapabilities with listChanged notification support
  • Add ListGroupsRequest for paginated group discovery
  • Add ListGroupsResult and ListGroupsResultResponse
  • Add GroupListChangedNotification for group list change notifications
  • Add Group interface extending BaseMetadata and Icons
  • Update ClientRequest, ServerNotification, and ServerResult union types

Documentation

  • Add docs/specification/draft/server/groups.mdx - Full specification page
  • Update docs/specification/draft/server/index.mdx - Add Groups to primitives overview
  • Update docs/specification/draft/basic/index.mdx - Document io.modelcontextprotocol/groups reserved _meta key
  • Update docs/docs.json - Add Groups to sidebar navigation

Examples

  • Group/basic-group.json
  • Group/group-with-nested-groups.json
  • ListGroupsRequest/list-groups-request.json
  • ListGroupsResult/groups-list-with-cursor.json
  • ListGroupsResultResponse/list-groups-result-response.json
  • GroupListChangedNotification/groups-list-changed.json
  • ServerCapabilities/groups-minimum-baseline-support.json
  • ServerCapabilities/groups-list-changed-notifications.json

Related

Implement Groups to organize tools, prompts, resources, tasks, and groups
into named collections. This enables:
- Client-side filtering of primitives by group
- Progressive disclosure for large sets of primitives
- Access control boundaries at the group level

Schema changes:
- Add `groups` capability to ServerCapabilities
- Add ListGroupsRequest, ListGroupsResult, Group interfaces
- Add GroupListChangedNotification for list changes

Documentation:
- Add groups.mdx specification page
- Update server overview to include Groups
- Document io.modelcontextprotocol/groups _meta key

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@chughtapan chughtapan requested a review from a team as a code owner January 18, 2026 02:56
chughtapan added a commit to chughtapan/modelcontextprotocol that referenced this pull request Jan 18, 2026
- Add link to schema changes PR modelcontextprotocol#2110
- Reorder Alternatives Considered (Resources first)
- Fix prettier formatting

Co-Authored-By: Claude Opus 4.5 <[email protected]>
@cliffhall cliffhall mentioned this pull request Jan 18, 2026
9 tasks
Comment on lines +204 to +206
#### Group Names

TBD: Maybe similar to tool names?
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be a separate PR to move the name rules to a separate section, so that all primitive names are governed by the same rules.

}
```

## Primitive Group Membership
Copy link
Copy Markdown

@Yuan325 Yuan325 Jan 31, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With this, I'm assuming that all the tool that belongs to a certain group will need to include the _meta key io.modelcontextprotocol/groups with all the group memberships that they belong to? Including all the "parent-group" as well?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tools, resources, resource templates, prompts, tasks, and groups themselves should include the groups they are an explicit direct member of. It is up to the client to decide how deep to go for displaying. In the reference implementation, the example client has a depth parameter that can be adjusted.

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.

@cliffhall
Copy link
Copy Markdown
Member

Closing, as SEP-2084 was rejected.

@cliffhall cliffhall closed this Feb 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants