protocol-version-handshake
/protocol-version-handshake
Negotiate the protocol revision explicitly and pin the one the server actually implements. Use when the client may run a different protocol revision than the server was written against
- Author
- Wsh7Ash ↗
- Repository
- skillmcp ↗
- Licence
- MIT
- Last repository change
- 29.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 29.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Negotiate the protocol revision explicitly and pin the one the server actually implements. Use when the client may run a different protocol revision than the server was written against
Original author description
Negotiate the protocol revision explicitly and pin the one the server actually implements. Use when the client may run a different protocol revision than the server was written against
How it works
- Procedure
- Signals
- Patterns
- Pitfalls
- Done when
- References
SKILL.md preview
---
name: protocol-version-handshake
description: "Negotiate the protocol revision explicitly and pin the one the server actually implements. Use when the client may run a different protocol revision than the server was written against"
pack: skillmcp
version: 1.0.0
category: ai-tool
tags: [setup, mcp, protocol]
---
# Protocol Version Handshake
> Negotiate the protocol revision explicitly and pin the one the server actually implements
**Use when:** the client may run a different protocol revision than the server was written against
**Avoid when:** server and client ship together and are upgraded as one unit
## Procedure
1. Read the client's requested protocolVersion from the initialize params
2. Decide the revision the server implements and state it in the response
3. Reject or downgrade gracefully when the client asks for an unsupported revision
4. Record the pinned revision in the README and in a constant
5. Assert the revision in a conformance test so a silent change is caught
6. Log both versions at handshake time to stderr for diagnosis
## Signals
- the initialize response names a revision the server genuinely implements
- a mismatched client revision produces a clear error instead of odd behaviour
- the pinned constant appears in exactly one place in the code
- the conformance test fails when the constant is edited without the docs
## Patterns
**1. Pinned constant**
```text
PROTOCOL_VERSION = "2025-03-26"
```
**2. Response shape**
```text
{"protocolVersion": PROTOCOL_VERSION, "capabilities": {...}}
```
**3. Diagnostic log**
```text
handshake: client=2024-11-05 server=2025-03-26
```
## Pitfalls
- Echoing the client's requested version without implementing it
- Scattering the version string through the code so a change is partial
- Treating a version mismatch as a transport failure and retrying forever
## Done when
- the server names one revision in a single constant and returns it
- a test asserts the returned revision equals the constant
## References
- [MCP - lifecycle](https://modelcontextprotocol.io/specification/2025-03-26/basic/lifecycle)
- [JSON-RPC 2.0](https://www.jsonrpc.org/specification)
Versions
The database has no other skills named protocol-version-handshake.
Database snapshot: 13.11.2026 · package version 2006abc659cd (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100verdi-bus-debug
Use when a bus/handshake is stuck or a transaction never arrives. Drives the protocol-agnostic primitives (signal map, handshake beats, change stats, window scan, declarative checks) and applies protocol rules from this skill's grounding text — the MCP server contains no protocol semantics. - 90esp32-protocol-version-interoperability
Use when designing, reviewing, debugging or validating protocol version interoperability for ESP32 firmware; apply target-specific constraints, failure analysis and measurable verification before release. - 100protocol-conformance-test
Test the wire protocol directly, so a client bug and a server bug are distinguishable. Use when a client reports a failure and the server's own behaviour is unproven - 90revision-lineage
Use when a revision, preview, asset or selection is associated with the wrong version, or viewing an old version silently changes the current one. - 100lifecycle-test-initialize-then-tools
Prove the handshake before the tool list, because a client never calls tools on a failed initialize. Use when a new server is being validated against a real client for the first time - 95bitcoin-p2p
Bitcoin P2P network protocol: messages, version handshake, addr/addrv2, compact blocks (BIP152), compact block filters (BIP157/158), v2 transport encryption (BIP324), wtxid relay (BIP339), Erlay (BIP330), Dandelion++ (BIP156). USE WHEN: implementing/debugging a node, integrating…