All chapters
  1. Start hereA protocol standardizes the call. It does not grant the permission
  2. Foundations · 1The primitive: a function, its arguments, its result, its side effects
  3. Foundations · 2Function calling: the model asks, your application executes
  4. Foundations · 3Client and server: process boundaries, JSON-RPC, errors and trust
  5. Foundations · 4What MCP is: host, client, server and what the protocol promises
  6. Protocol · 5Three surfaces: tools act, resources inform, prompts guide
  7. Protocol · 6A first MCP server: typed input, deterministic data, the raw exchange
  8. Protocol · 7Java and the SDKs: typed DTOs, validation and interoperability
  9. Protocol · 8Local or remote: stdio, HTTP, stateless requests and availability
  10. Platform · 9The database decision: direct SQL, a service boundary or an MCP adapter
  11. Platform · 10Sharing across teams: ownership, catalogs, contracts and versions
  12. Platform · 11Who gets access: users, agents, delegation and least privilege
  13. Platform · 12Enterprise authorization: tokens, audiences, gateways and no passthrough
  14. Platform · 13The threat model: injection, poisoned tools, confused deputies and egress
  15. Platform · 14Governance: who may publish, who approves, who answers the page
  16. Operations · 15Observability and audit: what was called, by whom, and why it was allowed
  17. Operations · 16Resilience: timeouts, retries, idempotency and overload at a shared server
  18. Operations · 17Testing and evaluation: contracts, authorization matrices and injection
  19. Reference · 18Advanced MCP: long tasks, large catalogs, tenants and evolving versions
  20. Reference · 19The ecosystem: SDKs, registries, gateways, identity and telemetry
  21. Reference · 20Enterprise reference architecture: one assessment platform, four teams
  22. Reference · 21Decision playbooks: function, API or MCP, and the records that explain why
  23. ReferenceGlossary
  24. AboutAbout this site and its sources
About

About this site and its sources

What this site is, what it is not, the sources it was checked against, the sister sites, and which statements are protocol requirements, ecosystem patterns or this site's own recommendations.

This is a knowledge site about the Model Context Protocol as an engineering decision. It starts from one plain function that reads a roof assessment and climbs to a remote MCP server shared by four teams, asking at every step what the step adds and who is allowed to do what. It is written for engineers who build agents, backend engineers who will host capabilities for them, and architects and platform teams who must decide between a function, an HTTP API and MCP, and then govern what they chose.

One example runs through every page. An insurer receives a broker's request for a quote. An underwriting agent gathers evidence from an assessment service and recommends; a human underwriter decides. Claims, support and analytics teams reach the same assessment service through one MCP server. The model recommends; a person decides.

What it is and is not#

It isIt is not
A decision guide: when a function, an HTTP API or MCP is the simplest right answer, with the trade-offs statedAn argument that MCP is always better, or a setup tutorial for one product
One running example with the series cases (UW-004, UW-005, UW-006, UW-009) and this site's own cases UW-M01 to UW-M12A record of any real insurer. Cases, rules, teams, tokens and the provider are invented
A demonstration of mechanism: discovery, calls, token validation, per-call authorization, audit, lifecycle, written as small runnable codeA measurement of any model, server or product. No page reports latency, throughput or quality figures
Protocol and products described from their own documentation, read on 2026-11-18A ranking or a buying guide. No product is called best, and no price is quoted
Labelled statements: normative requirements, ecosystem patterns and this site's recommendations kept apartA substitute for the specification. Read it before you build

Three kinds of statement#

The owner's specification for this site asked that protocol requirements, optional ecosystem patterns and personal architectural advice never blur. Pages use three bold lead-ins when the difference matters:

LabelMeansExample
Normative (MCP specification 2026-07-28)A requirement of the specification (or an RFC it cites), linked in the page's fact logA server must not pass through the token it received to another service
Ecosystem patternWhat SDKs, gateways, registries, identity products or the community commonly do; optionalA gateway in front of several MCP servers that validates tokens centrally
This site's recommendationThe author's design advice; never called "the standard"Every new consumer gets its own client id, rate limit and metrics

What is original here and what is not#

PartStatus
Host, client, server, tools, resources, prompts, server/discover, transports, authorizationThe Model Context Protocol specification, revision 2026-07-28, described from the specification. Not copied
OAuth 2.1 (draft), protected resource metadata (RFC 9728), resource indicators (RFC 8707), token exchange (RFC 8693), authorization server metadata (RFC 8414)Published standards and drafts, described from their texts
Enterprise-managed authorizationAn official MCP extension, described from its blog post and specification
Security threats and mitigationsFrom the MCP security best practices and a government cybersecurity information sheet on MCP, used with attribution
The five-architecture ladder, the decision table's wording, the RACI matrix, the lifecycle states, the playbooks and ADRsWritten for this site, from common practice in service engineering and the owner's specification. Called designs and recommendations on the pages
The assessment service, the MCP server uw-assessment, the principals, teams, tokens and the twelve UW-M casesWritten for this site. All synthetic
The example code, its tests, the Java programWritten for this site
The interactive labs and the diagramsWritten for this site. The labs' logic is a second implementation of the Python code, and a parity test fails if the two differ

How the facts were checked#

Kind of claimHow it was checked
The protocol, a product or a standardRead in its own documentation on 2026-11-18 and logged with the address and date in the page's fact log (docs/facts/ in the repository). Where the documentation is silent, the page says so. Surprising items, such as a protocol change or a moved page, were fetched a second time before publication
The exampleRun. Every command shown from examples/uw-mcp/ was executed in a copy of the folder, and the output on the page is the output it printed
The Java programRun with JDK 23 as java AssessmentService.java. Spring, Bean Validation, Pydantic and the official MCP Java SDK are shown as documented shape; not run here
The labsThey read data generated from the example; a parity test checks that the JavaScript gives the same results as the Python
Links and structureA build step checks every internal link, diagram, glossary reference, JSON block and Python block before the site is published

One source needs a note. The NSA's cybersecurity information sheet on MCP returned HTTP 403 from its official address on the day of reading. It was read from an Internet Archive copy of that same address, saved on 2026-11-17, and the pages that cite it say so. Treat every statement about a product or protocol as true on the day it was read; in this field documentation changes monthly.

What the example does not show#

The insurance example is an illustrative reconstruction for teaching. It follows the shape of a real project by the author, but the cases, rules, fields, teams, tokens, provider and every number are invented. Nothing here reports the quality of a real system or model. Example roof thresholds are synthetic, not insurance practice.

The model here is a scripted stand-in, so these results show how the protocol and the controls work, not how good any model is.

In the exampleWhat it really is
The agents' modelsScripts that emit requests. No model is called. There is no external network and no key
The MCP server and clientA teaching subset of MCP revision 2026-07-28 over stdio and HTTP, written from the specification. Not the official SDK, not conformance tested
The HTTP stagesServers bound to the machine's loopback address for the length of one run
Tokens and the identity providerToy tokens signed with HMAC from Python's standard library, and a stand-in issuer and token exchange. Not a real OAuth server, not a JWT library, not secure for production
The databaseSQLite from Python's standard library, with an authorizer callback standing in for database grants
Times and countsA simulated clock and a scripted workload; every run prints the same values

The sister sites#

This site is one of a series on AI-native engineering. Each owns one subject and links the others at the seams.

SiteWhat it owns
prompt.sammuthu.comInstructions: how they are written, composed and defended
context.sammuthu.comWhat the model can see now: selection, retrieval, budget
rag.sammuthu.comRetrieval from SQL rows to production: embeddings, vector indexes, hybrid search, reranking, grounding
memory.sammuthu.comDurable information and saved execution state
tools.sammuthu.comCallable capabilities: schema, execution, MCP tools
mcp.sammuthu.comShared capabilities across teams: when MCP is justified, identity, authorization, governance (this site)
a2a.sammuthu.comMessages between agents; A2A versus MCP
observe.sammuthu.comLogs, metrics, traces, audit events, replay
guardrails.sammuthu.comEnforceable checks around a probabilistic agent
schema.sammuthu.comTyped contracts: shape, validation, repair, evolution
orchestrate.sammuthu.comThe control plane: what runs next
reliable.sammuthu.comAcceptable outcomes despite failures and load
harness.sammuthu.comThe runtime around a model call
eval.sammuthu.comMeasurement: graders, golden sets, release gates
diff-to-deploy.sammuthu.comShipping a change with coding agents

Sources and reading list#

Each link below was opened on 2026-11-17 or 2026-11-18. The fact logs in the repository list every claim with the exact page it came from.

The protocol#

SourceWhy read it
Model Context Protocol specification and the changelog of revision 2026-07-28Architecture, discovery, tools, resources, prompts, transports. Read the changelog first if you learned MCP before mid-2026
MCP authorizationProtected resource metadata, authorization server discovery, resource indicators, token validation, the passthrough prohibition
MCP security best practicesConfused deputy, token passthrough, SSRF, state handle hijacking, local server compromise, scope minimization
MCP extensions and enterprise-managed authorization, with its announcementHow extensions are staged; the enterprise identity provider as the authority for MCP access
MCP RegistryPublishing and discovering servers; namespaces

Standards the protocol builds on#

SourceWhy read it
JSON-RPC 2.0The message format under MCP
RFC 9728: OAuth 2.0 Protected Resource MetadataHow a server tells a client which authorization server protects it
RFC 8707: Resource Indicators for OAuth 2.0How a client asks for a token for one specific server
RFC 8693: OAuth 2.0 Token ExchangeHow a service obtains a new token for a downstream call instead of forwarding one
RFC 8414: OAuth 2.0 Authorization Server MetadataHow a client discovers an authorization server's endpoints
OpenTelemetry semantic conventions for generative AISpan names and attributes for MCP calls; status development

Security guidance and products#

SourceWhy read it
NSA cybersecurity information sheet on MCP security (archived copy read 2026-11-18)Government design considerations for MCP deployments
Secure an MCP server with Microsoft Entra IDOne identity product's documented setup for an MCP server; vendor documentation
A2A protocol specification and A2A and MCPWhat agent-to-agent delegation standardizes, for the comparison on Advanced

SDKs#

SourceWhy read it
MCP SDKs and SDK tiersThe official implementations and how they are maintained
MCP Python SDK, TypeScript SDK, Java SDKCheck which protocol revision each implements before you depend on it

Who wrote it#

Written by Sam Muthu, an engineer who builds agentic systems. The example follows the shape of a real project by the author; everything in it is synthetic. Corrections are welcome.