Drafting a Specification Enhancement Proposal

This skill guides an author through producing a SEP that conforms to docs/community/sep-guidelines.mdx and seps/TEMPLATE.md. Work through the phases in order — do not start writing the draft until the gate, interview, and research are complete.

Prerequisite: This skill must be run from a local clone of modelcontextprotocol/modelcontextprotocol or a fork of it. Before doing anything else:

1. Verify seps/TEMPLATE.md exists in the working directory. If it does not, stop and tell the user to run gh repo fork modelcontextprotocol/modelcontextprotocol --clone (or, if they are a maintainer with push access, clone the upstream repo directly) and re-run from its root.
2. Determine the canonical remote — the remote that points at modelcontextprotocol/modelcontextprotocol itself, not a fork. Inspect git remote -v: if origin points at the canonical repo, the canonical remote is origin. If origin points at a fork, look for an upstream remote; if none exists, add it with git remote add upstream https://github.com/modelcontextprotocol/modelcontextprotocol.git. The canonical remote is then upstream.
3. Run git fetch {canonical} and ensure local main is current with {canonical}/main so the research phases see up-to-date SEPs, schema, and MAINTAINERS.md.

Phase 6 references {canonical} for the branch start-point and origin for the push target; these are the same remote for maintainers and different remotes for fork-based contributors.

Discuss before drafting. The SEP guidelines advise raising an idea in Discord or a Working Group or Interest Group meeting before opening a SEP. If the user has not discussed this idea anywhere yet, say so explicitly and ask whether they want to proceed anyway. A cold SEP is valid but more likely to stall — and if no sponsor is found within 6 months, Core Maintainers may close the PR and mark the SEP dormant.

The SEP author is responsible for building consensus within the community and documenting dissenting opinions — capture both as you go.

Phase 1 — Gate

Before any interview or research, decide from the one-line {idea} whether this is SEP-worthy.

Redirect (do not proceed) if the idea is:

• A bug fix or typo correction
• A documentation clarification
• Adding examples to an existing feature
• A minor schema fix that does not change behavior

For these, point the user at a regular pull request or the bug-report issue form instead and stop.

Proceed if the idea is:

• A new protocol feature or a change to an existing one
• A breaking change
• A governance or process change
• Anything controversial enough to need a design document and historical record

When unsure, the guidelines say to ask in Discord before starting significant work — point the user there rather than burning time on a draft that may not be SEP-worthy.

Phase 2 — Interview

Ask the user these six questions before touching any files. The answers feed directly into the draft.

1. SEP type? Standards Track (core protocol feature), Extensions Track (extension rather than core — see SEP-2133), Informational (guidelines/design notes), or Process (governance/workflow change). Most SEPs are Standards Track.
   • If Extensions Track: also ask which Working Group and Extension Maintainers will be responsible for the extension — SEP-2133 makes this a hard requirement, and an Extensions Track SEP MUST have at least one reference implementation in an official SDK prior to review.
2. Is this a breaking change? Determines how much weight the Backward Compatibility section carries.
3. Prototype status? There are two distinct gates: a working prototype is required before a SEP can be accepted, and a complete reference implementation is required before it can reach Final. The prototype proves feasibility — it doesn't need to be production-ready, but it must be runnable, not pseudocode. Does one exist, is one in progress, or is it still TBD?
4. Where was this discussed? Discord thread, Working Group or Interest Group meeting, GitHub Discussion — the link becomes the consensus evidence in the Rationale section. If the answer is "nowhere," flag it (see above).
5. Author and sponsor? Capture the author's name, email, and GitHub username for the Author(s) preamble field. Then ask about a sponsor: a SEP needs a Core Maintainer or Maintainer sponsor to enter draft status — the sponsor is what grants it. Until a sponsor signs on, the SEP sits in an "awaiting sponsor" state (Core Maintainers may close it as dormant after 6 months). If the user has a sponsor lined up, capture their GitHub username (without the @ — gh pr create --reviewer expects a bare handle). If not, the preamble should read Sponsor: None and the finding-a-sponsor guidance from docs/community/sep-guidelines.mdx applies: tag 1-2 relevant maintainers from MAINTAINERS.md on the PR, share in the relevant Discord channel, and if there's no response in two weeks ask in #general.
6. Security implications? Does this proposal touch the attack surface — new transports, auth flows, data exposure, trust boundaries? The Security Implications section is required in seps/TEMPLATE.md; even "none identified" needs to be stated explicitly with reasoning.

Phase 3 — Research

Run each step and capture the findings — they feed directly into the draft sections.

1. Current spec coverage

Use the SearchModelContextProtocol tool on the mcp-docs MCP server (if available) to find what the spec already says about this area. If that server is not configured, fall back to grep -rn "{keyword}" docs/specification/draft/. This becomes the "why is the current spec inadequate" half of the Motivation section.

2. Prior art on GitHub

Invoke /search-mcp-github {idea}. Look for:

• Merged PRs that touched the same surface
• Closed issues that asked for this (or something close)
• Prior discussions where maintainers set direction or rejected a similar approach

If a similar proposal was already rejected, that context is load-bearing — the new SEP needs to explain what changed.

3. Overlapping SEPs

grep -l -i "{keyword}" seps/*.md

Pick one or two keywords from the idea. If an existing SEP covers this area, the right move is usually to extend or supersede it rather than file a parallel proposal. Read any matches before continuing.

4. Design-principle and roadmap fit

Read docs/community/design-principles.mdx and docs/development/roadmap.mdx. Identify which principles the proposal serves and which it is in tension with. Check whether the proposal aligns with current Core Maintainer priorities reflected in the roadmap — proposals outside current priorities are more likely to face delays in review. Both findings go in the Rationale section.

5. Schema touch-points

grep -n "{affected-type}" schema/draft/schema.ts

For Standards Track and Extensions Track SEPs, find the concrete types the spec change would add or modify. Reference these by name in the Specification section.

6. Exemplar SEPs

grep -l "Status.*Final" seps/*.md | head -3

Read two or three Final-status SEPs to see what a well-filled section looks like in practice. Match their level of detail.

Phase 4 — Draft

Read seps/TEMPLATE.md and fill each section in order. Write to seps/0000-{slug}.md where {slug} is a lowercase, hyphenated version of the idea trimmed to ~50 characters (match the pattern of existing seps/*.md filenames). The 0000 placeholder is the documented convention from the SEP guidelines.

Everything above the --- rule in the template is required — write "none identified" with reasoning rather than omitting a section. Headings under "Additional Optional Sections" are optional.

Preamble notes:

• Status: — leave blank or omit. Authors should request status changes through their sponsor rather than setting the field themselves.
• Type: — from Q1: Standards Track | Informational | Process | Extensions Track.
• Created: — today's date in YYYY-MM-DD format.
• Author(s): — Name <email> (@github-username) from Q5.
• Sponsor: — @github-username from Q5, or the literal None.
• PR: — set to https://github.com/modelcontextprotocol/modelcontextprotocol/pull/{NUMBER} (the {NUMBER} placeholder gets filled in Phase 6).

Phase 5 — Checkpoint

Tell the user:

• The path to the draft file
• A one-line summary of what went into each section

Then ask: open a draft PR now, or stop here so they can edit the file first?

Do not proceed to Phase 6 without a yes.

Phase 6 — Open PR (only if the user says yes)

SEP-1850 documents an amend-based flow: open the PR with the 0000- placeholder, then immediately rename and amend so the final history is a single commit with the real number.

git fetch {canonical}
git checkout -b sep/{slug} {canonical}/main
git add seps/0000-{slug}.md
git commit -m "SEP: {title}"
git push -u origin sep/{slug}
gh pr create --repo modelcontextprotocol/modelcontextprotocol --base main \
  --title "SEP: {title}" --body "{one-paragraph summary}" --draft --reviewer {sponsor-username}

{canonical} is the remote established in the Prerequisite (either origin or upstream); origin is always the push target. If the sep/{slug} branch already exists (e.g., re-entering this phase after a checkpoint pause), reuse it instead of creating a new one. Omit --reviewer if Q5 answered None. If gh prompts for a default repository, run gh repo set-default modelcontextprotocol/modelcontextprotocol and retry.

Capture the PR number {N} from gh pr create output, then backfill:

git mv seps/0000-{slug}.md seps/{N}-{slug}.md
# edit the file: replace SEP-{NUMBER} with SEP-{N} in the title line,
# fill the PR link in the preamble
npm run generate:seps
npm run format:docs
git add seps/{N}-{slug}.md docs/seps/ docs/docs.json
git commit --amend --no-edit
git push --force-with-lease

The amend keeps the rename in one commit per SEP-1850. npm run generate:seps renders docs/seps/{N}-{slug}.mdx and updates docs/docs.json (required for the render-seps.yml CI check), and npm run format:docs keeps the markdown-format.yml check green.

If Q5 answered None, the next step after the PR is open is finding a sponsor — tag 1-2 relevant maintainers from MAINTAINERS.md on the PR and share it in the relevant Discord channel. The 6-month clock starts now.