Vetrix Docs

MCP spec-drift monitoring

Cadence: quarterly walk (2026-Q3 → 2027-Q2 first cycle). Findings are recorded in a running history, not inlined here. This document is the recurring runbook.

Why this exists

The Model Context Protocol evolves on a roughly quarterly cycle and the Vetrix v1.x server implements a deliberately narrow subset of it. The primary risk this watch guards against is silent capability drift — the spec gaining features (write-tool semantics, sampling, resources, prompts) that Vetrix should consciously decide to ignore or implement rather than ignore by accident, plus the spec's OAuth 2.1 + DCR profile for MCP servers moving out from under Vetrix's already-shipped implementation of it.

This runbook defines the watch. Every quarter the owner walks four artifacts, records a five-field finding, and files a follow-up ticket if a breaking change has landed. If no drift is found the finding is still recorded so the walk is provably done on schedule.

Current state (anchor for the first walk)

This is the baseline the 2026-Q3 walk compares against.

What is pinned Value Where it lives
Go SDK module github.com/modelcontextprotocol/go-sdk v1.6.0 go.mod
Transport Streamable HTTP, spec 2025-11-25 internal/mcp/transport.go (pkg doc, line 7)
Negotiated protocolVersion (initialize) 2025-06-18 server / toolsets-header / transport tests
Methods implemented initialize, tools/list, tools/call internal/mcp/server.go + per-toolset Call dispatch
Methods NOT implemented resources/*, prompts/*, sampling/*, roots/*, logging/* notifications n/a — out of v1 scope (non-goal)
Auth Bearer PAT with acl.ScopeMCPRead (mcp:read); OAuth 2.1 with mandatory PKCE (code_challenge_method=S256 only) and RFC 7591 Dynamic Client Registration (admin-gated via oauth2.dcr.enabled, default off) internal/api/mcp.go gate chain (PAT + OAuth2 bearer, RFC 8707 audience check at gate 3.5); internal/auth/oauth2_register.go, internal/auth/oauth2_metadata.go (RFC 8414 / RFC 9728 discovery)
Per-conn toolset opt-in X-MCP-Toolsets: <name,…> header (Vetrix extension) internal/mcp/transport.go (ToolsetsHeader const)
Untrusted-content boundary NFKC-aware nonce-fenced sentinel wrapper internal/mcp/security.go (WrapUntrusted, ValidatePath)
Session model SDK-minted UUID via Mcp-Session-Id, 5 min idle transport.go DefaultIdleTimeout

The wire-level identifiers (mcp:read scope name, X-MCP-Toolsets header, JSON-RPC method names) are stable contracts for back-compat; the non-goals list above is the explicit set of spec surfaces Vetrix has chosen not to implement in v1 and is the set the quarterly walk re-checks for new motion.

The four artifacts to walk

Each walk inspects all four, in this order. None is optional — a quarter that skips an artifact is not a complete walk.

1. MCP transport spec

  • Source: https://modelcontextprotocol.io/specification (canonical) and the spec repo's CHANGELOG / release tags at https://github.com/modelcontextprotocol/specification.
  • What to look for:
    • Revision date change. The transport doc carries a YYYY-MM-DD revision identifier. internal/mcp/transport.go pins 2025-11-25; any newer revision is drift to record.
    • SSE-only transport status. The original 2024 SSE-only transport is deprecated as of 2025-03-26; confirm it has not been un-deprecated or re-introduced under a new name.
    • New top-level methods. Anything beyond initialize, tools/list, tools/call (e.g. resources/list, prompts/list, sampling/createMessage, roots/list) is a new capability Vetrix has chosen not to implement — record whether the spec now treats it as required vs. optional.
    • protocolVersion negotiation rules. The version string the tests send (2025-06-18) is the contract. If the spec advertises a newer version as required for clients to talk to a v1.6 SDK server, record that and file a follow-up.

2. OAuth 2.1 + Dynamic Client Registration profile for MCP servers

  • Source: the MCP auth profile section of the spec (currently authoring under the authorization working group; tracked at https://github.com/modelcontextprotocol/specification/tree/main/docs/specification).
  • What to look for:
    • Status transition. Whether the profile is still "in progress" or has moved to "stable" with a fixed revision date.
    • Breaking changes. Any change to the DCR endpoint shape, the PKCE parameters, or the metadata-discovery (/.well-known/oauth-authorization-server) JSON shape — Vetrix already implements this profile and inherits whatever the revision-of-record says, so a breaking change here is a live compatibility break, not a future-adoption risk.
    • PAT compatibility carve-out. Confirm the spec still permits Bearer PAT as a parallel mechanism. If the spec mandates OAuth for every MCP transport, Vetrix's continued PAT support becomes non-conformant and that's an immediate blocker.

Vetrix implements this profile: OAuth 2.1 with mandatory PKCE (code_challenge_method=S256 only), RFC 7591 Dynamic Client Registration (admin-gated via oauth2.dcr.enabled, default off), RFC 8414 authorization-server metadata, and RFC 9728 protected-resource metadata, alongside the existing PAT path (internal/auth/oauth2_register.go, internal/auth/oauth2_metadata.go, internal/api/mcp.go gate chain). The walk now confirms Vetrix's shipped implementation has not silently drifted from the spec's evolving auth profile.

3. Go SDK release notes

  • Source: https://github.com/modelcontextprotocol/go-sdk/releases and the go.mod of the pinned tag.
  • What to look for:
    • Newer minor / patch tag. We pin v1.6.0; record every tag released since the previous walk.
    • Security advisories. https://github.com/modelcontextprotocol/go-sdk/security/advisories. Any open / new advisory is a same-day bump, filed as a Bug (not a Task).
    • Breaking API changes. The Vetrix surface that touches the SDK is internal/mcp/transport.go (mcpsdk.NewStreamableHTTPHandler, mcpsdk.StreamableHTTPOptions) and internal/mcp/server.go (mcpsdk.Server, tool registration). A signature change in either is drift even if the spec did not move.
    • Deprecations. Any field on StreamableHTTPOptions we set today (SessionTimeout, Logger, JSONResponse, DisableLocalhostProtection) being deprecated is drift.

4. GitHub MCP server release notes

  • Source: https://github.com/github/github-mcp-server/releases.
  • Why it's in the walk: GitHub publishes the practical reference implementation Vetrix benchmarks against (tool names, toolset boundaries, the X-MCP-Toolsets opt-in idea, audit semantics). When they change a tool name, an argument shape, or a default toolset, MCP clients in the wild start sending the new shape — and a Vetrix server that still advertises the old shape becomes a worse interop story even if no spec document changed.
  • What to look for:
    • Tool-name rename or removal in any toolset we mirror (repo, issues, pages).
    • New default toolset behaviour (e.g. the header semantics changing, a new "all" / "minimal" selector).
    • New mandatory headers or capability fields on initialize.

Finding shape

Every walk records exactly one finding with these five fields. The field names are the finding's literal headings — a reader scanning the history can scroll for "Observed drift" and find every quarter's row.

**Date:**                  YYYY-MM-DD
**SDK version pinned:**    github.com/modelcontextprotocol/go-sdk v<x.y.z>
**Spec revision targeted:** <transport-revision-date> (initialize protocolVersion=<value>)
**Observed drift:**        one of {none | <list each artifact + the delta>}
**Recommended action:**    one of {no action | bump SDK to v… | file follow-up ticket | adopt v… now}

If Observed drift is anything other than none, Recommended action must reference a filed follow-up ticket.

Cadence

Quarter Target completion
2026-Q3 2026-09-30
2026-Q4 2026-12-31
2027-Q1 2027-03-31
2027-Q2 2027-06-30

The walk is timeboxed: read-only artifact inspection, recording the finding, and a follow-up ticket if needed. A walk should not take more than half a day. If an artifact's content has grown beyond half-a-day to evaluate, that itself is a signal — file a separate Analysis ticket to scope the new surface rather than letting one quarterly walk grow into a multi-day epic.

Calendar reminder configuration is the owner's responsibility (the Vetrix deployment does not run an external calendar). Recommended mechanisms:

  • A standing tracker reminder filed ahead of each quarter's target completion date.
  • An external calendar entry (Google / Outlook / ical) on the owner's primary calendar, set to repeat quarterly.

The reminder mechanism is out of scope for this document; the owner chooses one of the above and confirms it is in place.

When a finding spawns a doc update

Findings live in the running monitoring history. If a finding requires a doc update (e.g. the transport spec moves and internal/mcp/transport.go's pkg doc needs to follow), the walk's owner files a separate Task against this directory (docs/mcp/) or against the relevant internal/mcp/ file. The walk does not edit code or docs in line — the recorded finding is the artifact; the follow-up ticket is the work.

Out of scope for this monitoring

  • Implementing write tools. Deferred to v2.0 under a separate mcp:write scope.
  • Day-to-day client compatibility (Claude Desktop / Cursor / VS Code / Continue.dev). That is covered by the v1.0 manual stopwatch verification and by user issue reports. The drift walk is upstream of those: it asks whether the spec has moved, not whether a specific client still works.