From ca34b7663dfab5f92a2f6cb51bd9715772f8b476 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Wed, 29 Apr 2026 17:12:59 -0400 Subject: [PATCH 1/7] Refresh MCP primer to current spec and ecosystem 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) --- docs/toolhive/concepts/mcp-primer.mdx | 215 ++++++++++++++++++-------- 1 file changed, 151 insertions(+), 64 deletions(-) diff --git a/docs/toolhive/concepts/mcp-primer.mdx b/docs/toolhive/concepts/mcp-primer.mdx index ede87e29..04b29ffe 100644 --- a/docs/toolhive/concepts/mcp-primer.mdx +++ b/docs/toolhive/concepts/mcp-primer.mdx @@ -1,72 +1,159 @@ --- -title: 'Model Context Protocol (MCP): A friendly primer for builders' +title: 'Model Context Protocol (MCP): A primer for builders' sidebar_label: MCP primer description: - Model Context Protocol (MCP) connects AI assistants to external tools and data - sources through a standard interface. + What MCP is, how it works, and how it fits into the ecosystem ToolHive + manages. --- -**TL;DR:** MCP offers a pragmatic, language-friendly bridge between -probabilistic code generators and the real-world systems where your source of -truth lives. It's young, but it already solves pain points around context size, -adapter sprawl, and brittle prompts—thanks largely to an open, welcoming -developer community. If you're building next-gen coding tools, now's the ideal -moment to give MCP a spin and leave your fingerprints on the spec. - -## Why we needed something new - -Modern code-generation models work by guessing the next token from probability -space. By nature they are powerful but probabilistic and work with natural -language. Context drives everything and they can only work on what they can see. -Most real-world context developers use lives outside the model: in GitHub repos, -API docs, RFCs, and issue trackers. Bridging that gap has been messy: - -| Traditional approach | Pain point for GenAI tools | -| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | -| Custom adapters / plugins per data source | Hard to keep in sync; brittle when schemas change | -| Prompt stuffing (copy-pasting docs into the prompt) | Dilutes effectiveness and reduces response acceptance rates, bloats token budget, hurts latency & cost | -| REST APIs with rigid schemas | Fine for deterministic code, awkward for probabilistic LLMs that prefer natural language | - -MCP tackles these headaches by letting a model **ask external systems for facts -or files using a concise, natural syntax that itself is easy for generative -models to emit and parse.** - -## What problems does MCP solve? - -- **Token-efficient context retrieval** \ - _One-shot, structured queries_ (e.g., - `mcp://github?repo=owner/project\&path=README.md`) let the model fetch exactly - what it needs—no boilerplate, no giant system prompts. -- **Natural-language-friendly envelope** \ - The URI-like syntax is short, deterministic, yet readable enough that an LLM - can generate it without dedicated training. Embeddings created before MCP work - just fine with MCP. -- **Uniform surface over heterogeneous data** \ - Git blobs, Swagger files, Confluence pages, or a private vector store all look - like "resources" under the same scheme. Tool builders write one resolver and - get many back-ends without additional work. -- **Graceful failure semantics** \ - Every MCP response carries both _content_ and a lightweight _provenance_ - object (source, timestamp, hash). Models can decide to retry, ignore, or cite. - -## The emergence of open community - -A community has sprung up around the MCP protocol incredibly quickly. - -The spec is Apache-licensed and refreshingly small, clean, and simple, which -makes the whole thing pretty easy to grok. SDK's abound and thousands of -examples exist. The efforts of communities like golang with the go-mcp release -in April 2025 are moving server development beyond the boundaries of the -traditional JavaScript and Python ecosystems. The Golang portfolio servers -inventory is growing incredibly quickly and with it comes a wealth of production -oriented access to resources. - -There's no governing foundation yet, but a lightweight steering group triages -PRs and publishes version tags. +The Model Context Protocol (MCP) is an open standard for connecting AI +applications to external data, tools, and workflows. With MCP, an AI application +like Claude, ChatGPT, or Cursor can read files, query databases, call APIs, or +trigger workflows through one well-defined protocol instead of a custom +integration per service. + +ToolHive runs and manages MCP servers. This primer explains what MCP is, how it +works, and what's happening in the ecosystem around it. If you're new to MCP, +read this before diving into the +[ToolHive UI quickstart](../guides-ui/quickstart.mdx) or +[CLI quickstart](../guides-cli/quickstart.mdx). + +## Why MCP exists + +Large language models (LLMs) are powerful, but they only work with the context +they can see. The context developers care about - source code, documentation, +tickets, metrics, internal APIs - lives outside the model. Bridging that gap +used to mean one of three uncomfortable options: + +| Approach | Problem | +| ------------------------------------------ | --------------------------------------------------------------------------------- | +| Custom plugin or adapter per data source | Every host application needed its own integration; brittle as schemas changed | +| Stuffing context into the prompt | Burned tokens, hurt latency, and degraded answers as the prompt grew | +| Calling REST APIs directly from agent code | Pushed authentication, error handling, and tool descriptions into the application | + +MCP replaces these with a single protocol that an AI application speaks once and +reuses across any compliant server. The protocol handles capability discovery, +structured tool invocation, and authorization, so server authors can focus on +the integration itself. + +## How MCP works + +MCP uses [JSON-RPC 2.0](https://www.jsonrpc.org/) over a stateful session. The +spec borrows from the Language Server Protocol: standardize the wire format and +the lifecycle once, and a whole ecosystem of clients and servers becomes +interoperable. + +### Architecture + +MCP defines three roles: + +- **Host** - the AI application itself (Claude Desktop, Visual Studio Code (VS + Code) with GitHub Copilot, Cursor, a custom agent). The host enforces user + consent, manages credentials, and routes context to the model. +- **Client** - a connector inside the host. Each client maintains a 1:1 + connection with one server and isolates that server from the rest of the + session. +- **Server** - a process that exposes capabilities through the MCP interface. + Servers can run locally or remotely. + +A session begins with _capability negotiation_: client and server each declare +which features they support, and only those features are available for the rest +of the connection. This keeps the protocol extensible without breaking older +implementations. + +### Protocol primitives + +Servers expose three primitives to clients: + +- **Tools** - functions the model can call (for example, "search the codebase" + or "create a Jira ticket"). Tool calls are structured, with JSON schemas for + inputs and outputs. +- **Resources** - data the host or model can read (files, database rows, API + responses). Resources are addressable and can be subscribed to for updates. +- **Prompts** - templated workflows the user can invoke (for example, "summarize + this PR"). + +Clients can also expose primitives back to servers: + +- **Sampling** - lets a server ask the host's model to complete a prompt, with + user approval. +- **Roots** - tells the server which directories or URIs it's allowed to operate + on. +- **Elicitation** - lets a server request additional input from the user + mid-session. + +### Transports + +The current spec defines two standard transports: + +- **stdio** - the host launches the server as a subprocess and exchanges + newline-delimited JSON-RPC messages over stdin and stdout. This is the + preferred transport for local servers. +- **Streamable HTTP** - the server runs as an independent HTTP service exposing + a single endpoint that handles JSON-RPC over POST and GET, optionally + upgrading to Server-Sent Events for streaming. This is the transport for + remote and networked servers. + +The older HTTP+SSE transport from the 2024-11-05 revision is deprecated; +Streamable HTTP replaced it in 2025-03-26. Custom transports are allowed as long +as they preserve the JSON-RPC message format and lifecycle. + +### Authorization + +For HTTP transports, MCP defines an OAuth 2.1-based authorization flow. The MCP +server acts as an OAuth resource server; the client obtains a token from an +authorization server and presents it as a bearer token on each request. PKCE, +audience-bound tokens (RFC 8707), and Protected Resource Metadata (RFC 9728) are +required to prevent token misuse and confused-deputy attacks. The stdio +transport doesn't use OAuth - servers read credentials from the environment. + +ToolHive sits in front of MCP servers as a gateway and handles the operational +parts of this model for you. See +[Authentication and authorization](./auth-framework.mdx) for the details. + +## The ecosystem + +MCP support is broad across host applications: Claude, ChatGPT, GitHub Copilot +in VS Code, Cursor, MCPJam, and many others. Official SDKs cover the major +languages, including TypeScript, Python, Go, Java, Kotlin, C#, and Rust, with +community ports beyond that. + +The official [MCP Registry](https://modelcontextprotocol.io/registry/about) is +the canonical metadata index for publicly accessible servers, backed by +Anthropic, GitHub, PulseMCP, and Microsoft. The registry doesn't host server +code - it stores `server.json` metadata pointing to the underlying package (npm, +PyPI, Docker Hub) or remote endpoint, with namespace authentication via DNS or +GitHub identity. The registry is consumed primarily by downstream aggregators +and host applications. ToolHive's +[Registry Server](../guides-registry/index.mdx) is one such aggregator, and +combines the official registry with the curated ToolHive catalog. ## Where MCP is headed -Expect iterative, community-driven releases—v1.0 is slated for late 2025 with a -stable core and optional capability sets (search, write-back, streaming). The -protocol's youth means rough edges, but that also means **you can still shape -it**: file issues, prototype adapters, or just lurk and learn. +The spec uses dated revisions (2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25) +rather than semver, with the `MCP-Protocol-Version` header allowing clients and +servers to negotiate compatibility. The core protocol is deliberately small; new +capabilities arrive as additive extensions, including a separate +[authorization extensions](https://github.com/modelcontextprotocol/ext-auth) +track for advanced auth scenarios. + +Active areas of evolution include richer tool annotations, structured tool +output, resource subscriptions, interactive apps that render inside hosts (MCP +Apps), and deeper registry tooling. The spec is open and actively maintained on +[GitHub](https://github.com/modelcontextprotocol/specification); proposals and +issues are welcome. + +## Next steps + +- [ToolHive UI quickstart](../guides-ui/quickstart.mdx) - run your first MCP + server through the desktop app. +- [ToolHive CLI quickstart](../guides-cli/quickstart.mdx) - run MCP servers from + the command line. +- [Authentication and authorization](./auth-framework.mdx) - how ToolHive + secures MCP servers. + +## Related information + +- [Official MCP documentation](https://modelcontextprotocol.io) +- [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25) +- [MCP Registry](https://modelcontextprotocol.io/registry/about) From 541f23bac498f31c32b6b3bce1e816f25a116840 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Wed, 29 Apr 2026 17:25:30 -0400 Subject: [PATCH 2/7] Clarify Streamable HTTP vs deprecated HTTP+SSE 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) --- docs/toolhive/concepts/mcp-primer.mdx | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/toolhive/concepts/mcp-primer.mdx b/docs/toolhive/concepts/mcp-primer.mdx index 04b29ffe..bd9ad8d8 100644 --- a/docs/toolhive/concepts/mcp-primer.mdx +++ b/docs/toolhive/concepts/mcp-primer.mdx @@ -90,13 +90,15 @@ The current spec defines two standard transports: newline-delimited JSON-RPC messages over stdin and stdout. This is the preferred transport for local servers. - **Streamable HTTP** - the server runs as an independent HTTP service exposing - a single endpoint that handles JSON-RPC over POST and GET, optionally - upgrading to Server-Sent Events for streaming. This is the transport for - remote and networked servers. - -The older HTTP+SSE transport from the 2024-11-05 revision is deprecated; -Streamable HTTP replaced it in 2025-03-26. Custom transports are allowed as long -as they preserve the JSON-RPC message format and lifecycle. + a single endpoint that handles JSON-RPC over POST and GET. The server can open + a Server-Sent Events (SSE) stream as part of a response when it needs to push + multiple messages back. This is the current transport for remote and networked + servers. + +The earlier HTTP+SSE transport (separate POST and SSE endpoints, defined in the +2024-11-05 revision) is deprecated; Streamable HTTP replaced it in 2025-03-26. +Custom transports are allowed as long as they preserve the JSON-RPC message +format and lifecycle. ### Authorization From 689484b96c22fec87c0a0e1dd52ce9641eaf5a2d Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Wed, 29 Apr 2026 17:48:23 -0400 Subject: [PATCH 3/7] Add some opinionated framing to the MCP primer 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) --- docs/toolhive/concepts/mcp-primer.mdx | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/docs/toolhive/concepts/mcp-primer.mdx b/docs/toolhive/concepts/mcp-primer.mdx index bd9ad8d8..8d55a6d1 100644 --- a/docs/toolhive/concepts/mcp-primer.mdx +++ b/docs/toolhive/concepts/mcp-primer.mdx @@ -12,6 +12,11 @@ like Claude, ChatGPT, or Cursor can read files, query databases, call APIs, or trigger workflows through one well-defined protocol instead of a custom integration per service. +This is the first integration layer the AI ecosystem has actually rallied +behind. Earlier attempts stayed vendor-specific or model-specific; MCP landed at +the right moment with a small, opinionated spec and broad early adoption from +the major host applications. + ToolHive runs and manages MCP servers. This primer explains what MCP is, how it works, and what's happening in the ecosystem around it. If you're new to MCP, read this before diving into the @@ -36,6 +41,12 @@ reuses across any compliant server. The protocol handles capability discovery, structured tool invocation, and authorization, so server authors can focus on the integration itself. +What's different this time is what the spec leaves out. MCP is small enough to +read in one sitting, uses JSON-RPC instead of inventing a new wire format, and +treats capability negotiation as extensibility rather than versioning. Hosts can +adopt it incrementally; simple servers can be a few hundred lines of code. That +low ceiling on the easy case is most of why MCP spread the way it did. + ## How MCP works MCP uses [JSON-RPC 2.0](https://www.jsonrpc.org/) over a stateful session. The @@ -109,8 +120,11 @@ audience-bound tokens (RFC 8707), and Protected Resource Metadata (RFC 9728) are required to prevent token misuse and confused-deputy attacks. The stdio transport doesn't use OAuth - servers read credentials from the environment. -ToolHive sits in front of MCP servers as a gateway and handles the operational -parts of this model for you. See +The auth model is sound, but it's a lot for a single server to get right: +discovery, dynamic registration, token validation, audience binding, scope +handling. ToolHive sits in front of MCP servers as a gateway and absorbs that +complexity centrally, so individual servers don't each need to reimplement the +protocol's hard parts. See [Authentication and authorization](./auth-framework.mdx) for the details. ## The ecosystem @@ -139,9 +153,12 @@ capabilities arrive as additive extensions, including a separate [authorization extensions](https://github.com/modelcontextprotocol/ext-auth) track for advanced auth scenarios. -Active areas of evolution include richer tool annotations, structured tool -output, resource subscriptions, interactive apps that render inside hosts (MCP -Apps), and deeper registry tooling. The spec is open and actively maintained on +The shape-from-scratch moment has passed - the core protocol is settled and the +major host applications are shipping against it. The interesting churn is now in +the surrounding layers rather than the protocol itself: richer tool annotations, +structured tool output, resource subscriptions, interactive apps that render +inside hosts (MCP Apps), and the registry. Builders who get familiar with MCP +now will be early to those layers as they land. The spec is openly maintained on [GitHub](https://github.com/modelcontextprotocol/specification); proposals and issues are welcome. From caa2606b274e0280a2b5225e448df0baa25b0f6c Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 30 Apr 2026 10:57:07 -0400 Subject: [PATCH 4/7] Note tool annotations and trust direction in primer 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) --- docs/toolhive/concepts/mcp-primer.mdx | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/toolhive/concepts/mcp-primer.mdx b/docs/toolhive/concepts/mcp-primer.mdx index 8d55a6d1..7937e87f 100644 --- a/docs/toolhive/concepts/mcp-primer.mdx +++ b/docs/toolhive/concepts/mcp-primer.mdx @@ -78,7 +78,10 @@ Servers expose three primitives to clients: - **Tools** - functions the model can call (for example, "search the codebase" or "create a Jira ticket"). Tool calls are structured, with JSON schemas for - inputs and outputs. + inputs and outputs. Tools may also carry annotations that hint at behavior - + read-only, idempotent, destructive - which hosts can use to gate or surface + the call. The spec treats those hints as advisory rather than authoritative, + so they're only as trustworthy as the server providing them. - **Resources** - data the host or model can read (files, database rows, API responses). Resources are addressable and can be subscribed to for updates. - **Prompts** - templated workflows the user can invoke (for example, "summarize @@ -155,10 +158,11 @@ track for advanced auth scenarios. The shape-from-scratch moment has passed - the core protocol is settled and the major host applications are shipping against it. The interesting churn is now in -the surrounding layers rather than the protocol itself: richer tool annotations, -structured tool output, resource subscriptions, interactive apps that render -inside hosts (MCP Apps), and the registry. Builders who get familiar with MCP -now will be early to those layers as they land. The spec is openly maintained on +the surrounding layers rather than the protocol itself: trust and provenance +signals for tool calls and responses, structured tool output, resource +subscriptions, interactive apps that render inside hosts (MCP Apps), and the +registry. Builders who get familiar with MCP now will be early to those layers +as they land. The spec is openly maintained on [GitHub](https://github.com/modelcontextprotocol/specification); proposals and issues are welcome. From af21a896f3dd0ebf4530d24af3187d81d3d23398 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 30 Apr 2026 15:26:37 -0400 Subject: [PATCH 5/7] Note AAIF stewardship and re-anchor headed section to roadmap - 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) --- docs/toolhive/concepts/mcp-primer.mdx | 31 ++++++++++++++++----------- 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/docs/toolhive/concepts/mcp-primer.mdx b/docs/toolhive/concepts/mcp-primer.mdx index 7937e87f..fe080f5f 100644 --- a/docs/toolhive/concepts/mcp-primer.mdx +++ b/docs/toolhive/concepts/mcp-primer.mdx @@ -15,11 +15,16 @@ integration per service. This is the first integration layer the AI ecosystem has actually rallied behind. Earlier attempts stayed vendor-specific or model-specific; MCP landed at the right moment with a small, opinionated spec and broad early adoption from -the major host applications. - -ToolHive runs and manages MCP servers. This primer explains what MCP is, how it -works, and what's happening in the ecosystem around it. If you're new to MCP, -read this before diving into the +the major host applications. As of December 2025, MCP is also a Linux Foundation +project under the new Agentic AI Foundation, jointly stewarded by Anthropic, +AWS, Block, Bloomberg, Cloudflare, Google, Microsoft, and OpenAI as Founding +Platinum members - meaningful because earlier integration attempts had no +equivalent neutral home. + +ToolHive runs and manages MCP servers. Stacklok, the company behind ToolHive, is +a Silver member of AAIF and an active contributor to the MCP spec. This primer +explains what MCP is, how it works, and what's happening in the ecosystem around +it. If you're new to MCP, read this before diving into the [ToolHive UI quickstart](../guides-ui/quickstart.mdx) or [CLI quickstart](../guides-cli/quickstart.mdx). @@ -156,13 +161,15 @@ capabilities arrive as additive extensions, including a separate [authorization extensions](https://github.com/modelcontextprotocol/ext-auth) track for advanced auth scenarios. -The shape-from-scratch moment has passed - the core protocol is settled and the -major host applications are shipping against it. The interesting churn is now in -the surrounding layers rather than the protocol itself: trust and provenance -signals for tool calls and responses, structured tool output, resource -subscriptions, interactive apps that render inside hosts (MCP Apps), and the -registry. Builders who get familiar with MCP now will be early to those layers -as they land. The spec is openly maintained on +The shape-from-scratch moment has passed. The current roadmap puts +production-readiness ahead of protocol greenfield: scaling Streamable HTTP +statelessly behind load balancers, hardening the new Tasks primitive for +long-running async tool calls, and formalizing the gateway and proxy patterns +enterprises are already building. Surrounding-layer work continues - MCP Apps, +structured tool output, conformance test suites, and the registry - and a +horizon track covers triggers, result streaming, and finer-grained auth. +Builders who get familiar with MCP now will be early to those layers as they +land. The spec is openly maintained on [GitHub](https://github.com/modelcontextprotocol/specification); proposals and issues are welcome. From a5d71a7562223e43409d47a9a3d82fe18182fcb7 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Tue, 5 May 2026 21:21:34 -0400 Subject: [PATCH 6/7] Address review: agents in intro, backend auth callout - 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) --- docs/toolhive/concepts/mcp-primer.mdx | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/toolhive/concepts/mcp-primer.mdx b/docs/toolhive/concepts/mcp-primer.mdx index fe080f5f..7f8b4ed0 100644 --- a/docs/toolhive/concepts/mcp-primer.mdx +++ b/docs/toolhive/concepts/mcp-primer.mdx @@ -8,9 +8,9 @@ description: The Model Context Protocol (MCP) is an open standard for connecting AI applications to external data, tools, and workflows. With MCP, an AI application -like Claude, ChatGPT, or Cursor can read files, query databases, call APIs, or -trigger workflows through one well-defined protocol instead of a custom -integration per service. +like Claude, ChatGPT, Cursor, or a custom autonomous agent can read files, query +databases, call APIs, or trigger workflows through one well-defined protocol +instead of a custom integration per service. This is the first integration layer the AI ecosystem has actually rallied behind. Earlier attempts stayed vendor-specific or model-specific; MCP landed at @@ -135,6 +135,11 @@ complexity centrally, so individual servers don't each need to reimplement the protocol's hard parts. See [Authentication and authorization](./auth-framework.mdx) for the details. +One thing the MCP auth spec doesn't cover: how an MCP server authenticates to +the upstream services it fronts - a GitHub token, an Atlassian credential, a +database password. That's left to the implementation, and ToolHive handles it +too. See [Backend authentication](./backend-auth.mdx) for the approach. + ## The ecosystem MCP support is broad across host applications: Claude, ChatGPT, GitHub Copilot From 3c9cc18328b3a605654002a16affcae23fbfe840 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Tue, 5 May 2026 21:27:42 -0400 Subject: [PATCH 7/7] Add CLI-driven agents row to "Why MCP exists" table 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) --- docs/toolhive/concepts/mcp-primer.mdx | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/toolhive/concepts/mcp-primer.mdx b/docs/toolhive/concepts/mcp-primer.mdx index 7f8b4ed0..2f57495e 100644 --- a/docs/toolhive/concepts/mcp-primer.mdx +++ b/docs/toolhive/concepts/mcp-primer.mdx @@ -32,14 +32,15 @@ it. If you're new to MCP, read this before diving into the Large language models (LLMs) are powerful, but they only work with the context they can see. The context developers care about - source code, documentation, -tickets, metrics, internal APIs - lives outside the model. Bridging that gap -used to mean one of three uncomfortable options: - -| Approach | Problem | -| ------------------------------------------ | --------------------------------------------------------------------------------- | -| Custom plugin or adapter per data source | Every host application needed its own integration; brittle as schemas changed | -| Stuffing context into the prompt | Burned tokens, hurt latency, and degraded answers as the prompt grew | -| Calling REST APIs directly from agent code | Pushed authentication, error handling, and tool descriptions into the application | +tickets, metrics, internal APIs - lives outside the model. Bridging that gap has +meant one of four uncomfortable options: + +| Approach | Problem | +| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | +| Custom plugin or adapter per data source | Every host application needed its own integration; brittle as schemas changed | +| Stuffing context into the prompt | Burned tokens, hurt latency, and degraded answers as the prompt grew | +| Calling REST APIs directly from agent code | Pushed authentication, error handling, and tool descriptions into the application | +| Letting agents call CLI tools directly | No structured input or output, and no easy way to govern which commands or flags the agent is allowed to invoke | MCP replaces these with a single protocol that an AI application speaks once and reuses across any compliant server. The protocol handles capability discovery,