​

Abstract

​

Motivation

• Dispersed content: Proposal content was scattered across GitHub issues, linked documents, and pull requests, making review and archival difficult.
• Difficult collaboration: Maintaining long-form specifications in issue bodies made iterative edits and multi-contributor collaboration harder.
• Limited version control: GitHub issues don’t provide the same version control capabilities as Git-managed files.
• Unclear status management: The process lacked clear mechanisms for tracking status transitions and ensuring consistency between different sources of truth.

• Keeping every SEP in version control alongside the specification itself
• Providing Git’s built-in review tooling, history, and searchability
• Linking SEP numbers to pull requests to eliminate manual bookkeeping
• Surfacing all discussion in the pull request thread
• Using PR labels in conjunction with file status for better discoverability

​

Specification

​

1. Canonical Location

• Every SEP lives in seps/{NUMBER}-{slug}.md in the specification repository
• The SEP number is always the pull request number that introduces the SEP file
• The seps/ directory serves as the single source of truth for all SEPs

​

2. Author Workflow

1. Draft the proposal in seps/0000-{slug}.md using 0000 as a placeholder number
2. Open a pull request containing the draft SEP and any supporting materials
3. Request a sponsor from the Maintainers list; tag potential sponsors from MAINTAINERS.md
4. After the PR number is known, amend the commit to rename the file to {PR-number}-{slug}.md and update the header (SEP-{PR-number} and PR: #{PR-number})
5. Wait for sponsor assignment: Once a sponsor agrees, they will assign themselves and update the status to Draft

​

3. Sponsor Responsibilities

• Reviewing the proposal and providing constructive feedback
• Requesting changes based on community input
• Managing status transitions by:
  • Ensuring that the Status field in the SEP markdown file is accurate
  • Applying matching PR labels to keep them in sync with the file status
  • Communicating status changes via PR comments
• Initiating formal review when the SEP is ready (moving from Draft to In-Review)
• Raising to Core-Maintainers ensuring the SEP is presented at the Core Maintainer meeting and that author and sponsor present.
• Ensuring quality standards are met before advancing the proposal
• Tracking implementation progress and ensuring reference implementations are complete before Final status

​

4. Review Flow

​

5. Documentation

• docs/community/sep-guidelines.mdx serves as the contributor-facing instructions
• seps/README.md provides the concise reference for formatting, naming, sponsor responsibilities, and acceptance criteria
• Both documents must reflect this workflow and be kept in sync

​

6. SEP File Structure

# SEP-{NUMBER}: {Title}

- **Status**: Draft | In-Review | Accepted | Rejected | Withdrawn | Final | Superseded | Dormant
- **Type**: Standards Track | Informational | Process
- **Created**: YYYY-MM-DD
- **Author(s)**: Name <email> (@github-username)
- **Sponsor**: @github-username (or "None" if seeking sponsor)
- **PR**: https://github.com/modelcontextprotocol/specification/pull/{NUMBER}

## Abstract

## Motivation

## Specification

## Rationale

## Backward Compatibility

## Security Implications

## Reference Implementation

​

7. Status Management via PR Labels

• Sponsors must apply PR labels that match the SEP status (draft, in-review, accepted, final, etc.)
• Both the markdown Status field and PR labels should be kept in sync
• The markdown file serves as the canonical record (versioned with the proposal)
• PR labels enable easy filtering and searching for SEPs by status
• Only sponsors should modify status fields and labels; authors should request changes through their sponsor

​

8. Legacy Considerations

• Contributors may optionally open a GitHub Issue for early discussion, but the authoritative SEP text lives in seps/
• Issues should link to the relevant file once a pull request exists
• SEP numbers are derived from PR numbers, not issue numbers

​

Rationale

​

Why File-Based?

• Provides built-in version control via Git
• Enables standard code review workflows
• Maintains clear history of all changes
• Supports multi-contributor collaboration
• Integrates naturally with the specification repository

​

Why PR Numbers?

• Eliminates race conditions around manual numbering
• Creates natural traceability between proposal and discussion
• Prevents number conflicts
• Simplifies the contribution process
• Maintains a single discussion thread for review

​

Why PR Labels?

• Enables quick filtering of SEPs by status without opening files
• Provides immediate visibility of SEP states in PR lists
• Supports GitHub’s search and filter capabilities
• Complements the canonical markdown status field
• Reduces friction for maintainers managing multiple SEPs

​

Making This the Primary Process

• Reduces cognitive overhead for new contributors
• Ensures consistency in the SEP corpus
• Simplifies maintenance for sponsors
• Aligns with industry best practices

​

Backward Compatibility

• Existing issue-based SEPs remain valid and require no migration
• Historical GitHub Issue links continue to work
• Future SEPs should reference the new file locations in seps/
• Maintainers may optionally backfill historical SEPs into seps/ for archival purposes

​

Security Implications

​

Reference Implementation

• This pull request (#1850) implements the canonical instructions in both seps/README.md and docs/community/sep-guidelines.mdx
• The process has been updated to reflect the PR-based workflow with status management via labels
• This SEP document itself serves as an example of the new format

​

Vote