modelcontextprotocol · nickcoai · Nov 12, 2025 · Nov 12, 2025 · Nov 12, 2025 · Nov 12, 2025
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,7 @@
+{
+    "workbench.colorCustomizations": {
+        "activityBar.background": "#312E14",
+        "titleBar.activeBackground": "#45411C",
+        "titleBar.activeForeground": "#FBFAF4"
+    }
+}
@@ -5,11 +5,13 @@ description: Specification Enhancement Proposal (SEP) guidelines for proposing c
 
 ## What is a SEP?
 
+The canonical SEP workflow keeps every proposal as a Markdown file in the `seps/` directory of this repository; the process below mirrors `seps/README.md` and the corresponding SEP that established this workflow.
+
 SEP stands for Specification Enhancement Proposal. A SEP is a design document providing information to the MCP community, or describing a new feature for the Model Context Protocol or its processes or environment. The SEP should provide a concise technical specification of the feature and a rationale for the feature.
 
 We intend SEPs to be the primary mechanisms for proposing major new features, for collecting community input on an issue, and for documenting the design decisions that have gone into MCP. The SEP author is responsible for building consensus within the community and documenting dissenting opinions.
 
-Because the SEPs are maintained as text files in a versioned repository (GitHub Issues), their revision history is the historical record of the feature proposal.
+Because SEPs are Markdown files stored in the `seps/` directory of the specification repository, Git provides the authoritative revision history for every proposal.
 
 ## What qualifies a SEP?
 
@@ -42,14 +44,17 @@ Each SEP must have an **SEP author** -- someone who writes the SEP using the sty
 
 ### SEP Workflow
 
-SEPs should be submitted as a GitHub Issue in the [specification repository](https://github.com/modelcontextprotocol/modelcontextprotocol). The standard SEP workflow is:
+SEPs are submitted as pull requests that add a Markdown file to the `seps/` directory in the [specification repository](https://github.com/modelcontextprotocol/modelcontextprotocol). The standard workflow is:
+
+1. Draft the proposal as `seps/DRAFT-your-feature.md`, following the [SEP format](#sep-format) including header metadata (status, type, created date, author, sponsor placeholder, and PR reference).
+2. Open a pull request containing the draft SEP (and any supporting material). The pull request discussion replaces the historical GitHub Issue thread, and the SEP should start with status `Draft`.
+3. Find a Core Maintainer or Maintainer to sponsor your proposal. Tag potential sponsors from [MAINTAINERS.md](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/MAINTAINERS.md). Once someone agrees, record their handle in the `Sponsor` field.
+4. After the pull request number is known, rename the file to `seps/{PR-number}-{slug}.md` and update the title/header to `SEP-{PR-number}` along with `PR: #{PR-number}`.
+5. Work with your sponsor to iterate on the proposal. Sponsors move the SEP through `Draft → In-Review → Accepted → Final` by updating the `Status` field in the file and using matching pull request labels.
+6. Provide or link to a reference implementation before requesting `Final` status. The pull request containing the SEP should include links to any tracking issues or additional PRs needed to implement the change.
+
 
-1. You, the SEP author, create a [well-formatted](#sep-format) GitHub Issue with the `SEP` and `proposal` tags. The SEP number is the same as the GitHub Issue number, the two can be used interchangeably.
-2. Find a Core Maintainer or Maintainer to sponsor your proposal. Core Maintainers and Maintainers will regularly go over the list of open proposals to determine which proposals to sponsor. You can tag relevant maintainers from [the maintainer list](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/MAINTAINERS.md) in your proposal.
-3. Once a sponsor is found, the GitHub Issue is assigned to the sponsor. The sponsor will add the `draft` tag, ensure the SEP number is in the title, and assign a milestone.
-4. The sponsor will informally review the proposal and may request changes based on community feedback. When ready for formal review, the sponsor will add the `in-review` tag.
-5. After the `in-review` tag is added, the SEP enters formal review by the Core Maintainers team. The SEP may be accepted, rejected, or returned for revision.
-6. If the SEP has not found a sponsor within three months, Core Maintainers may close the SEP as `dormant`.
+You can still open a GitHub Issue or discussion for early feedback, but the Markdown file in `seps/` is the single source of truth for every SEP once the pull request exists.
 
 ### SEP Format
 
@@ -66,17 +71,15 @@ Each SEP should have the following parts:
 
 ### SEP States
 
-SEPs can be one one of the following states
+SEPs move through the following states, which are recorded in the SEP header:
 
-- `proposal`: SEP proposal without a sponsor.
 - `draft`: SEP proposal with a sponsor.
-- `in-review`: SEP proposal ready for review.
+- `review`: SEP proposal ready for review.
 - `accepted`: SEP accepted by Core Maintainers, but still requires final wording and reference implementation.
 - `rejected`: SEP rejected by Core Maintainers.
 - `withdrawn`: SEP withdrawn.
 - `final`: SEP finalized.
 - `superseded`: SEP has been replaced by a newer SEP.
-- `dormant`: SEP that has not found sponsors and was subsequently closed.
 
 ### SEP Review & Resolution
 
@@ -94,7 +97,7 @@ A SEP can also be "Rejected" or "Withdrawn". A SEP that is "Withdrawn" may be re
 
 ## Reporting SEP Bugs, or Submitting SEP Updates
 
-How you report a bug, or submit a SEP update depends on several factors, such as the maturity of the SEP, the preferences of the SEP author, and the nature of your comments. For SEPs not yet reaching `final` state, it's probably best to send your comments and changes directly to the SEP author. Once SEP is finalized, you may want to submit corrections as a GitHub comment on the issue or pull request to the reference implementation.
+How you report a bug, or submit a SEP update depends on several factors, such as the maturity of the SEP, the preferences of the SEP author, and the nature of your comments. For SEPs that have not yet reached `Final`, comment on the active pull request or open a follow-up pull request editing the SEP file directly. Once a SEP is finalized, submit corrections through a new pull request against the SEP file or the relevant reference implementation.
 
 ## Transferring SEP Ownership
 

diff --git a/seps/1802-file-based-sep-workflow.md b/seps/1802-file-based-sep-workflow.md
@@ -0,0 +1,64 @@
+# SEP-1802: File-Based SEP Workflow
+
+- **Status**: Draft
+- **Type**: Process
+- **Created**: 2025-11-12
+- **Author(s)**: Nick C. (@nickcoai)
+- **Sponsor**: @nickcoai
+- **PR**: #1802
+
+## Abstract
+
+This SEP formalizes the Markdown-file-based SEP workflow that stores proposals in the `seps/` directory of the Model Context Protocol repository. The workflow assigns SEP numbers from pull requests, keeps each proposal's history in Git, and removes the need to manage GitHub Issues as the primary source of truth for SEPs. This document makes the file-based process the canonical way to author, review, and accept SEPs while still allowing GitHub Issues for early idea discussion when helpful.
+
+## Motivation
+
+The issue-based SEP process introduced friction:
+
+- Proposal content was dispersed between issues, linked documents, and pull requests, which complicated review and archival.
+- SEP numbers had to be coordinated manually when proposals moved between issues and pull requests.
+- Maintaining long-form specifications inside issue bodies made iterative edits harder, especially when multiple contributors collaborated.
+
+A file-based workflow keeps every SEP in version control alongside the specification itself. Git provides built-in review tooling, history, and searchability. Linking SEP numbers to pull requests removes manual bookkeeping while still surfacing discussion in the pull request thread.
+
+## Specification
+
+1. **Canonical Location**
+   - Every SEP lives in `seps/{NUMBER}-{slug}.md`.
+   - The SEP number is always the pull request number that introduces the SEP file.
+
+2. **Author Workflow**
+   - Draft the proposal in `seps/DRAFT-{slug}.md`.
+   - Open a pull request containing the draft SEP and any supporting materials.
+   - Request a sponsor from the Maintainers list; record the sponsor in the SEP header once confirmed.
+   - After the pull request number is known, rename the file to `{PR}-{slug}.md` and update the header (`SEP-{PR}` and `PR: #{PR}`).
+
+3. **Review Flow**
+   - Status progression is `Draft → In-Review → Accepted → Final`, with optional `Rejected`, `Withdrawn`, or `Superseded`.
+   - Sponsors manage status updates directly in the SEP file and in the pull request labels.
+   - Reference implementations are tracked via linked pull requests or issues and must be complete before marking a SEP as `Final`.
+
+4. **Documentation Updates**
+   - `docs/community/sep-guidelines.mdx` serves as the contributor-facing instructions and must reflect this workflow.
+   - `seps/README.md` remains the concise reference for formatting, naming, sponsor responsibilities, and acceptance criteria.
+
+5. **Legacy Issue-Based Flow**
+   - 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; numbers are no longer derived from issues.
+
+## Rationale
+
+Storing SEPs as files keeps authoritative specs versioned with the code, which mirrors successful processes used by PEPs and other standards bodies. Using pull request numbers eliminates race conditions around manual numbering while keeping a single discussion thread for review. Maintaining two overlapping canonical processes risked divergence; naming the file-based approach as primary reduces confusion for contributors and maintainers.
+
+## Backward Compatibility
+
+- Existing issue-based SEPs remain valid and require no migration, though maintainers may optionally backfill them into `seps/` for archival.
+- Links to historical GitHub Issues continue to work; future SEPs should link to the new file locations.
+
+## Security Implications
+
+No new security considerations beyond the standard code-review process.
+
+## Reference Implementation
+
+- This pull request adds the canonical instructions in both `seps/README.md` and `docs/community/sep-guidelines.mdx`.
diff --git a/seps/README.md b/seps/README.md
@@ -1,6 +1,6 @@
 # Specification Enhancement Proposals (SEPs)
 
-> **Experimental**: This is an experimental alternative method for creating SEPs. The default method remains using GitHub issues as described at https://modelcontextprotocol.io/community/sep-guidelines.
+This directory now holds the canonical, file-based SEP workflow described in [SEP-1802: File-Based SEP Workflow](./1802-file-based-sep-workflow.md) until it receives its permanent number. The contributor-facing guidelines at https://modelcontextprotocol.io/community/sep-guidelines mirror the steps below.
 
 ## Overview
 
@@ -22,15 +22,11 @@ Examples:
 
 ## Creating a New SEP
 
-1. **Draft your SEP** as a markdown file with a temporary name (e.g., `DRAFT-your-feature.md`)
-
-2. **Create a pull request** adding your SEP file to the `seps/` directory
-
-3. **Rename your file** to use the PR number as the SEP number (e.g., PR #1850 → `1850-your-feature.md`)
-
-4. **Update the SEP header** to reference the correct number
-
-5. **Find a Sponsor** - A Core Maintainer or Maintainer who will shepherd your proposal through review
+1. **Draft your SEP** inside `seps/` with a temporary filename such as `DRAFT-your-feature.md`.
+2. **Open a pull request** that includes the draft and any supporting material.
+3. **Find a Sponsor** — tag potential sponsors from [`MAINTAINERS.md`](../MAINTAINERS.md) and record the confirmed sponsor in the SEP header.
+4. **Rename the file after the PR number** once the pull request exists (`PR #1850 → seps/1850-your-feature.md`) and update the header to `SEP-1850`.
+5. **Iterate in the pull request** until the sponsor promotes the proposal through `Draft → In-Review → Accepted → Final`.
 
 ## SEP File Structure
 
@@ -121,4 +117,4 @@ Using the PR number as the SEP number:
 
 ## Relationship to Issue-Based SEPs
 
-This file-based approach complements the existing issue-based SEP process. Contributors may choose either method based on preference. The canonical SEP guidelines remain at https://modelcontextprotocol.io/community/sep-guidelines
+GitHub Issues remain useful for early discussion or coordinating reference implementations, but the file inside `seps/` is the single source of truth for every SEP. Authors who start in an issue should link to the draft file once a pull request exists, and the SEP number must always match the pull request number that first introduces the file.