The MCP primer at docs/toolhive/concepts/mcp-primer.mdx was written in mid-2025 and is now significantly out of date with both the protocol and the ecosystem around it. Several claims are misleading or factually incorrect for someone using it as an introduction today.
Specific issues
Protocol mechanics are misrepresented. The doc frames MCP as a "URI-like" scheme with examples like mcp://github?repo=owner/project&path=README.md. MCP is a JSON-RPC 2.0 protocol with defined primitives (tools, resources, prompts), not a URI fetch syntax. The example URI doesn't reflect anything real about how MCP actually works. This is the most important fix - readers come away with a wrong mental model.
The provenance claim is wrong. The doc states "Every MCP response carries both content and a lightweight provenance object (source, timestamp, hash)." This is not part of the MCP spec. Responses carry content (text, image, resource references, structured output), but there's no standardized provenance envelope.
The embeddings line is a non sequitur. "Embeddings created before MCP work just fine with MCP" doesn't really mean anything - MCP isn't about embeddings.
Roadmap and governance are stale.
- "v1.0 is slated for late 2025" - we're past that. The spec uses dated revisions (2024-11-05, 2025-03-26, 2025-06-18, etc.); we should describe the actual versioning model.
- "No governing foundation yet, but a lightweight steering group triages PRs" - governance has evolved; needs verification against the current state.
- "go-mcp release in April 2025" reads as breaking news but is now a year old. The Go ecosystem (and others) has matured well past that milestone.
Major protocol developments are missing.
- Streamable HTTP transport (replaced SSE in the 2025-03-26 revision) - significant for how ToolHive users actually deploy servers.
- OAuth 2.1 authorization flow - directly relevant to ToolHive's auth integrations.
- Elicitation, sampling, structured tool output, tool annotations, resource subscriptions.
Tone and framing. Some phrasing ("leave your fingerprints on the spec," "now's the ideal moment to give MCP a spin") was apt for early 2025 but reads oddly now that MCP is mainstream. The "Why we needed something new" framing is still useful but the comparison table should be tightened.
Proposed approach
Rewrite as a current-state primer:
- What MCP is (JSON-RPC, client/server, primitives: tools/resources/prompts).
- What problems it solves (keep the spirit of the existing section, but ground examples in real MCP mechanics).
- Transports (stdio, Streamable HTTP) and where each fits.
- Auth model in one paragraph, with a link to deeper auth docs.
- Ecosystem snapshot (SDKs across languages, registry-driven discovery, ToolHive's role).
- Where to go next - drop the "shape the spec" framing in favor of links to the spec, ToolHive quickstarts, and the registry.
The page is in concepts/, so it should remain explanation-flavored (Diataxis), not a how-to.
The MCP primer at
docs/toolhive/concepts/mcp-primer.mdxwas written in mid-2025 and is now significantly out of date with both the protocol and the ecosystem around it. Several claims are misleading or factually incorrect for someone using it as an introduction today.Specific issues
Protocol mechanics are misrepresented. The doc frames MCP as a "URI-like" scheme with examples like
mcp://github?repo=owner/project&path=README.md. MCP is a JSON-RPC 2.0 protocol with defined primitives (tools, resources, prompts), not a URI fetch syntax. The example URI doesn't reflect anything real about how MCP actually works. This is the most important fix - readers come away with a wrong mental model.The provenance claim is wrong. The doc states "Every MCP response carries both content and a lightweight provenance object (source, timestamp, hash)." This is not part of the MCP spec. Responses carry content (text, image, resource references, structured output), but there's no standardized provenance envelope.
The embeddings line is a non sequitur. "Embeddings created before MCP work just fine with MCP" doesn't really mean anything - MCP isn't about embeddings.
Roadmap and governance are stale.
Major protocol developments are missing.
Tone and framing. Some phrasing ("leave your fingerprints on the spec," "now's the ideal moment to give MCP a spin") was apt for early 2025 but reads oddly now that MCP is mainstream. The "Why we needed something new" framing is still useful but the comparison table should be tightened.
Proposed approach
Rewrite as a current-state primer:
The page is in
concepts/, so it should remain explanation-flavored (Diataxis), not a how-to.