Skip to content
Skills Library
Programming · Building & coding

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

Repository
skillmcp ↗
Licence
MIT
Last repository change
29.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 29.10.2026, without references to retired models or APIs.

Licence

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

  1. Procedure
  2. Signals
  3. Patterns
  4. Pitfalls
  5. Done when
  6. References
Original SKILL.md headings · 61 lines, 271 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.