nledford/engineering-review-board / skills/mcp-server-engineering
mcp-server-engineering
VerifiedMCP server engineering guidance. Use when creating, updating, refactoring, testing, or reviewing Model Context Protocol servers, tools, resources, prompts, capability discovery, stdio transport, Streamable HTTP, or legacy HTTP+SSE compatibility. Do not use merely to operate an existing MCP server; use the applicable provider or service skill instead.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.4 KB |
| references/protocol-2026-07-28.md | markdown | 14.6 KB |
| references/sdk-selection.md | markdown | 15.9 KB |
references/protocol-2026-07-28.md
View on GitHub# MCP Protocol Baseline — 2026-07-28
**Retrieved:** 2026-07-31. **Status:** current dated-specification baseline.
This is an evidence map and revision-specific implementation guide, not a
replacement for the specification. Select this revision before implementing or
reviewing a server.
## Pin and authority
The official [2026-07-28 specification landing page][P1] labels this dated
revision “latest.” The official [draft landing page][P2] is a draft, not a newer
published dated revision. No newer published dated revision was found in the
official source set at retrieval. Therefore the required file name and pin remain
`2026-07-28`.
Use authority in this order:
1. **Normative core:** the revision-specific specification and its `schema.ts`
source of truth ([P3]).
2. **Normative policy/process where applicable:** the current feature-lifecycle
policy ([P4]); its adopted SEP is historical design context, not a substitute
for current specification text ([P5]).
3. **Official guidance:** version-specific documentation and SDK guides. They
explain implementation choices but do not override normative core text.
4. **Host/vendor policy and examples:** host documentation, installed plugins,
and example servers. These are not protocol authority.
## Lifecycle and deprecated surfaces
Core features are **Active**, **Deprecated**, or **Removed**. A deprecated
feature remains specified for compatibility, but a new implementation must not
adopt it. Eligibility for removal is not removal; consult the current
changelog/registry before a future implementation ([P4], [P5], [P6]).
| Surface | Current rule | Boundary |
| --- | --- | --- |
| Roots, Sampling, Logging | Deprecated. Preserve only necessary compatibility; do not add new use. Prefer explicit inputs/resources/configuration, direct provider integration, and stderr/OpenTelemetry respectively. | Existing feature pages describe compatibility, not new-adoption guidance ([P7], [P8], [P9]). |
| Sampling context | Deprecated context-inclusion values must not be newly used; omit the option rather than requesting cross-server context. | Removed no later than Sampling ([P6], [P8]). |
| HTTP+SSE | Deprecated; build new remote servers on Streamable HTTP. | An adapter for known legacy clients is not a second modern transport ([P6], [P10]). |
| DCR | OAuth Dynamic Client Registration is deprecated as the preferred registration route, while remaining a backward-compatible fallback. | Prefer known-client pre-registration, then CIMD when available; use DCR only as fallback ([P6], [P11]). |
| CIMD | Client ID Metadata Documents replace DCR for clients without a prior relationship. | Apply the required HTTPS client-ID URL, path, exact metadata match, and referenced OAuth requirements ([P11]). |
## Stateless lifecycle and discovery
The modern core is stateless at the protocol level:
- Protocol sessions and `Mcp-Session-Id` are removed. A connection, host
conversation, or application handle is not a core protocol session. Use
explicit server handles or protected request state when cross-call state is
required.
- The `initialize` / `notifications/initialized` handshake is removed. Each
request carries protocol version and client capabilities in `_meta`, and every
server implements `server/discover` ([P3], [P6], [P12]).
- A server cannot independently send a JSON-RPC request. Request-scoped
notifications/streams and the MRTR retry pattern do not restore that ability
([P12], [P13]).
- `logging/setLevel` is removed. For compatible existing Logging use, a client
requests a level for one request with the defined metadata; without it, do not
emit logging notifications for that request ([P6], [P9]). Logging itself is
deprecated, so do not build a new dependency on this path.
Complete discovery, list, and resource-read results have the revision's required
nonnegative `ttlMs` and `cacheScope` hints. Choose actual freshness and visibility
rather than copying a conservative value; `public` is only for content safe to
share across authorization contexts, and `private` caches must be partitioned by
the needed principal/tenant/scope context. A cache hint neither authorizes access
nor makes a result immutable ([P3], [P12]).
For Streamable HTTP, use one endpoint accepting POST; each JSON-RPC request is
its own HTTP request. A response may be JSON or request-scoped SSE when that
request needs related notifications before its final result. Do not recreate a
legacy GET event stream or session behavior. Validate required protocol metadata
and mirrored HTTP headers, reject disagreement, validate Origin, and use HTTPS
outside explicitly bounded local development ([P3]).
For protected remote servers, invalid or expired bearer authentication is an HTTP
authentication failure; insufficient authorization follows the selected profile's
authorization failure and challenge requirements. Do not conceal transport-level
authentication failure in an apparent successful tool result.
## Primitive wire details
Tool names are unique and case-sensitive. In this revision they use the selected
schema's tool-name constraints; use the specification rather than copying an
older client limit. Tool `inputSchema` is a non-null JSON Schema object in the
revision's default dialect. A no-argument tool explicitly accepts only an empty
object. If an `outputSchema` is declared, structured output conforms to it.
Use a JSON-RPC protocol error for an unknown method, malformed protocol request,
or protocol/server failure. Return a complete tool execution error for actionable
validation, authorization, business, or upstream outcomes. A multi-round
operation returns the distinct input-required result shape rather than a
successful terminal result. Direct resources have stable URIs; parameterized
families use resource templates; prompts return explicit role-tagged messages.
## Versioning, capabilities, and extensions
Every request is independently versioned and declares client capabilities. The
server discovers supported core versions and capabilities; advertise only
implemented behavior. Core extensions use a namespaced `extensions` capability
map and are negotiated separately from the core revision. Both sides must
explicitly support an extension; an unrecognized extension follows that
extension's fallback/rejection rule, not an implied core requirement ([P12]).
When a client lacks an optional capability, never send its interaction. Preserve
semantics with a feasible fallback or return the applicable
missing/unsupported-capability error. This is protocol-compatible
interoperability guidance, not a claim that all optional features have one
universal fallback.
## Authorization baseline
This applies when an HTTP-based MCP server protects requests with OAuth. Keep
three decisions separate: client authorization to the MCP resource server,
resource-server validation of the presented MCP token, and authorization
elicited through a third-party URL flow. Approval or credentials from one does
not authorize either of the others ([P16], [P17]).
- **Discover the authorization server through the resource.** The MCP resource
server **MUST** publish OAuth 2.0 Protected Resource Metadata, and the MCP
client **MUST** use that metadata to discover the authorization server under
RFC 9728; do not substitute a configured issuer, a host hint, or URL
elicitation for protected-resource discovery ([P16], [P18]).
- **Protect authorization codes with verified PKCE.** Before starting an
authorization-code flow, the MCP client **MUST** verify that the selected
authorization server metadata declares `code_challenge_methods_supported`
and includes `S256`; refuse the flow when this support cannot be verified.
Send an `S256` PKCE challenge and redeem the code with its verifier as
specified by RFC 7636 Section 4.2 ([P17], [P19]).
- **Bind a token request to this MCP resource.** The MCP client **MUST** send
RFC 8707's canonical `resource` parameter in both authorization and token
requests. The resource server **MUST** accept the resulting token only when
its intended audience or resource identifies that MCP server ([P16], [P17],
[P20]).
- **Validate tokens before protected work.** Before serving every protected
request, the MCP resource server **MUST** validate the token's trusted
issuer, signature, expiry, intended audience/resource, and the scopes
required by the requested operation. Reject a token or scope that fails any
check; never pass the MCP-client token through to an upstream API ([P17]).
## MRTR and elicitation
MRTR replaces the old independent server-request pattern. A server returns
`resultType: "input_required"` with `inputRequests` and optional opaque
`requestState`; the client collects supported input and retries the original
operation with a new JSON-RPC ID and `inputResponses` ([P13], [P14]). Send only
input request types declared in client capabilities.
For integrity, principal binding, expiry, request binding, replay prevention,
and required tests for returned state, use the parent’s
[MRTR state safety rules](../SKILL.md#mrtr-state-safety). They are intentionally
maintained once, not duplicated here.
### Elicitation contract
| Need | Rule |
| --- | --- |
| Capability and delivery | Use `elicitation/create` only when the client declares elicitation and only inside MRTR `inputRequests`; never as an independent request ([P13], [P14]). |
| Modes | Use form mode (omitted `mode` or `"form"`) for a flat object with primitive properties; use URL mode (`"url"`) for an out-of-band interaction. Never send a mode the client did not declare. |
| Form safety | Form data is visible to the MCP client. Do not request passwords, API keys, or other credentials in form mode ([P14]). |
| Outcomes | The user may accept, decline, or cancel. Acceptance of URL mode authorizes opening/continuing the interaction, not completion; determine completion from protected or server-side state on retry. |
| URL consent | Show the full URL, obtain explicit user consent, and do not prefetch/open it before consent. Do not send sensitive or pre-authenticated URLs. Use HTTPS outside development. |
| URL trust | Bind URL-flow state to the user and protect it. Defend against phishing/domain confusion with a deployment-approved domain policy and clear user-visible domain controls. |
| Authorization | URL elicitation serves third-party or sensitive interaction; it is not authorization for client access to the MCP server. Do not relay third-party credentials through the MCP client. |
If URL mode starts an OAuth flow, apply OAuth redirect-URI and state protections
to that flow. Do not infer an OAuth redirect/state requirement merely from a
non-OAuth URL elicitation. Keep MCP-server authorization distinct from external
authorization; validate an MCP token for this server and acquire a separately
issued upstream token where needed—token passthrough is prohibited ([P11], [P14]).
## Plugin/example non-authority rule
The official development-skills page calls its `mcp-server-dev` plugin a
reference skill set ([P15]). It, installed plugins, SDK examples, and host
examples are non-authoritative examples. Do not copy lifecycle, initialization,
session, transport, extension, or security assumptions from them when they
conflict with the current revision-specific normative sources. This baseline did
not install packages, execute a server/runtime, mutate browser state, or use
private data.
## Sources
Sources are cited with their retrieval dates. `modelcontextprotocol.io` pages
are official MCP project sources; dated specification sources are normative
where labelled above.
- [P1] [Specification 2026-07-28 (latest)](https://modelcontextprotocol.io/specification/2026-07-28) — official core, revision `2026-07-28`; retrieved 2026-07-31.
- [P2] [Specification draft](https://modelcontextprotocol.io/specification/draft) — official draft, no dated revision asserted; retrieved 2026-07-31.
- [P3] [Core overview](https://modelcontextprotocol.io/specification/2026-07-28/basic) — normative core, revision `2026-07-28`; retrieved 2026-07-31.
- [P4] [Feature Lifecycle and Deprecation Policy](https://modelcontextprotocol.io/community/feature-lifecycle) — official current policy, no independent version; retrieved 2026-07-31.
- [P5] [SEP-2596](https://modelcontextprotocol.io/seps/2596-spec-feature-lifecycle-and-deprecation) — official Final historical process record; retrieved 2026-07-31.
- [P6] [2026-07-28 changelog](https://modelcontextprotocol.io/specification/2026-07-28/changelog) — normative revision changelog; retrieved 2026-07-31.
- [P7] [Roots](https://modelcontextprotocol.io/specification/2026-07-28/client/roots) — normative core feature page; retrieved 2026-07-31.
- [P8] [Sampling](https://modelcontextprotocol.io/specification/2026-07-28/client/sampling) — normative core feature page; retrieved 2026-07-31.
- [P9] [Logging](https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/logging) — normative core feature page; retrieved 2026-07-31.
- [P10] [Deprecated features registry](https://modelcontextprotocol.io/specification/2026-07-28/deprecated) — official derived registry; retrieved 2026-07-31.
- [P11] [Client registration](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration) — normative authorization text; retrieved 2026-07-31.
- [P12] [Versioning and compatibility](https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning) — normative core; retrieved 2026-07-31.
- [P13] [Multi Round-Trip Requests](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr) — normative core; retrieved 2026-07-31.
- [P14] [Elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation) — normative core; retrieved 2026-07-31.
- [P15] [Build with Agent Skills](https://modelcontextprotocol.io/docs/2026-07-28/develop/build-with-agent-skills) — official guidance/example, not normative protocol text; retrieved 2026-07-31.
- [P16] [Authorization](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization) — normative MCP authorization requirements; retrieved 2026-08-01.
- [P17] [Authorization Security Considerations](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/security-considerations) — normative MCP authorization-security requirements; retrieved 2026-08-01.
- [P18] [RFC 9728: OAuth 2.0 Protected Resource Metadata](https://www.rfc-editor.org/rfc/rfc9728.html) — IETF Standards Track; retrieved 2026-08-01.
- [P19] [RFC 7636: Proof Key for Code Exchange by OAuth Public Clients](https://www.rfc-editor.org/rfc/rfc7636.html#section-4.2) — IETF Standards Track, PKCE `S256`; retrieved 2026-08-01.
- [P20] [RFC 8707: Resource Indicators for OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8707.html) — IETF Standards Track; retrieved 2026-08-01.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |