hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-mcp
hyper-mcp
Flagged[Hyper] Use this skill when the user wants Model Context Protocol (MCP) work carried end to end - building or extending an MCP server or client, auditing or fixing one, migrating it to the current protocol revision, wiring MCP servers into an agent host's configuration, or preparing registry publication - with findings and verification saved under `.hyper/mcp/[slug]/`. Do not use it for API, CLI, or plugin work that has no MCP surface, for documents that only explain MCP, or for creating a reusable skill folder.
| File | Kind | Size |
|---|---|---|
| SKILL.ko.md | markdown | 17.5 KB |
| SKILL.md | skill md | 15.3 KB |
| assets/evals/hyper-mcp-cases.jsonl | other | 12.6 KB |
| references/build-test-ship.ko.md | markdown | 13.2 KB |
| references/build-test-ship.md | markdown | 11.6 KB |
| references/host-integration.ko.md | markdown | 13.1 KB |
| references/host-integration.md | markdown | 11.6 KB |
| references/protocol-2026-07-28.ko.md | markdown | 15.9 KB |
| references/protocol-2026-07-28.md | markdown | 13.9 KB |
| references/security-and-authorization.ko.md | markdown | 16.5 KB |
| references/security-and-authorization.md | markdown | 14.4 KB |
| references/server-design.ko.md | markdown | 14.8 KB |
| references/server-design.md | markdown | 12.8 KB |
| rules/mcp-rules.ko.md | markdown | 7.4 KB |
| rules/mcp-rules.md | markdown | 6.6 KB |
| rules/mcp-workflow.ko.md | markdown | 10.1 KB |
| rules/mcp-workflow.md | markdown | 8.9 KB |
| rules/validation.ko.md | markdown | 6.1 KB |
| rules/validation.md | markdown | 5.2 KB |
references/protocol-2026-07-28.md
View on GitHub# Protocol 2026-07-28
What the current MCP revision requires on the wire, what changed from `2025-11-25`, and how to stay compatible with clients and servers that still speak the older revisions. Read it before writing or reviewing any code that sends or answers MCP messages.
> Korean version: [`protocol-2026-07-28.ko.md`](protocol-2026-07-28.ko.md)
## Contents
- Version anchor
- Message shape
- Breaking changes from 2025-11-25
- Multi Round-Trip Requests
- Subscriptions, progress, cancellation
- Caching
- Transports
- Compatibility across eras
- Deprecated features
- Migration checklist from 2025-11-25
## Version anchor
- The current protocol version is `2026-07-28`; revisions are `Draft`, `Current`, or `Final`, and a version string names "the last date backwards incompatible changes were made" (docs versioning page, checked 2026-11-07).
- The release was published on 2026-07-28 as "a stateless protocol core - MCP is transforming from a bidirectional stateful protocol into a request/response stateless protocol" (release post, checked 2026-11-07).
- The publication date is not a switch-off date for older clients: the SDK beta post says it "is not a switch-off for any implementers relying on the current protocol version" (checked 2026-11-07).
- Material written against `2025-11-25` or earlier — tutorials, blog posts, model memory, older SDK examples — describes `initialize`, sessions, and server-initiated requests that no longer exist in the current revision. Check the revision of every example before copying it.
## Message shape
| Concern | Rule in `2026-07-28` |
|---|---|
| Statefulness | "a server processes each request independently; no state should be inferred from previous requests, even those on the same connection or stream." Servers **MUST NOT** rely on prior requests for capabilities, version, or client identity. |
| Version and capabilities | Every request carries `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities` in `_meta`; clients **SHOULD** add `io.modelcontextprotocol/clientInfo`. A request missing a required field is rejected with `-32602`. |
| Server identity | Servers **MUST** implement `server/discover`, which returns supported versions, capabilities, optional `instructions`, and `serverInfo`. Clients **MAY** call it first; they are not required to. |
| Version mismatch | The server answers `UnsupportedProtocolVersionError` (`-32022`) listing `supported`; the client **SHOULD** retry with a mutually supported version. |
| Result type | Every result carries `resultType`: `"complete"` or `"input_required"`. Results from older servers that omit it are treated as `"complete"`. |
| Message direction | "Servers **MUST NOT** initiate JSON-RPC requests, and clients do not send JSON-RPC responses." |
| Cross-call state | No protocol session exists. State that spans requests is an explicit, server-minted handle passed back as an ordinary tool argument. |
Two trust facts ride on this shape: `serverInfo` and `clientInfo` are self-reported and "not verified by the protocol", so neither may drive a security decision (discover page, checked 2026-11-07).
## Breaking changes from 2025-11-25
| Removed or replaced | Replacement |
|---|---|
| `initialize` / `notifications/initialized` handshake | Per-request `_meta`, plus optional `server/discover` |
| Protocol sessions and the `Mcp-Session-Id` header | Stateless requests; explicit handles for application state |
| Server-initiated `roots/list`, `sampling/createMessage`, `elicitation/create` | Multi Round-Trip Requests (`InputRequiredResult`) |
| HTTP GET stream, `resources/subscribe` / `unsubscribe` | One `subscriptions/listen` stream with opted-in notification types |
| `ping`, `logging/setLevel`, `notifications/roots/list_changed` | Removed; log level travels per request as `io.modelcontextprotocol/logLevel` |
| SSE resumability (`Last-Event-ID`, event IDs) | A broken stream loses the request; the client re-issues it with a new request ID |
| Core experimental Tasks | The `io.modelcontextprotocol/tasks` extension, with polling via `tasks/get` |
| `notifications/elicitation/complete`, `elicitationId` | The client learns the outcome by retrying the original request |
| Resource-not-found `-32002` | `-32602`; clients **SHOULD** still accept `-32002` from older servers |
Additions that are mandatory rather than optional: `Mcp-Method` and `Mcp-Name` headers on Streamable HTTP, `ttlMs` and `cacheScope` on cacheable results, and deterministic `tools/list` ordering as a **SHOULD** (changelog, checked 2026-11-07).
## Multi Round-Trip Requests
A server that needs user input, a model completion, or the client's roots in the middle of a request no longer sends its own request. It returns an interim result and the client retries.
1. The client sends `tools/call`, `prompts/get`, or `resources/read`. Only these three may return `InputRequiredResult`.
2. The server returns `resultType: "input_required"` with `inputRequests` (keyed requests such as `elicitation/create`) and an optional opaque `requestState`.
3. The client gathers the answers and re-sends the original request with a **new** JSON-RPC `id`, adding `inputResponses` and echoing `requestState` unchanged.
Rules that decide whether the pattern is safe:
- Servers **MUST NOT** request a capability the client did not declare; the error is `MissingRequiredClientCapabilityError` (`-32021`).
- Clients **MUST NOT** inspect, parse, or modify `requestState`.
- Servers **MUST** treat `requestState` as attacker-controlled input. If it influences authorization, access, or business logic, the server **MUST** protect its integrity (for example HMAC or AEAD) and reject state that fails verification; binding it to the principal, a TTL, and the original request is a **SHOULD**.
- Servers **MUST NOT** assume the client will answer or retry.
## Subscriptions, progress, cancellation
- `subscriptions/listen` opens one long-lived stream. The client opts into `toolsListChanged`, `promptsListChanged`, `resourcesListChanged`, or specific `resourceSubscriptions`; the server **MUST** send `notifications/subscriptions/acknowledged` first and **MUST NOT** send types the client did not request.
- Progress and log notifications travel on the response stream of the request they belong to, never on the subscription stream. `progress` **MUST** increase with each notification.
- On Streamable HTTP, closing the SSE response stream is the cancellation signal; on stdio, cancellation is `notifications/cancelled`. After a stdio reconnect the client **MUST** re-send `subscriptions/listen`.
## Caching
- Results of `server/discover`, `tools/list`, `prompts/list`, `resources/list`, `resources/templates/list`, and `resources/read` **MUST** carry `ttlMs` (≥ 0) and `cacheScope` (caching page, checked 2026-11-07). The changelog lists five of these; the caching page adds `server/discover` and is the normative text.
- `ttlMs` is a freshness hint, not a guarantee, and **SHOULD NOT** be used as a polling interval; pollers **MUST** apply jitter and backoff.
- `cacheScope: "private"` caches **MUST NOT** be shared across authorization contexts, and servers **MUST NOT** rely on `cacheScope` alone to prevent unauthorized access.
- `input_required` results and retries carrying `inputResponses` are never cached. A matching list-changed notification invalidates the cached entry.
## Transports
A transport is a binding; protocol semantics are identical on every transport.
| Transport | Rules that break implementations when ignored |
|---|---|
| stdio | Newline-delimited JSON-RPC with no embedded newlines. The server **MUST NOT** write anything to `stdout` that is not a valid MCP message; logs go to `stderr`, and `stderr` output does not imply an error. Servers **SHOULD** exit promptly when `stdin` closes. |
| Streamable HTTP | One endpoint that accepts POST. Requests carry `MCP-Protocol-Version`, `Mcp-Method`, and — for `tools/call`, `resources/read`, `prompts/get` — `Mcp-Name`; a header that disagrees with the body is rejected with `400` and `-32020`. Servers **MUST** validate `Origin` (invalid → `403`) and **SHOULD** bind to `127.0.0.1` when local. An incoming `Mcp-Session-Id` is ignored. |
| HTTP+SSE (2024-11-05) | Deprecated since `2025-03-26`, reclassified Deprecated under the lifecycle policy in `2026-07-28`. Do not build on it. |
`x-mcp-header` on a primitive tool parameter mirrors its value into an `Mcp-Param-{Name}` header so gateways can route without parsing bodies. Clients on Streamable HTTP **MUST** drop tool definitions whose `x-mcp-header` values break the constraints, and servers **SHOULD NOT** mark secrets or PII this way, because headers are visible to intermediaries (tools page, checked 2026-11-07).
## Compatibility across eras
The specification names three kinds of implementation: **modern** (`2026-07-28` and later), **legacy** (`2025-11-25` and earlier, handshake-based), and **dual-era** (both).
| Client → Server | Outcome |
|---|---|
| Modern → Modern | Works; mismatches surface as `UnsupportedProtocolVersionError` and the client retries. |
| Modern → Legacy | Fails. On stdio the client **SHOULD** send `server/discover` first so the failure is deterministic. |
| Dual-era → Legacy | Works: the stdio probe gets a non-modern error or times out, or the HTTP request gets a `4xx` without a modern error body, and the client falls back to `initialize`. |
| Legacy → Modern | Fails; legacy clients have no fall-forward path. A modern-only server **SHOULD** name its supported versions in the error it returns to `initialize`. |
| Legacy → Dual-era | Works under the negotiated legacy revision. |
Era detection is a property of the server: clients **SHOULD** cache it per stdio process or HTTP origin. Choose dual-era only when you must serve clients you do not control; a modern-only server is simpler and fails loudly.
## Deprecated features
Deprecated features stay in the specification for at least twelve months, and the registry states that the earliest removal is the first revision released on or after 2027-07-28 (deprecated registry, checked 2026-11-07). "No features have been removed under this policy yet." New implementations **SHOULD NOT** adopt any of them.
| Deprecated | Migrate to |
|---|---|
| Roots | Directories or files as tool parameters, resource URIs, or server configuration |
| Sampling (and `includeContext` values `thisServer` / `allServers`) | Direct integration with an LLM provider API |
| Logging (`notifications/message`) | `stderr` on stdio; OpenTelemetry on HTTP |
| Dynamic Client Registration (RFC 7591) | Client ID Metadata Documents |
| HTTP+SSE transport | Streamable HTTP |
Elicitation is not deprecated; it is the remaining client feature a server can rely on, through MRTR.
## Migration checklist from 2025-11-25
- [ ] Remove every dependency on `initialize`, session IDs, and per-connection state; move cross-call state into explicit handles.
- [ ] Implement `server/discover` and include `ttlMs` / `cacheScope` on the six cacheable results.
- [ ] Replace server-initiated requests with `InputRequiredResult`, and integrity-protect any `requestState` that matters.
- [ ] Replace `resources/subscribe` and the GET stream with `subscriptions/listen`.
- [ ] Stop emitting `notifications/message` unless the request carried `io.modelcontextprotocol/logLevel`; log to `stderr` or OpenTelemetry.
- [ ] On HTTP: send and validate `Mcp-Method` / `Mcp-Name`; stop relying on `Last-Event-ID`.
- [ ] Map resource-not-found to `-32602` and accept `-32002` from older servers.
- [ ] Move error codes from the release-candidate numbers (`-32001`, `-32003`, `-32004`) to `-32020`, `-32021`, `-32022`.
- [ ] Re-test with an inspector pinned to the modern era; its default is legacy ([`build-test-ship.md`](build-test-ship.md)).
## Sources
> All links checked 2026-11-07; specification pages are the `2026-07-28` revision, and blog dates are as printed on each post.
| Claim | Source | Published |
|---|---|---|
| Key changes, deprecations, error-code renumbering | <https://modelcontextprotocol.io/specification/2026-07-28/changelog> | rev. 2026-07-28 |
| Current revision, revision states, twelve-month deprecation window | <https://modelcontextprotocol.io/docs/2026-07-28/learn/versioning> | rev. 2026-07-28 |
| Per-request negotiation, eras, compatibility matrix | <https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning> | rev. 2026-07-28 |
| Statelessness, `_meta` fields, error-code allocation | <https://modelcontextprotocol.io/specification/2026-07-28/basic> | rev. 2026-07-28 |
| `server/discover`, self-reported `serverInfo` | <https://modelcontextprotocol.io/specification/2026-07-28/server/discover> | rev. 2026-07-28 |
| MRTR flow and `requestState` integrity rules | <https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr> | rev. 2026-07-28 |
| `subscriptions/listen` | <https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/subscriptions> | rev. 2026-07-28 |
| Cancellation on each transport | <https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/cancellation> | rev. 2026-07-28 |
| `ttlMs`, `cacheScope`, cache sharing limits | <https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/caching> | rev. 2026-07-28 |
| stdio framing and `stdout` rule | <https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/stdio> | rev. 2026-07-28 |
| Streamable HTTP headers, `Origin` validation, localhost binding | <https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http> | rev. 2026-07-28 |
| `x-mcp-header` constraints, deterministic tool order | <https://modelcontextprotocol.io/specification/2026-07-28/server/tools> | rev. 2026-07-28 |
| Deprecated registry, earliest removal date | <https://modelcontextprotocol.io/specification/2026-07-28/deprecated> | rev. 2026-07-28 |
| Release announcement and stateless core | <https://blog.modelcontextprotocol.io/posts/2026-07-28/> | 2026-07-28 |
| Release date is not a switch-off date | <https://blog.modelcontextprotocol.io/posts/sdk-betas-2026-07-28/> | 2026-06-29 |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |