Model Context Protocol (MCP)

This content was generated with the assistance of AI and should be verified against the official documentation of each tool and framework before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

This sub-section was written against the 2026-07-28 revision of the Model Context Protocol specification and the SDK, framework and host versions listed in Version baseline, all read from PyPI, npm, Maven Central and the official documentation on 2026-09-29. Where an individual page and that baseline ever disagree after a later update, the baseline is the one to trust.

Why MCP exists: the N x M problem

Before a standard existed, connecting an AI application to a tool or a data source meant writing an integration for that one pair: a Claude Code plugin for the issue tracker, a different VS Code extension for the same tracker, a hand-rolled function for a home-grown agent. With N hosts (AI applications) and M tools that is up to N x M integrations, each with its own authentication, schema mapping and failure modes. The Model Context Protocol (MCP) replaces that grid with one protocol: a host embeds an MCP client once, a tool or data source exposes an MCP server once, and any client can talk to any server — N + M implementations instead of N x M.

Two panels. On the left, without a standard, four hosts (Claude Code, VS Code with Copilot, Claude Desktop and a custom agent) are each wired to each of four tools (docs search, Postgres, GitHub and an issue tracker) with sixteen separate lines. On the right, with MCP, the same four hosts each act as an MCP client and the same four tools each expose an MCP server, all connected through a single MCP box that carries JSON-RPC 2.0 messages for tools, resources and prompts, giving eight implementations.
Figure 1. The N x M integration problem, and N + M with MCP

An MCP server exposes three kinds of capability to the model: tools (functions the model can call), resources (data the application can read, addressed by URI) and prompts (reusable message templates the user can pick), and can ask the user for missing information through elicitation. Messages are JSON-RPC 2.0 and travel over stdio for local servers or Streamable HTTP for remote ones. The details are on MCP Architecture, Tools, Resources, Prompts & Elicitation and Transports; this page only orients you and lists the sources.

Governance

MCP was introduced by Anthropic and is now an open standard governed under the Linux Foundation, which formed the Agentic AI Foundation (AAIF) as a neutral home for open agent standards, starting with MCP; its sibling protocol, Agent2Agent (A2A), is a separate Linux Foundation project, and Agent-to-Agent Protocol (A2A) explains how the two fit together. The specification is versioned by date, changes are proposed and decided in the open as Specification Enhancement Proposals (SEPs, the numbers quoted in the release blog), and SDKs are ranked in tiers by how completely and promptly they follow it (see the SDK table under Other SDK languages). Sources are in the Bibliography: the Linux Foundation announcement and the versioning page.

Three revisions in thirteen months

Protocol revisions are named by date. The three most recent ones changed different layers of the protocol, and the last one changed the shape of it:

Revision What changed

2025-06-18

JSON-RPC batching removed; structured tool output (outputSchema) added; servers classified as OAuth resource servers, with Protected Resource Metadata (RFC 9728) to find the authorization server; clients required to use resource indicators (RFC 8707); elicitation and resource links in tool results added; the negotiated protocol version had to be sent in an MCP-Protocol-Version header over HTTP.

2025-11-25

OpenID Connect Discovery accepted for authorization-server discovery; icons for tools, resources and prompts; incremental scope consent through WWW-Authenticate; URL-mode elicitation; tool calling inside sampling; Client ID Metadata Documents (CIMD) recommended for client registration; experimental Tasks for durable, pollable requests; JSON Schema 2020-12 made the default dialect; SSE streams that servers may close and clients poll.

2026-07-28

A stateless core: the initialize handshake and the Mcp-Session-Id header are gone, every request carries its protocol version, client information and capabilities in _meta, and an optional server/discover call replaces the handshake for clients that want capabilities up front. Server-to-client requests are redesigned as Multi Round-Trip Requests (resultType input_required). Streamable HTTP requests must carry Mcp-Method and Mcp-Name headers so gateways can route without parsing bodies. List results carry ttlMs and cacheScope and a deterministic order. A single subscriptions/listen stream replaces the GET endpoint. A formal extensions framework takes Tasks out of the core (io.modelcontextprotocol/tasks). Authorization is hardened: RFC 9207 iss validation, credentials bound to their issuer, and CIMD replaces Dynamic Client Registration (DCR), which is deprecated. Roots, sampling, logging and the HTTP+SSE transport are deprecated under a formal policy with a twelve-month minimum window, and ping and logging/setLevel are removed.

Two consequences follow for anyone reading older material, including the books in the bibliography, which all predate the 2026-07-28 revision: the initialize handshake, sessions and Mcp-Session-Id, the old FastMCP class name in the official Python SDK (now MCPServer), and the v1 TypeScript package @modelcontextprotocol/sdk describe the previous protocol era. Each page flags that behaviour where it matters and shows the current API, and the architecture page covers the history in one place.

Version baseline

Every version below was read from the package registries, the official documentation and the running servers built for this sub-section on 2026-09-29. Each page repeats the subset it uses in its own lead paragraph.

Area Versions

Protocol

Specification revision 2026-07-28, with the previous revisions 2025-11-25 and 2025-06-18 described on this page.

Python

Python 3.12 (the mcp package requires 3.10 or newer); the official mcp SDK 2.2.0 (MCPServer); the standalone fastmcp 4.0.10 (needs mcp 2); FastAPI 0.141.1. The community fastapi-mcp 0.4.0 and langchain-mcp-adapters 0.3.2 are built on mcp 1 (mcp below 2.0 for the adapters): installing either into an environment that has mcp 2 downgrades it to 1.30.0 and breaks FastMCP 4, so this sub-section runs them in a separate virtual environment.

Java

Java 21; Spring Boot 4.1.1 with Spring AI 2.0.1 (GA; 2.1.0-M1 exists but is a milestone and is not used); the MCP Java SDK 2.0.1 (Spring AI 2.0.1 resolves 2.0.0); LangChain4j MCP langchain4j-mcp 1.20.2-beta30.

TypeScript

Node.js 24 LTS (Krypton; runs used v24.20.0, 24.21.0 was current on 2026-09-07; Node.js 26 is the current release but not yet LTS); @modelcontextprotocol/server and @modelcontextprotocol/client 2.2.0, @modelcontextprotocol/express 2.0.1, @modelcontextprotocol/node 2.1.0; Zod 4.6.5; TypeScript 7.0.2; Express 5.2.1.

Tooling

MCP Inspector 2.8.0 (mcp-inspector); uv for Python environments; Maven 3.9.16.

Models and stores

Ollama with llama3.1:8b for chat and nomic-embed-text for embeddings, and the pgvector store of PostgreSQL & pgvector behind the search tool — the same as the rest of the AI section. Any of the hosted models used elsewhere (claude-sonnet-5, claude-opus-5-5, claude-haiku-4-5, claude-fable-5-1, gpt-6-sol) is a drop-in replacement.

The Java protocol-version skew

The Java stack lags the specification, and this sub-section says so rather than hiding it. The MCP Java SDK 2.0.x defines protocol versions only up to 2025-11-25, and Spring AI 2.0.1 builds on it, so a Spring AI MCP server has no server/discover and no multi-round-trip elicitation: it answers a 2026-07-28 client’s initialize with 2025-11-25, and calling server/discover fails (a "method not found" error on the Streamable mode, an internal error on the stateless mode). The Spring AI reference still describes its Streamable-HTTP servers as introduced with spec version 2025-03-26 and does not mention 2026-07-28. Consequently the Java build of docs-assistant is tested with the Inspector in its legacy protocol era and has no elicitation step, and its component argument is required. The Java SDK is a Tier 2 SDK on the official SDK list, not one of the SDKs updated in the release blog. The details and the practical consequences are on Spring Boot MCP Servers.

What’s covered

The sub-section builds one running example, the docs-assistant MCP server — the MCP-facing side of the DocsAssistant scenario used in LLM Foundations & Prompting, AI Agents and Vector Databases & RAG. It exposes this site’s documentation through the same four things on every stack:

  • a tool search_docs(query, component?, top_k) that returns structuredContent (hits with title, URL, snippet and score) together with an outputSchema;

  • a resource template docs://{component}/{page} that returns a page’s AsciiDoc;

  • a prompt answer_with_citations;

  • an elicitation through a Multi Round-Trip Request that asks which component to search when the query is ambiguous.

It is built three times — Python, Java and TypeScript — and each build passes the same Inspector CLI contract script, shown once on Testing & Debugging. The pages are grouped the same way as the navigation:

Concepts

  • MCP Architecture — hosts, clients and servers, JSON-RPC 2.0, the stateless core and _meta negotiation, server/discover, extensions, trace context, and one full discover, list and call exchange in three languages.

  • Tools, Resources, Prompts & Elicitation — tools with inputSchema, outputSchema and structuredContent, resources and URI templates, prompts, elicitation through input_required, cacheable lists, and the deprecated roots, sampling and logging.

  • Transports — stdio, Streamable HTTP with the Mcp-Method and Mcp-Name headers, subscriptions/listen, why HTTP+SSE is deprecated, load balancing without sticky sessions, and a curl walkthrough.

  • Authorization — OAuth 2.1 for remote servers, Protected Resource Metadata, resource indicators, CIMD versus DCR, RFC 9207, audience binding and no token passthrough.

Building servers

  • Python MCP Servers — the official mcp v2 MCPServer, stdio and Streamable HTTP, the FastMCP to MCPServer rename and the standalone FastMCP 4.

  • MCP inside FastAPI — mounting MCP in a FastAPI process, the lifespan pitfall, FastMCP’s combine_lifespans, generated versus curated tools, and sharing authentication.

  • Spring Boot MCP Servers — the Spring AI 2.0 starters, the STREAMABLE, STATELESS and SSE modes, @McpTool and its siblings, Spring Security, the plain Java SDK and the protocol-version caveat.

  • Node.js MCP Servers — @modelcontextprotocol/server v2, registerTool with Zod, serveStdio(), the Express adapter and migrating from the v1 SDK.

Clients and hosts

  • Building MCP Clients — Python, Java and TypeScript clients, handling input_required, LangChain adapters and a local Ollama model driving MCP tools.

  • Connecting Hosts — Claude Code, Claude Desktop, VS Code and GitHub Copilot, and the Copilot cloud agent, with pointers to other hosts.

Testing and deployment

  • Testing & Debugging — the MCP Inspector, the shared contract test, a CI recipe, logging to stderr and OpenTelemetry, and common errors and their fixes.

  • Deploying Remote Servers — a Dockerfile per stack, stateless scaling, capacity math, gateways that route on Mcp-Method, TLS, rate limits and the MCP Registry.

Design and integration

  • Designing Good MCP Servers — tool design rules for LLM callers, curated versus generated tools, the token cost of tool definitions and code execution with MCP.

  • Exposing RAG through MCP — search and retrieve tools, handles instead of sessions, access control from the caller’s identity, and wiring to pgvector and to a Spring AI VectorStore.

  • MCP Security — confused deputy, token passthrough, SSRF, state handle hijacking, local server compromise, tool poisoning and prompt injection, least privilege and human confirmation.

Cheat sheet

  • Cheat Sheet (PDF) — a single-page, printable summary of every concept in this sub-section.

Related material elsewhere on this site is linked rather than repeated: the OAuth fundamentals in the OAuth Reference, REST APIs in Spring Boot REST APIs, containers in the Docker Reference, the retrieval side of RAG in Agentic RAG, and how coding tools use MCP servers (rather than build them) in MCP Configuration. The CLI alternative to an MCP server, and how to wrap a CLI as one, is covered in Building CLIs for AI Agents (see CLI vs. MCP). Chat-channel hosts are covered in Conversational Channels. LangChain, Spring AI, Hugging Face, Voice Agents, LLMOps & Evaluation and AI Security & Responsible AI are separate sub-sections of this AI section; the production RAG service behind the RAG server of these pages is covered in RAG Systems in Production, in particular RAG Behind MCP.

Other SDK languages

This sub-section builds servers in Python, Java and TypeScript. The other official SDKs follow the same protocol; the table lists them with the tier the official SDK list gave them on 2026-09-29. Their documentation is the place to look; this sub-section does not cover them.

Language Tier Documentation and repository

C#

Tier 1

C# SDK documentation and csharp-sdk repository

Go

Tier 1

Go SDK documentation and go-sdk repository

Rust

Tier 1

Rust SDK documentation and rust-sdk repository; the language in the Rust Reference

Kotlin

Tier 3

Kotlin SDK documentation and kotlin-sdk repository

Swift

Tier 3

swift-sdk repository

(TypeScript and Python are Tier 1 and Java is Tier 2; those three are the subject of this sub-section. Ruby is Tier 1 and PHP Tier 3 on the same list.)

MCP Apps

MCP servers can also return interactive user interfaces to hosts through the MCP Apps extension. Building those UIs is out of scope here; the extensions framework that carries them is introduced on MCP Architecture, and the MCP Apps overview is the starting point.

Bibliography

The following sources were consulted while preparing this sub-section’s pages. Every class, decorator, method, field, header, flag and protocol name was checked against the installed packages, the official source repositories or the specification pages listed here on 2026-09-29 — never copied from a book. Every URL cited on any page of this sub-section is listed here, once.

Requester-provided books, consulted for concepts only and never the source of an example. All five predate the 2026-07-28 revision (they describe the initialize handshake, sessions and the v1 SDKs), so where they differ from the specification or an SDK’s own documentation, those are authoritative:

oreilly.com answers automated fetches with an HTTP 403 response, but every publisher page above is a live, reachable page when opened in a browser.

The specification, revision 2026-07-28:

Earlier revisions, for the revision timeline:

Other protocol pages:

Python:

Java:

TypeScript and Node.js:

Other SDKs:

Hosts and clients:

LangChain and MCP:

Identity providers:

RFCs, standards and drafts:

Reference servers and other MCP servers:

Security references:

Governance:

Papers and engineering articles:

These books are consulted references, not the primary source of any example on this sub-section’s pages. On any discrepancy between a book and an SDK’s or framework’s own official documentation or a protocol’s specification, that documentation is authoritative.