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

MCP engineering · from a local function to an enterprise capability platform

A protocol standardizes the call. It does not grant the permission.

The Model Context Protocol lets many agent applications discover and call one shared capability. This site starts from one plain function that reads a roof assessment and climbs, one honest step at a time, to a remote MCP server used by four teams. At every step it asks two questions: what does this step add, and who is allowed to do what?

For engineers who build agents, backend engineers who will host their capabilities, and architects who must decide between a function, an API and MCP. One running example, and code that runs without a model, an external network or an API key.

You will understand
What MCP is, in one sentence, and what it does not do for you.
You will be able to decide
When a function, an HTTP API or an MCP server is the simplest right answer.
You will know
The insurance example, its four consuming teams, and where this site sits in its series.

An insurer's underwriting team built an agent last spring. It reads a broker's quote request, gathers evidence, applies the insurer's rules and leaves a recommendation for a human underwriter. One piece of evidence matters more than most: the age of the roof. The agent gets it from a function, get_roof_assessment, that lives in the same Python process as the agent and reads one row from the team's database.

The function works. Then three other teams ask for it. The claims team wants the roof age when a storm claim arrives. The support desk wants to tell a broker whether an assessment exists yet. The analytics team wants counts per region. Each team runs its own agent application, on its own release schedule, some in Python and one in Java. In the planning meeting somebody says what many people say in 2026: "Let's put it behind an MCP server, then every agent can use it."

That sentence may be right. It may also add a network hop, a new server to operate, a token to validate and a catalog to govern, to solve a problem that an ordinary function or an existing HTTP API already solves. And it hides the harder question: once four teams and their agents can call the capability, who decides which of them may read which submission, and who may write anything at all?

This site is about that decision and everything that follows from it.

One capability, five ways to offer it#

A capability is something useful a system can do for a caller, independent of how it is exposed. Here it is: given a submission id such as SUB-1004, return the assessed roof of the property. The result is a small typed record, a data transfer object (a DTO: a plain structure that carries data between layers and has no behavior). This site calls it PropertyAssessment:

{"submission_id": "SUB-1004", "property_id": "PROP-2207", "roof_age_years": 22, "roof_material": "modified bitumen", "evidence_source": "roof-data provider (stand-in)", "evidence_id": "EV-ROOF-0412", "assessed_at": "2026-08-03T14:20:00Z", "policy_version": "2026.2", "assessment_status": "complete"}

The code that owns this record and the rules around it is the assessment service: a domain service, meaning the code that owns the business rules and the data of one domain. Every version below calls the same service. What changes is how a caller reaches it.

1. A function in the agent's process. The agent's own code imports the service and calls get_roof_assessment("SUB-1004"). One process, no network, no serialization. The application's existing database account and transaction handling apply. Nothing new to deploy.

2. A tool the model may request. The application describes the function to the model with a name, a description and a JSON Schema for its arguments. The model writes a request; the application validates it, checks the caller may use it, runs the function and returns the result. Still one process. New: a contract the model reads, and validation of arguments the model wrote. Function calling is the page.

3. A private HTTP API. The service team runs the function behind GET /v2/submissions/SUB-1004/roof-assessment with authentication. Now there is a network hop, a second process, serialization, a credential, and a team that operates the endpoint. Any program in any language can call it, agent or not. Most companies already know how to run this.

4. A local MCP server. The function is wrapped in a small program that speaks the Model Context Protocol over standard input and output. The agent's host application starts it as a child process. Any MCP-capable host on that machine (a desktop assistant, a coding agent, the underwriting agent) can discover the tool by asking the server what it offers, without a line of integration code. There is a process boundary but no network.

5. A remote MCP server shared by teams. The same wrapper, deployed as a network service. Every request carries a token that says who is calling, for which resource, with which permissions. The server lists only the tools that caller may use, checks the permission again on every call, records an audit event, and calls the assessment service with its own credential. Four teams' agents use it. A platform team runs it; the assessment domain owns the data.

The lab below toggles between the five. Pick a version and see what it adds: components, process and network hops, trust boundaries, how identity is established, what can fail, and who deploys each part. The result row does not change, because the same service answers every time. That is this site's own case UW-M01.

VersionNew componentsTrust boundary crossedHow the caller is identifiedWho deploys it
1. Functionnonenonethe application's own sessionthe agent's team
2. Model tooltool definition, validator, adaptermodel output to application codethe application's session; the model is not a principalthe agent's team
3. HTTP APIserver process, endpoint, client, credentialnetwork, processa bearer credential per calling servicethe service team
4. Local MCPMCP server process, MCP client in the hostprocess (same machine, same user)the operating-system user who started itwhoever installs it on that machine
5. Remote MCPMCP server service, token validation, catalog, audit, token exchangenetwork, process, organizationa token with audience, scopes and principal type, checked per requestplatform team (server), assessment domain (service), identity team (tokens)

The table is qualitative on purpose. This site shows no timing figures: latency depends on networks and deployments this example does not have, and an invented number would teach the wrong thing. What does not depend on deployment is the count of boundaries a request crosses and the number of parties who must agree before it succeeds.

Diagram: One capability, five ways to offer it · each rung adds reach and adds parties

Read left to right. The same assessment service answers in every column and returns the same PropertyAssessment for SUB-1004 (case UW-M01). What grows is the number of boundaries a request crosses and the number of teams that must agree before it succeeds. Climb a rung only when the one below stops working. Click a box for what it adds.

  1. 1 · Function
    1. Function call: The agent's code imports the assessment service and calls it. No network, no serialization, the application's own database account and transaction.
  2. 2 · Model tool
    1. Tool definition + adapter: The model sees a name, a description and a JSON Schema; it writes a request; application code validates, authorizes, executes and returns.
  3. 3 · HTTP API
    1. Private endpoint: The service team runs the function behind an authenticated endpoint. Any program in any language can call it, agent or not.
  4. 4 · Local MCP
    1. Local MCP server: A small program speaks MCP over standard input and output. Any MCP host on this machine can discover the tool without integration code. It runs with the rights of the user who started it.
  5. 5 · Remote MCP
    1. Remote MCP server: The same wrapper as a network service. Each request carries a token; the server filters the list, checks permission on every call, writes an audit event and calls the service with its own credential.

The honest decision table#

Read the five versions as a ladder you climb only when the step below stops working. Each step solves a real problem and adds real cost.

SituationUsually simplest starting pointWhy
The same application owns the database credentials and the agent runtimeA direct typed function in Python or JavaFewer moving parts; the application's existing authorization and transactions apply
Many non-agent services need a shared contractA conventional HTTP API or serviceA mature interface with established governance and operations
Different MCP-capable agent hosts must discover and use shared capabilitiesAn MCP server, often wrapping the same underlying serviceStandard discovery and invocation, and an agent-facing interface of tools, resources and prompts
Sensitive shared enterprise dataA protected API and/or MCP with central identity, scoped authorization and auditThe protocol is not an authorization policy; permission checks remain essential

For the insurer the honest answer is mixed. The underwriting agent keeps calling the function in its own process: it owns the data and the transaction, and an extra hop would buy nothing. The support desk's ticketing system, which is not an agent, calls the existing HTTP API. The claims, support and analytics agents, which run in three different hosts, reach the capability through one remote MCP server that wraps the same service. Playbooks turns this into a checklist.

Common confusion. "We need MCP to let the agent read the database." No. MCP is not required for database access. It does not replace data-layer authorization, an API gateway, a transactional service or service ownership. The same domain service can have a direct, a REST and an MCP adapter at the same time. The database decision works through the choice.

A protocol standardizes the call. It does not grant the permission#

MCP is a standard for how an AI application discovers and uses capabilities that other programs offer. It fixes the shape of the conversation: how a client asks a server what it offers, how it asks for a tool to run, how errors come back. That standardization is valuable. It is also easy to mistake for something it is not.

Here is the moment it bites, in this site's own case UW-M03. The intake agent holds one permission, to read assessments. When it asks the remote server for its list of tools, the server shows it the read tools and hides record_recommendation, the write. A careless design stops there: the tool is hidden, so it is safe. Then the intake agent's model, nudged by text in a broker's email, writes a request for record_recommendation by name anyway. The name is public; a client can send any name it likes. If the server only filtered the list, the write runs.

In the example it does not run. The server checks the caller's permission again when the call arrives, refuses it (HTTP 403 with an insufficient-scope challenge; reason not_authorized), and writes an audit event that a person can read later. Hiding a tool is a convenience for the model. Refusing a call is the security control.

The first primitive. A protocol standardizes the call. It does not grant the permission. Every page of this site keeps that sentence true. MCP decides how a request travels; identity, authorization and ownership, which you build around it, decide whether the request may succeed.

Diagram: Who acts in one remote call · hiding a tool is not refusing it

Time runs down the page, for this site's own case UW-M03 against the remote server. The list the intake agent sees has no write tool, yet its model still writes a request for one by name. The server refuses the call because it checks the token's permission again when the call arrives, and it records why. The model only ever writes text.

  1. Host + MCP client to MCP server: tools/list + token. The token says who is calling, for which server, with which scopes.
  2. MCP server to Host + MCP client: read tools only. Discovery is filtered by scope: record_recommendation is not listed.
  3. Model to Host + MCP client: request: record_recommendation. Text in the broker's email nudged the model; the name is known anyway.
  4. Host + MCP client to MCP server: tools/call record_recommendation. Any client can send any tool name. The list was a convenience, not a lock.
  5. MCP server: authorize: scope uw.recommend missing. The permission is checked again at execution, against the token.
  6. MCP server to Host + MCP client: not_authorized + audit event. Nothing reaches the assessment service; a person can read why later.
Before AI. A backend engineer has seen this pattern with every shared interface. Publishing an OpenAPI document did not authorize anyone; a gateway, a token and a check in the service did. A Kafka topic anyone can name is still protected by access control lists on the broker. MCP is one more standard interface, and it inherits the same rule: the contract says how to ask, never who may.

The example in one minute#

An email arrives at the insurer from a broker asking for a quote on an office building. An intake step reads it once and writes the facts down as one structured record, a submission: a JSON record of one quote request that every later step reads instead of the email. Submission SUB-1004 says the roof was replaced 9 years ago.

The underwriting agent (a program that calls a language model in a loop and runs the capabilities the model asks for in between) gathers evidence. The assessment service says the roof is 22 years old, evidence EV-ROOF-0412. The insurer's written guidance, the policy fixture UW-GUIDE version 2026.2, has a rule for that: R-ROOF-03, when the two ages differ by more than 5 years, escalate to a senior underwriter. The agent writes a recommendation, one of approve, decline, request_info or escalate, with reasons and rule ids. Here it is escalate. This is series case UW-004, the default case on most pages.

The model recommends; a person decides. An underwriter, the employee who decides whether the insurer accepts a risk, reads the recommendation in the underwriter cockpit and decides. On this site the decision is written by a tool, record_underwriter_decision, that only a person acting through the cockpit can use, with their own credential. No agent can call it, even if someone gives the agent the permission by mistake.

The MCP server uw-assessment offers this catalog. It is the same catalog on every page:

Offered asNameReads or writesWho may use it
toolget_roof_assessment(submission_id)readsscope uw.read
toolsearch_guidance(query)readsscope uw.read
toolcheck_eligibility(submission_id)readsscope uw.read
toolget_assessment_status(submission_id)reads a summaryscope support.read
toolget_assessment_stats(business_unit)reads aggregatesscope analytics.read
toolrecord_recommendation(submission_id, recommendation, idempotency_key)writesscope uw.recommend, an agent
toolrecord_underwriter_decision(submission_id, decision, reason, override)writesscope uw.decide and a person with the underwriter role
resourceuw://policy/UW-GUIDE/2026.2the policy fixture as datascope uw.read
promptunderwriting-reviewa review template a person picksscope uw.read

A scope is a named permission carried in a token, such as uw.read. The owner's original specification for this site used the names get_property_assessment, search_policy and record_underwriter_decision; this site keeps the series names get_roof_assessment and search_guidance, which the sister sites share, and uses record_underwriter_decision for the person's decision only.

Five principals call the server: the underwriter (a person), the underwriting agent, the intake agent, the audit agent, and an unknown agent with no valid token. Four teams consume it: claims, underwriting, support and analytics. Each later page uses the same names, the same permissions and the same cases.

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. No model is called anywhere in the example. The servers listen only on the machine's own loopback address for the length of one run. The tokens are toy tokens signed with Python's standard library.

Honest boundary. This 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.
In a coding agent. The same ladder appears on a developer's laptop. A coding agent reads files through a function inside its own process. It reaches the company's issue tracker through a local MCP server it started, which runs with the developer's own operating-system rights. It reaches the code review system through a remote MCP server shared by every team, where a token says which repositories this developer may open a pull request in. Harness Engineering shows where MCP sits inside the agent's runtime.
What this is not. This site does not teach tool schemas, result envelopes or the tool-calling loop in depth; Tools Engineering does, and has its own short introduction to MCP. Messages between agents, and the A2A protocol itself, belong to https://a2a.sammuthu.com. Defending a model against injected text in depth belongs to https://guardrails.sammuthu.com.
Which MCP is this? The revision mattersThe specification changed shape in 2026; tutorials written before it describe a handshake that no longer exists

MCP is versioned by date. The specification read for this site on 2026-11-18 is revision 2026-07-28. Its changelog removed the initialize handshake and the protocol sessions of the earlier revision 2025-11-25. In the current revision every request carries its protocol version and the client's capabilities in a _meta field, and a server must answer a server/discover request that tells a client what it supports.

Normative (MCP specification 2026-07-28): the request and result shapes, the methods, the transports and the authorization rules quoted on this site come from that revision, with links in each page's fact log. Ecosystem pattern: SDKs, registries and gateways move at their own pace; an SDK may implement both revisions, and a product may still document the old one. This site's recommendation: pin the protocol revision of every server you publish in your catalog entry, and test each consuming host against it (Testing).

The example's server and client are a teaching subset of revision 2026-07-28, written from the specification. They are not the official SDK and are not conformance tested. A page that shows the example's JSON says so.

What each rung really costs a platformOperations, identity and governance grow faster than the code does

The code of the remote MCP server in the example is short. The cost of running it is not in the code. Compare what has to exist before step 5 can serve its first request in a real organization: a deployed service with an owner and an on-call rotation; an identity provider that issues tokens with the server's audience; scopes someone defined and someone approves; a catalog entry that says who owns the tool, what data it touches and what risk tier it is in; an audit trail that someone reads; a version policy so that four teams do not break when one field changes.

None of that is MCP-specific, and none of it is optional once data is shared across teams. That is the honest reason step 5 should be a decision rather than a default. If only one application uses a capability, steps 1 or 2 carry none of these costs. If many non-agent services use it, step 3 already has them, and an MCP server becomes a thin second adapter on a service that is already governed.

This site's recommendation: count owners, not lines of code. If moving a capability up one rung adds a team that must be paged when it fails, write down why that team is worth it.

How to read the labels on this siteNormative, ecosystem pattern, recommendation: three kinds of statement kept apart

Writing about MCP mixes three kinds of statement, and confusing them causes real mistakes. Some things the specification requires: a server that uses HTTP authorization must validate that a token was issued for it, and must not pass the token it received on to another service. Some things are common practice in SDKs, gateways and registries, and are optional. And some things are design advice from the author of this site.

Each page labels them when the difference matters. Normative (MCP specification 2026-07-28) marks a requirement of the specification, with a link. Ecosystem pattern marks what tools and vendors commonly do. This site's recommendation marks advice. A recommendation is never called "the standard", and a requirement is never softened to "best practice".

Where this fits#

MCP is one of fifteen subjects in a series of guides by the same author. Each site owns one question about agentic software and links to the others where the subjects meet, instead of repeating them. This one is marked below.

Three neighbors matter most here. Tools Engineering teaches a single tool from the inside: its schema, its result and its execution. This site starts where one tool becomes a shared capability that many teams depend on. Agent Communication covers agents that delegate work to other agents, which MCP does not standardize. Guardrails covers the checks around the model that this site's threat model relies on.

How to read this site#

The pages follow the order in which questions come up when one team's function becomes everybody's capability. The foundations rebuild the stack from a function to the protocol. The protocol part builds a server and moves it from a laptop to the network. The platform part covers what makes sharing safe: data access, ownership, identity, authorization, threats and governance. Operations and reference close the site.

Foundations. From a function to the idea of a protocol.

Protocol. Building a server and taking it from a laptop to the network.

Platform. Sharing a capability safely across teams.

Operations and reference. Running it, testing it, and the whole design.

If you are new to agents, read in order; every page assumes only the pages before it. If you already run MCP servers, start at the question of the day. Each page folds its harder material (failure cases, competing designs, security and operations) into blocks like the three above, so the first reading stays short.

If your question isStart at
Do we need MCP at all for this?Playbooks, then The database decision
What exactly travels between a host and a server?First server
How does a remote server know who is calling?Enterprise authorization
Can an agent act with a person's permissions?Who gets access
Who approves a new tool before other teams can see it?Governance
How do four teams share one capability without sharing database credentials?Reference architecture

In one breath#

A capability can be offered as a function, as a tool the model may request, as an HTTP API, as a local MCP server or as a remote MCP server; each step adds reach and adds parties who must agree. MCP standardizes how agent applications discover and call capabilities they do not own, which pays off when several different hosts need the same capability. It does not decide who may call what: identity, authorization checked on every call, ownership and audit do that, and you build them. A protocol standardizes the call; it does not grant the permission.

Every rung of that ladder rests on the bottom one, a function with arguments, a result and maybe a side effect. Before any model or protocol is involved, the next page looks at the roof lookup and the recommendation write as plain Python and Java, and at why the difference between reading and writing decides almost everything later. That is The primitive.