Skip to content

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.

references/protocol-2026-07-28.ko.md

View on GitHub
# 프로토콜 2026-07-28

현재 MCP 판이 회선 위에서 요구하는 것, `2025-11-25`에서 바뀐 것, 그리고 옛 판을 쓰는 클라이언트·서버와 호환을 유지하는 방법이다. MCP 메시지를 보내거나 응답하는 코드를 쓰거나 검토하기 전에 읽는다.

> 영어판: [`protocol-2026-07-28.md`](protocol-2026-07-28.md)

## 목차

- 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

- 현재 프로토콜 버전은 `2026-07-28`이다. 판은 `Draft`, `Current`, `Final` 가운데 하나이고 버전 문자열은 "하위 호환이 깨지는 변경이 마지막으로 이루어진 날짜"를 가리킨다(문서 버전 관리 페이지, 2026-11-07 확인).
- 릴리스는 2026-07-28에 "무상태 프로토콜 코어 - MCP는 양방향 상태 기반 프로토콜에서 요청·응답 무상태 프로토콜로 전환한다"로 공개됐다(릴리스 글, 2026-11-07 확인).
- 게재일은 옛 클라이언트의 사용 중단일이 아니다. SDK 베타 글은 이 릴리스가 "현재 프로토콜 버전에 의존하는 어떤 구현자에게도 사용 중단을 뜻하지 않는다"고 밝힌다(2026-11-07 확인).
- `2025-11-25`나 그 이전을 기준으로 쓴 자료(튜토리얼, 블로그 글, 모델 기억, 옛 SDK 예제)는 현재 판에 없는 `initialize`, 세션, 서버 발신 요청을 설명한다. 예제를 복사하기 전에 그 예제의 판을 확인한다.

## Message shape

| 항목 | `2026-07-28`의 규칙 |
|---|---|
| 상태 유지 | "서버는 각 요청을 독립적으로 처리한다. 같은 연결이나 스트림 위에 있더라도 이전 요청에서 상태를 추론해서는 안 된다." 서버는 능력, 버전, 클라이언트 신원을 이전 요청에 의존해 정해서는 안 된다(**MUST NOT**). |
| 버전과 능력 | 모든 요청은 `_meta`에 `io.modelcontextprotocol/protocolVersion`과 `io.modelcontextprotocol/clientCapabilities`를 담는다. 클라이언트는 `io.modelcontextprotocol/clientInfo`를 더하는 것이 좋다(**SHOULD**). 필수 필드가 빠진 요청은 `-32602`로 거절한다. |
| 서버 신원 | 서버는 `server/discover`를 구현해야 한다(**MUST**). 이 메서드는 지원 버전, 능력, 선택적인 `instructions`, `serverInfo`를 반환한다. 클라이언트는 먼저 호출해도 되지만(**MAY**) 필수는 아니다. |
| 버전 불일치 | 서버는 `supported`를 담은 `UnsupportedProtocolVersionError`(`-32022`)로 응답한다. 클라이언트는 서로 지원하는 버전으로 다시 시도하는 것이 좋다(**SHOULD**). |
| 결과 유형 | 모든 결과는 `resultType`을 담는다. 값은 `"complete"` 또는 `"input_required"`다. 이 필드를 빼고 보내는 옛 서버의 결과는 `"complete"`로 취급한다. |
| 메시지 방향 | "서버는 JSON-RPC 요청을 시작해서는 안 되고(**MUST NOT**), 클라이언트는 JSON-RPC 응답을 보내지 않는다." |
| 호출 사이의 상태 | 프로토콜 세션이 없다. 요청을 가로지르는 상태는 서버가 발급한 명시적 핸들로 만들어 도구 인자에 그대로 넘긴다. |

이 형태에는 신뢰에 관한 사실이 둘 붙는다. `serverInfo`와 `clientInfo`는 자기 신고 값이며 "프로토콜이 검증하지 않는다". 따라서 둘 다 보안 결정의 근거가 될 수 없다(discover 페이지, 2026-11-07 확인).

## Breaking changes from 2025-11-25

| 제거되거나 대체된 것 | 대체 |
|---|---|
| `initialize` / `notifications/initialized` 핸드셰이크 | 요청별 `_meta`, 그리고 선택적인 `server/discover` |
| 프로토콜 세션과 `Mcp-Session-Id` 헤더 | 무상태 요청. 애플리케이션 상태는 명시적 핸들로 |
| 서버 발신 `roots/list`, `sampling/createMessage`, `elicitation/create` | 다중 왕복 요청(`InputRequiredResult`) |
| HTTP GET 스트림, `resources/subscribe` / `unsubscribe` | 알림 유형을 선택해 거는 하나의 `subscriptions/listen` 스트림 |
| `ping`, `logging/setLevel`, `notifications/roots/list_changed` | 제거됐다. 로그 수준은 요청마다 `io.modelcontextprotocol/logLevel`로 전달한다 |
| SSE 재개(`Last-Event-ID`, 이벤트 ID) | 끊긴 스트림은 요청을 잃는다. 클라이언트가 새 요청 ID로 다시 보낸다 |
| 핵심 실험 기능 Tasks | `io.modelcontextprotocol/tasks` 확장. `tasks/get`으로 폴링한다 |
| `notifications/elicitation/complete`, `elicitationId` | 클라이언트가 원래 요청을 다시 보내 결과를 알게 된다 |
| 리소스 없음 `-32002` | `-32602`. 클라이언트는 옛 서버의 `-32002`도 계속 받아들이는 것이 좋다(**SHOULD**) |

선택이 아니라 의무가 된 추가 항목이 있다. Streamable HTTP의 `Mcp-Method`·`Mcp-Name` 헤더, 캐시 가능한 결과의 `ttlMs`와 `cacheScope`, 그리고 `tools/list`의 결정적 정렬이다. 마지막 항목은 의무가 아니라 따르는 것이 좋다(**SHOULD**)(변경 이력, 2026-11-07 확인).

## Multi Round-Trip Requests

요청 처리 중간에 사용자 입력, 모델 완성, 클라이언트의 roots가 필요한 서버는 더 이상 자기 요청을 보내지 않는다. 중간 결과를 반환하고 클라이언트가 다시 시도한다.

1. 클라이언트가 `tools/call`, `prompts/get`, `resources/read`를 보낸다. `InputRequiredResult`를 반환할 수 있는 것은 이 셋뿐이다.
2. 서버가 `resultType: "input_required"`와 `inputRequests`(예: `elicitation/create` 같은 키별 요청), 선택적인 불투명 `requestState`를 반환한다.
3. 클라이언트가 답을 모아 원래 요청을 **새** JSON-RPC `id`로 다시 보낸다. `inputResponses`를 더하고 `requestState`는 바꾸지 않고 그대로 되돌려 준다.

이 패턴이 안전한지를 정하는 규칙이다.

- 서버는 클라이언트가 선언하지 않은 능력을 요구해서는 안 된다(**MUST NOT**). 이때 오류는 `MissingRequiredClientCapabilityError`(`-32021`)다.
- 클라이언트는 `requestState`를 들여다보거나 해석하거나 수정해서는 안 된다(**MUST NOT**).
- 서버는 `requestState`를 공격자가 제어할 수 있는 입력으로 다뤄야 한다(**MUST**). 이 값이 인가, 접근, 업무 로직에 영향을 준다면 서버는 무결성을 보호해야 하고(예: HMAC, AEAD) 검증에 실패한 상태는 거절해야 한다(**MUST**). 주체, TTL, 원래 요청에 묶어 두는 것이 좋다(**SHOULD**).
- 서버는 클라이언트가 답하거나 다시 시도한다고 가정해서는 안 된다(**MUST NOT**).

## Subscriptions, progress, cancellation

- `subscriptions/listen`은 오래 사는 스트림 하나를 연다. 클라이언트는 `toolsListChanged`, `promptsListChanged`, `resourcesListChanged` 또는 특정 `resourceSubscriptions`를 선택해 건다. 서버는 `notifications/subscriptions/acknowledged`를 먼저 보내야 하고(**MUST**) 클라이언트가 요청하지 않은 유형을 보내서는 안 된다(**MUST NOT**).
- 진행과 로그 알림은 그 알림이 속한 요청의 응답 스트림으로 다니며 구독 스트림으로는 다니지 않는다. `progress`는 알림마다 증가해야 한다(**MUST**).
- Streamable HTTP에서 SSE 응답 스트림을 닫는 것이 취소 신호다. stdio에서는 `notifications/cancelled`가 취소다. stdio를 다시 연결한 뒤 클라이언트는 `subscriptions/listen`을 다시 보내야 한다(**MUST**).

## Caching

- `server/discover`, `tools/list`, `prompts/list`, `resources/list`, `resources/templates/list`, `resources/read`의 결과는 `ttlMs`(0 이상)와 `cacheScope`를 담아야 한다(**MUST**)(캐싱 페이지, 2026-11-07 확인). 변경 이력은 이 가운데 다섯 개를 적고 캐싱 페이지가 `server/discover`를 더하며 규범 문장은 캐싱 페이지다.
- `ttlMs`는 신선도 힌트이지 보장이 아니며 폴링 주기로 써서는 안 된다(**SHOULD NOT**). 폴링하는 쪽은 지터와 백오프를 적용해야 한다(**MUST**).
- `cacheScope: "private"`인 캐시는 인가 문맥을 넘어 공유해서는 안 되고(**MUST NOT**), 서버는 무단 접근을 막는 수단으로 `cacheScope`만 믿어서는 안 된다(**MUST NOT**).
- `input_required` 결과와 `inputResponses`를 담은 재시도는 절대 캐시하지 않는다. 대응하는 목록 변경 알림이 오면 캐시 항목을 무효로 한다.

## Transports

트랜스포트는 바인딩이다. 프로토콜 의미는 모든 트랜스포트에서 같다.

| 트랜스포트 | 무시하면 구현이 깨지는 규칙 |
|---|---|
| stdio | 개행으로 구분하는 JSON-RPC이며 메시지 안에 개행을 넣지 않는다. 서버는 유효한 MCP 메시지가 아닌 것을 `stdout`에 써서는 안 된다(**MUST NOT**). 로그는 `stderr`로 보내고 `stderr` 출력이 오류를 뜻하지는 않는다. `stdin`이 닫히면 서버는 곧바로 종료하는 것이 좋다(**SHOULD**). |
| Streamable HTTP | POST를 받는 엔드포인트 하나다. 요청은 `MCP-Protocol-Version`, `Mcp-Method`, 그리고 `tools/call`, `resources/read`, `prompts/get`이면 `Mcp-Name`을 담는다. 본문과 어긋나는 헤더는 `400`과 `-32020`으로 거절한다. 서버는 `Origin`을 검증해야 하고(**MUST**, 유효하지 않으면 `403`) 로컬이면 `127.0.0.1`에 바인딩하는 것이 좋다(**SHOULD**). 들어온 `Mcp-Session-Id`는 무시한다. |
| HTTP+SSE (2024-11-05) | `2025-03-26`부터 폐기 예정이었고 `2026-07-28`의 수명주기 정책에서 폐기 예정(Deprecated)으로 다시 분류됐다. 이 위에 구현을 쌓지 않는다. |

원시 도구 매개변수의 `x-mcp-header`는 그 값을 `Mcp-Param-{Name}` 헤더로 비춰 게이트웨이가 본문을 해석하지 않고 라우팅하게 한다. Streamable HTTP를 쓰는 클라이언트는 `x-mcp-header` 값이 제약을 어기는 도구 정의를 버려야 하고(**MUST**), 서버는 비밀값이나 개인정보를 이 방식으로 표시해서는 안 된다(**SHOULD NOT**). 헤더는 중개자에게 보이기 때문이다(도구 페이지, 2026-11-07 확인).

## Compatibility across eras

명세는 구현을 세 종류로 나눈다. **modern**(`2026-07-28` 이후), **legacy**(`2025-11-25` 이전, 핸드셰이크 기반), **dual-era**(둘 다)다. 세 이름은 명세 용어라 원어로 쓴다.

| 클라이언트 → 서버 | 결과 |
|---|---|
| modern → modern | 동작한다. 불일치는 `UnsupportedProtocolVersionError`로 드러나고 클라이언트가 다시 시도한다. |
| modern → legacy | 실패한다. stdio에서는 실패를 결정적으로 만들기 위해 클라이언트가 `server/discover`를 먼저 보내는 것이 좋다(**SHOULD**). |
| dual-era → legacy | 동작한다. stdio 탐침이 modern 오류가 아닌 응답을 받거나 시간이 초과되면, 또는 HTTP 요청이 modern 오류 본문 없는 `4xx`를 받으면 클라이언트가 `initialize`로 물러난다. |
| legacy → modern | 실패한다. legacy 클라이언트에는 새 판으로 넘어갈 경로가 없다. modern 전용 서버는 `initialize`에 돌려주는 오류에 지원 버전을 적는 것이 좋다(**SHOULD**). |
| legacy → dual-era | 협상된 legacy 판으로 동작한다. |

era 판별은 서버의 속성이다. 클라이언트는 stdio 프로세스나 HTTP 오리진 단위로 이를 캐시하는 것이 좋다(**SHOULD**). 통제할 수 없는 클라이언트를 상대해야 할 때만 dual-era를 고른다. modern 전용 서버가 더 단순하고 실패할 때 조용히 넘어가지 않는다.

## Deprecated features

폐기 예정 기능은 명세에 최소 12개월 남는다. 레지스트리는 가장 이른 제거 시점을 2027-07-28 이후에 나오는 첫 판이라고 밝힌다(폐기 레지스트리, 2026-11-07 확인). "이 정책에 따라 제거된 기능은 아직 없다." 새 구현은 어느 것도 받아들이는 것이 좋지 않다(**SHOULD NOT**).

| 폐기 예정인 것 | 옮겨 갈 곳 |
|---|---|
| Roots | 도구 매개변수, 리소스 URI, 서버 설정으로 쓰는 디렉터리나 파일 |
| Sampling(`includeContext` 값 `thisServer` / `allServers` 포함) | LLM 공급자 API와의 직접 통합 |
| Logging(`notifications/message`) | stdio에서는 `stderr`, HTTP에서는 OpenTelemetry |
| 동적 클라이언트 등록(RFC 7591) | 클라이언트 ID 메타데이터 문서 |
| HTTP+SSE 트랜스포트 | Streamable HTTP |

elicitation은 폐기 예정이 아니다. 서버가 MRTR을 통해 의지할 수 있는 남은 클라이언트 기능이다.

## Migration checklist from 2025-11-25

- [ ] `initialize`, 세션 ID, 연결별 상태에 기대는 것을 모두 걷어낸다. 호출 사이의 상태는 명시적 핸들로 옮긴다.
- [ ] `server/discover`를 구현하고 캐시 가능한 여섯 결과에 `ttlMs` / `cacheScope`를 넣는다.
- [ ] 서버 발신 요청을 `InputRequiredResult`로 바꾸고 문제가 되는 `requestState`는 무결성을 보호한다.
- [ ] `resources/subscribe`와 GET 스트림을 `subscriptions/listen`으로 바꾼다.
- [ ] 요청이 `io.modelcontextprotocol/logLevel`을 담지 않았으면 `notifications/message`를 보내지 않는다. `stderr`나 OpenTelemetry에 기록한다.
- [ ] HTTP에서는 `Mcp-Method` / `Mcp-Name`을 보내고 검증한다. `Last-Event-ID`에 의존하지 않는다.
- [ ] 리소스 없음을 `-32602`로 매핑하고 옛 서버의 `-32002`도 받아들인다.
- [ ] 오류 코드를 릴리스 후보 번호(`-32001`, `-32003`, `-32004`)에서 `-32020`, `-32021`, `-32022`로 옮긴다.
- [ ] modern era로 고정한 인스펙터로 다시 시험한다. 인스펙터의 기본값은 legacy다([`build-test-ship.ko.md`](build-test-ship.ko.md)).

## Sources

> 확인 2026-11-07. 명세 페이지는 `2026-07-28` 판이며 블로그 날짜는 각 페이지에 표시된 값이다.

| 주장 | 출처 | 게재 |
|---|---|---|
| 주요 변경, 폐기, 오류 코드 번호 재배치 | <https://modelcontextprotocol.io/specification/2026-07-28/changelog> | 2026-07-28 판 |
| 현재 판, 판 상태, 12개월 폐기 기간 | <https://modelcontextprotocol.io/docs/2026-07-28/learn/versioning> | 2026-07-28 판 |
| 요청별 협상, era 구분, 호환성 행렬 | <https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning> | 2026-07-28 판 |
| 무상태성, `_meta` 필드, 오류 코드 할당 | <https://modelcontextprotocol.io/specification/2026-07-28/basic> | 2026-07-28 판 |
| `server/discover`, 자기 신고 `serverInfo` | <https://modelcontextprotocol.io/specification/2026-07-28/server/discover> | 2026-07-28 판 |
| MRTR 흐름과 `requestState` 무결성 규칙 | <https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr> | 2026-07-28 판 |
| `subscriptions/listen` | <https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/subscriptions> | 2026-07-28 판 |
| 트랜스포트별 취소 | <https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/cancellation> | 2026-07-28 판 |
| `ttlMs`, `cacheScope`, 캐시 공유 제한 | <https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/caching> | 2026-07-28 판 |
| stdio 프레이밍과 `stdout` 규칙 | <https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/stdio> | 2026-07-28 판 |
| Streamable HTTP 헤더, `Origin` 검증, 로컬호스트 바인딩 | <https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http> | 2026-07-28 판 |
| `x-mcp-header` 제약, 결정적 도구 정렬 | <https://modelcontextprotocol.io/specification/2026-07-28/server/tools> | 2026-07-28 판 |
| 폐기 레지스트리, 가장 이른 제거 날짜 | <https://modelcontextprotocol.io/specification/2026-07-28/deprecated> | 2026-07-28 판 |
| 릴리스 발표와 무상태 코어 | <https://blog.modelcontextprotocol.io/posts/2026-07-28/> | 2026-07-28 |
| 게재일은 사용 중단일이 아니다 | <https://blog.modelcontextprotocol.io/posts/sdk-betas-2026-07-28/> | 2026-06-29 |
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall