MCP Protocol Stinger

mcp-protocol Stinger

Procedural arsenal for mcp-protocol-worker-bee, the MCP protocol authority for The Hive.

This stinger encodes the reference material needed to build and audit any MCP server's protocol correctness and tool contract against the MCP specification, @modelcontextprotocol/sdk (or an equivalent), and JSON-RPC 2.0 - plus how to register a server in each of the four harnesses The Hive supports. It is organized around general, server-agnostic guides (00-08), a fully worked example applied to one real server (09, the Hivemind agent-memory server this pair originally shipped for), templates for common deliverables, and worked examples for frequent tasks.

Paired Bee: ../../agents/mcp-protocol-worker-bee.md

First action when this stinger is loaded

Read these in order before doing anything:

1. guides/00-principles.md - spec-first reasoning; tool idempotency + side-effect declaration; tools vs resources vs prompts; JSON-RPC error-code honesty. This is the foundation every other guide builds on.
2. The guide most relevant to the current task (see index below).

Then pick the appropriate template from templates/ for the deliverable the Bee is producing. If the server under review is Hivemind specifically, also read guides/09-hivemind-worked-example.md for the concrete, ground-truthed version of every rule.

Guide index

Template index

Example index

These worked examples are grounded in the Hivemind codebase (see guides/09-hivemind-worked-example.md); the design decisions they walk through generalize per guides/00-08.

Critical directives (lifted from Command Brief)

• Cite the spec section or SDK symbol for every ruling. Why: it is the only way the developer can verify the ruling and learn the principle, not just take the Bee's word.
• Never conflate the JSON-RPC error channel with the tool-result channel. Why: dressing a protocol fault as a success (or vice versa) is the MCP analog of HTTP "200 with error body" and poisons the agent's context.
• The zod import at the SDK boundary MUST be zod/v3. Why: the SDK generates tool JSON Schemas against v3 internals; v4 produces a wrong/empty schema and breaks param validation.
• Treat tool names + arg shapes + parseable output as a cross-harness contract. Why: Hermes, OpenClaw, pi, Claude Code, Codex, and Cursor all depend on them; a rename is breaking, not a refactor.
• Do not audit Deeplake credential/OAuth lifecycle - hand off to security-worker-bee. Do not audit Deeplake query/schema internals - hand off to vector-store-worker-bee.

Scope note: general MCP work vs the Hivemind worked example

This pair originally shipped scoped to one product (Hivemind, an npm-distributed agent-memory MCP server: tools hivemind_search/hivemind_read/hivemind_index, Deep Lake credentials, a mcp/bundle build output). It has been broadened to cover building and auditing MCP servers generally - any tool/resource/prompt design question, any zod schema question, any transport or auth or testing or harness-registration question applies to any MCP server, not just Hivemind's. The Hivemind material was not deleted: it is preserved in full as guides/09-hivemind-worked-example.md, a clearly labeled worked example showing every general principle applied to one real, shipped server. Use guides 00-08 for anything general; use guide 09 when the server actually under review is Hivemind, or when you want to see the general rules exercised end to end.

Folder layout

mcp-protocol-stinger/
+- SKILL.md                                  (this file - master index)
+- README.md                                 (one-page human overview)
+- guides/
|  +- 00-principles.md                       (spec-first reasoning; idempotency; primitives; error honesty)
|  +- 01-transport.md                        (stdio vs HTTP, general; stdio hygiene)
|  +- 02-tool-resource-prompt-design.md      (tool vs resource vs prompt; anatomy of a well-formed tool)
|  +- 03-zod-schemas.md                      (zod input schemas; the versioned v3/v4 SDK trap)
|  +- 04-error-model.md                      (two channels; JSON-RPC codes; classifying raw errors)
|  +- 05-capability-negotiation.md           (initialize/discovery lifecycle; capabilities; deprecated primitives)
|  +- 06-authentication.md                   (auth patterns for remote/HTTP servers: API keys, bearer, OAuth 2.1)
|  +- 07-testing-mcp.md                      (layered testing model; boundary-mock Vitest pattern)
|  +- 08-harness-registration.md             (Claude Code / Cursor / Codex / Cowork registration; the Codex TOML trap; Cowork public-reachability)
|  +- 09-hivemind-worked-example.md          (every principle above, applied to the Hivemind server - WORKED EXAMPLE, not general guidance)
+- examples/
|  +- add-hivemind-tool.md                   (new hivemind_* tool with a zod/v3 schema)
|  +- expose-a-resource.md                   (expose a document as an MCP resource)
|  +- test-mcp-tool.md                       (test an MCP tool with Vitest)
+- templates/
|  +- findings-report.md                     (audit output template)
|  +- tool-contract-checklist.md             (tool well-formedness + contract stability)
|  +- error-channel-matrix.md                (JSON-RPC error vs tool-result routing)
|  +- transport-decision.md                  (stdio vs HTTP + stdio hygiene)
+- reports/
|  +- README.md                              (how audit findings accumulate)
+- research/
   +- distilled-mcp-protocol.md              (NEW - the general MCP distillation: tool/resource/prompt design, zod v3/v4 trap, transport, JSON-RPC, capabilities, auth, testing, four-harness registration)
   +- research-plan.md, research-summary.md, index.md   (original Hivemind-era research trail, kept)
   +- 2026-06-16-*.md                        (6 files, original Hivemind-era MCP SDK + protocol notes, kept)
   +- external/                              (NEW - 8 general-purpose sources archived 2026-08-14: MCP spec pages, zod v3/v4 ecosystem issues, MCP server testing guides)

Part of The Hive, curated by Mario Aldayuz a.k.a @thenotoriousllama.