Refresh MCP primer to current spec and ecosystem#824
Merged
Conversation
Rewrite to reflect MCP as it stands today: JSON-RPC architecture, the host/client/server roles, the actual primitives (tools, resources, prompts; sampling, roots, elicitation), Streamable HTTP replacing the deprecated SSE transport, OAuth 2.1 authorization, and the official MCP Registry. Removes inaccuracies about a URI-style scheme and a "provenance" envelope that aren't part of the spec, and drops the "shape the spec" framing now that MCP is mainstream. Closes #822 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the ToolHive MCP primer to reflect the current MCP specification and ecosystem, replacing older (mid-2025) framing with an accurate JSON-RPC/session-based description and adding pointers to ToolHive’s related docs.
Changes:
- Replaces the outdated “URI-like scheme” / provenance framing with MCP’s JSON-RPC 2.0 architecture, primitives, and capability negotiation.
- Documents current transports (stdio and Streamable HTTP), notes the SSE deprecation timeline, and adds an OAuth-based authorization overview with links into ToolHive auth docs.
- Adds ecosystem/registry context plus “Next steps” and “Related information” sections aligned with the docs IA.
Distinguish SSE used internally by Streamable HTTP from the separate-endpoints HTTP+SSE transport that's deprecated, so the two mentions of "SSE" don't read as contradictory. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds short take paragraphs in the four framing sections (intro, why-MCP-exists, authorization, where-headed). Architecture, primitives, and transports stay reference-y. Goal is a primer with a point of view, not just an enumeration of facts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add a sentence in the Tools primitive describing optional behavior annotations (read-only, idempotent, destructive) and the spec's advisory-not-authoritative framing. Update "Where MCP is headed" to swap "richer tool annotations" for "trust and provenance signals for tool calls and responses" - matches the actual frontier of community discussion (SEP-1487, content-level provenance, server identity). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Add a sentence in the intro establishing MCP as a Linux Foundation project under the Agentic AI Foundation, naming the eight Founding Platinum members as proof of multi-vendor stewardship. - Note Stacklok's Silver membership and spec contribution alongside the existing ToolHive intro line. - Replace the speculative "richer tool annotations" / "trust and provenance" framing in the headed section with the actual roadmap priorities: stateless transport, Tasks primitive, gateway/proxy patterns, plus the surrounding-layer and horizon items. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Derek2Tu
reviewed
May 5, 2026
- Broaden the intro client list to include autonomous agents alongside the named chat clients. - Note that the MCP auth spec doesn't cover MCP-server-to-upstream auth and link to the backend-auth concept page. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reviewer pointed out that letting agents drive CLI tools directly is a real current alternative to MCP, and the central problem with it - governance over the configuration surface - isn't covered by the existing rows. Adjust the lead-in count and tense to match. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Rewrites
docs/toolhive/concepts/mcp-primer.mdxto reflect MCP as it stands today, replacing several inaccurate claims from the original (mid-2025) version.What changed:
mcp://github?repo=...) that misrepresents MCP as a fetch syntax. MCP is JSON-RPC 2.0; the rewrite leads with that.Grounded against the current MCP docs:
Type of change
Related issues/PRs
Closes #822
Submitter checklist
Content and formatting
🤖 Generated with Claude Code