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.

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

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

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

Next steps​