Skip to main content

Model Context Protocol (MCP): A primer for builders

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.

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. 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 or CLI quickstart.

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:

ApproachProblem
Custom plugin or adapter per data sourceEvery host application needed its own integration; brittle as schemas changed
Stuffing context into the promptBurned tokens, hurt latency, and degraded answers as the prompt grew
Calling REST APIs directly from agent codePushed 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.

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 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. 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 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. 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​

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.

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 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 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 is one such aggregator, and combines the official registry with the curated ToolHive catalog.

Where MCP is headed​

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 track for advanced auth scenarios.

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; proposals and issues are welcome.

Next steps​