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
Reference · 21

Decision playbooks: function, API or MCP, and the records that explain why

Checklists and architecture decision records for the choices this site teaches: local function, HTTP API or MCP; direct SQL or a service; publishing, authorization and retirement.

You will have
A checklist that decides between a function, an HTTP API and MCP in ten minutes.
You will be able to write
An architecture decision record that a reviewer can check a year later.
You will know
Which page of this site to reopen for each question the checklist raises.

Eight months after the insurer's assessment platform went live, a new architect joins the platform team. Her first ticket says: "Marketing wants their campaign agent to read roof ages. Add them to the MCP server." She opens the server's repository and finds the code. She opens the catalog and finds the tool entries. What she cannot find is why. Why does the underwriting agent call the assessment service directly while the claims agent goes through MCP? Why does the support desk get a summary tool instead of the full assessment? Why can no agent hold uw.decide? Every one of those choices was argued in a meeting. None of the arguments was written down.

So she does what most people do. She copies the claims team's setup for marketing, grants uw.read, and ships. Marketing's agent can now read every assessment in its business unit, including evidence ids that the analytics team was deliberately denied. Nothing in the code is wrong. The reasoning that protected the data was never in the code.

This page is the part of the design that is not code: the checklists that make a decision quickly, and the records that keep its reasons.

Why decisions need a record#

A decision playbook is a short, ordered list of questions that leads a team to a choice and tells it what to check before acting on it. An example: "Does more than one host application need this capability? If no, stop: use a function." A playbook is for the moment of deciding.

An architecture decision record (an ADR) is a short document that states one decision, its context, the options considered and the consequences, written when the decision is made and kept with the code. An example: "ADR-007: Analytics reads aggregates only. Context: per-submission data includes evidence ids. Decision: a separate stats tool. Consequence: analytics cannot debug one submission." An ADR is for the moment someone asks why.

Before AI. Backend teams have used both for years. A runbook is a playbook for an incident. An ADR in a docs/adr/ folder, numbered and never edited after acceptance (only superseded), is a common practice from service-oriented architecture. Nothing about agents changes the format. What changes is the number of decisions that look like plumbing ("add a tool") but are really access decisions.

The rest of this page gives the playbooks in the order the site taught the questions, then five ADRs for the insurance platform, written the way a team would write them.

Diagram: Playbook 1 as a path · stop at the first rung that works

Read left to right and stop at the first box whose question you answer yes. Each later box adds a party who must operate or approve something. Sensitive data adds identity and audit whichever interface you choose. Click a box for the question behind it.

  1. 1 · Same application?
    1. Direct function: If the code that needs the capability runs in the application that owns the data and its credentials, call the domain service directly.
  2. 2 · Non-agent callers?
    1. HTTP API: If batch jobs, web apps or other services need it, an HTTP API is the shared contract; agents may also call it as a tool.
  3. 3 · Several agent hosts?
    1. MCP adapter: If two or more different agent hosts must discover and call it without integration code each, an MCP server is justified, as an adapter.
  4. 4 · Sensitive data?
    1. Identity + audit: Whatever the interface, shared sensitive data needs central identity, scoped authorization at execution and audit events.

Playbook 1: function, HTTP API or MCP?#

Answer the questions in order. Stop at the first answer that settles it.

#QuestionIf yesIf no
1Does the code that needs the capability run in the same application that owns the data and its credentials?Use a direct typed function. Keep the application's transactions and authorization. Go to question 5 only if a model will request itGo on
2Do programs that are not agents need it too (batch jobs, web apps, other services)?Offer or reuse an HTTP API. It is the shared contract. Go on to see whether agents also need MCPGo on
3Do two or more different agent hosts need to discover and call it, without integration code per host?An MCP server is justified. Make it an adapter over the same domain service, never a copy of its rulesStay with a function or the API; an agent can call an HTTP API as a tool
4Does the capability touch sensitive or shared data?Remote server with central identity, per-call authorization and audit. Read Enterprise authorization before buildingA local server may be enough for one machine and one user
5Will a model request it?Treat every request as untrusted input: validate, authorize, execute in code. Function callingIt is ordinary code; no tool definition needed

The table encodes the honest decision table from Start. Three things it deliberately does not ask. It does not ask whether MCP is modern; that is not a reason. It does not ask whether the capability touches a database; The database decision shows that MCP is never required for that. And it does not ask whether an SDK makes the server easy to write; writing the server is the cheap part.

Common confusion. "MCP or API" is often a false choice. In the example the assessment service has a direct caller (the underwriting agent's application), a REST endpoint (the support desk's ticketing system) and an MCP server (the other agents). Three adapters, one service, one set of rules. The question is which adapter each caller should use.

Playbook 2: the database decision#

When a capability reads or writes a database, decide where the database account lives before you decide anything else.

CheckWhat to write downWhere it is taught
Who holds the database credentials?One owning service. Never every consuming agentThe database decision
What is the database account allowed to do?A grant per table and per operation; reads and writes in separate accountsThe database decision
Who owns the transaction?The domain service. Not the MCP server, not the modelThe database decision
Who owns the schema, and who must release when it changes?The domain team; consumers depend on the contract, not on tablesSharing across teams
Is a write idempotent?The key, who chooses it, and how a retry finds the stored resultResilience

This site's recommendation: if the answer to the first row is "every agent that uses it", stop. That design gives the database's authorization model to whoever controls an agent's prompt.

Playbook 3: publishing a tool to other teams#

A tool another team can discover is a product with users. Before a tool reaches the state "discoverable" in the catalog, check:

CheckOwner who signs it
Name, description and version follow the catalog's naming rules; no two tools mean the same thingServer maintainer, platform team
Input and output schemas are versioned; the change policy is statedServer maintainer
Scopes are defined and approved; write tools need a stronger scope than read toolsIdentity and security governance
Risk tier is assigned (what data, read or write, reversible or not)Domain data owner, security
Owner and on-call are named; an incident route existsDomain data owner, platform team
Audit events are written for every allowed and refused callServer maintainer, audit and compliance
Deprecation path for the previous version is publishedServer maintainer, consumer application owners informed

Governance has the lifecycle and the full RACI matrix behind this list.

Playbook 4: authorizing a new consumer#

The marketing request at the top of this page is this playbook. Answer before granting anything:

  1. Which principal will call: a person through an application, or an agent with its own workload identity?
  2. Which tools does it need, and which data inside them? If the answer is "the same as team X", ask why team X has what it has: read that team's ADR.
  3. What is the narrowest scope that works? Is there a summary or aggregate tool that would do?
  4. Which business units may it see? Is the tenant check enforced at execution, not only in the list?
  5. Who approves the scope, and who reviews it in six months?
  6. What audit query would show misuse, and who reads it?

This site's recommendation: a new consumer gets a new client id and its own rate limit and metrics, even if it shares scopes with another team. Shared identities make an incident impossible to scope.

Playbook 5: retiring a tool#

StepDone when
Mark the version deprecated in the catalog with a dateDiscovery results carry the deprecation notice
Find every consumerAudit events by client_id over the last 90 days (illustrative window) list them
Tell each consumer application ownerEach has a migration ticket
Watch calls to the old version fallThe per-version call count is zero for the agreed period
RetireThe tool is no longer offered; a call by name returns an error that names the replacement
Write the ADR that supersedes the old oneThe reason survives the code

This site's own case UW-M07 is what happens when step 3 is skipped: a client built against version 1 of get_roof_assessment still sends property_id, and the server answers with an invalid-arguments error.

Five decision records for the insurance platform#

The records below are written for the synthetic insurer. They are short on purpose: an ADR that takes an hour to read will not be read. Each one names the page that holds the reasoning in full.

Diagram: Where a decision lives · record, catalog, test

A decision becomes durable in three places. The record keeps the reasons, the catalog entry links the record to every tool it governs, and a fitness check in CI fails when someone changes the code against the decision. Click a box for an example from the insurance platform.

  1. 1 · Decide
    1. Decision review: Domain data owner, server maintainer, identity and security governance, and each consuming team agree on interface and access.
  2. 2 · Record
    1. ADR: Context, options, decision and consequences in a short numbered document kept with the code.
  3. 3 · Link
    1. Catalog entry: Each tool's entry names the records that govern it, so a reviewer finds the why from the what.
  4. 4 · Enforce
    1. Fitness check: A test that verifies the decision still holds after every change.

ADR-001: the underwriting agent calls the assessment service directly#

FieldContent
StatusAccepted
ContextThe underwriting agent and the assessment service are owned by the same team, deployed together, and share a database account with write grants on recommendations only
OptionsDirect function call; the internal HTTP API; the remote MCP server
DecisionDirect function call through the service's typed interface
ConsequencesNo extra hop, the application's transactions apply. The agent does not appear in the MCP server's metrics; its audit events come from the service instead. If the agent moves to another team, revisit
ReasoningThe database decision, playbook 1 question 1

ADR-002: claims, support and analytics agents use the remote MCP server#

FieldContent
ContextThree teams, three agent hosts, one in Java; none owns the data
DecisionOne remote MCP server uw-assessment, run by the platform team, wrapping the assessment service
ConsequencesOne place for discovery filtering, per-call authorization, audit and per-team metrics. The platform team is on call for the server; the assessment domain stays on call for the service
ReasoningSharing across teams, Reference architecture

ADR-003: no agent may record an underwriting decision#

FieldContent
ContextThe specification for the platform asked for a decision write tool. Agents read text from brokers; injected text has asked agents to approve (series case UW-005)
Decisionrecord_underwriter_decision is offered only to a person with the underwriter role, acting through the cockpit with a delegated token. The check is on the principal type, not only the scope
ConsequencesA mistaken grant of uw.decide to an agent does not let it decide. The model recommends; a person decides
ReasoningWho gets access, Threat model, case UW-M09

ADR-004: the server never forwards the caller's token#

FieldContent
ContextThe MCP server must call the assessment service on behalf of callers
DecisionThe server validates the caller's token for its own audience, then obtains a separate downstream token for the service's audience. It never passes the received token on
ConsequencesThe service can tell the server's calls apart; a token stolen from one hop cannot be replayed at another. Requires a token exchange or a service credential
ReasoningEnterprise authorization, case UW-M04. Normative (MCP specification 2026-07-28): the specification forbids token passthrough

ADR-005: analytics reads aggregates only#

FieldContent
ContextAnalytics asked for per-submission assessments to compute regional statistics
DecisionA separate tool get_assessment_stats returns counts per business unit; get_roof_assessment is refused for analytics-jobs
ConsequencesAnalytics cannot inspect one submission. A request for that goes through the domain owner. Case UW-M12 tests it
ReasoningWho gets access, Sharing across teams

With these five records the new architect's ticket answers itself. Marketing is a new consumer (playbook 4). ADR-005 shows that per-submission access was refused to a team with a weaker need than underwriting. The right first offer is the aggregate tool, a new client id, and a scope review with the domain owner.

In a coding agent. The same records help a team that gives coding agents MCP servers. "ADR: coding agents may open pull requests but never merge" is the coding equivalent of ADR-003. "ADR: the repository server runs locally with the developer's rights; the deployment server is remote and needs a token with the environment as audience" is ADR-002 and ADR-004 together. Diff to Deploy follows those permissions through a real change.
What this is not. These playbooks decide interfaces and permissions for capabilities. How to judge whether an agent's answers are good enough to ship belongs to eval.sammuthu.com; how to recover a whole workflow after a failure belongs to https://reliable.sammuthu.com.

A fitness check you can automate#

A fitness check is a test that verifies an architecture decision still holds, run in continuous integration like any other test. An example: "No agent token in the test fixtures can call record_underwriter_decision." When someone changes the policy, the check fails before the change ships. Several ADRs above become fitness checks directly:

ADRFitness check
ADR-003For every agent principal, record_underwriter_decision is refused even with uw.decide granted
ADR-004The server's outgoing request to the service never carries a token whose audience is the server
ADR-005analytics-jobs is refused get_roof_assessment for every submission in the fixtures
Playbook 3Every catalog entry in state "discoverable" has an owner, an on-call, a risk tier and an approved scope

Testing shows the authorization matrix that turns rows like these into one test per cell.

Keeping ADRs aliveSupersede, never edit; link from the catalog; review on a schedule

An ADR that is edited after acceptance stops being evidence: nobody can tell what was decided when. The common practice is to write a new ADR that supersedes the old one and to mark the old one "superseded by ADR-012". The record of change is then the list of ADRs itself.

For a shared capability, store the ADR id in the catalog entry of each tool it governs. A reviewer who opens get_assessment_stats in the catalog sees ADR-005 one click away, and the platform team can find every tool affected when ADR-005 is superseded.

Review on a schedule, not only on change. This site's recommendation: every six months (illustrative), the domain data owner reviews the ADRs that grant access to their data and either reaffirms or supersedes them. Access decisions decay quietly: teams change purpose, agents gain tools, and nobody notices until an audit asks.

Signals that MCP was the wrong rungSymptoms that a team climbed too high, and how to step down

Some symptoms show that an MCP server was added where a lower rung would have done. Only one host ever connects to it. Its tools are called only by code that knows exactly which tool it needs, never chosen by a model. It holds business rules that also exist in the domain service. Its on-call rotation is the same people as the service's, and every incident touches both. Its catalog entry has no consumers outside its own team.

Stepping down is cheap if the server was a thin adapter: the host calls the service directly, the server is deprecated with playbook 5, and nothing about the domain changes. Stepping down is expensive if the server grew rules of its own. That asymmetry is the practical argument for keeping every MCP server an adapter.

The opposite symptom also exists: a team that refused MCP and now maintains five slightly different integrations of the same capability in five agent hosts, each with its own authorization code. That team climbed too slowly.

Running a decision review in practiceWho is in the room, what they bring, and how long it takes

For a new shared capability the review that produces ADRs like the five above needs four roles and about an hour (illustrative). The domain data owner brings the data classification and says which fields are sensitive. The server maintainer brings the draft catalog entry and the schemas. Identity and security governance bring the scope model and say which principals may hold which scopes. A representative of each consuming team brings the use case in one sentence and the narrowest data that would serve it.

The output is the ADRs, the approved scopes and a catalog entry in state "approved". The output is not code. If a review ends with "we will figure out permissions later", the capability is not ready to be shared.

Exercises#

  1. A finance team's batch job (no agent) needs roof ages nightly. Which rung? Answer below.
  2. A single developer wants their desktop assistant to read their own local notes. Local or remote MCP, or neither?
  3. A vendor offers a hosted MCP server that reads your claims data. Which playbooks apply before anyone connects to it?
AnswersOne line each
  1. The existing HTTP API (playbook 1, question 2): it is not an agent and needs no discovery.
  2. A local MCP server, or a built-in function of the assistant; a remote server adds an operator and a token for one user's own data.
  3. Playbooks 3 and 4 from the consumer side, plus the Threat model: who operates the server, which audience its tokens have, and what egress it is allowed.

In one breath#

Decide the rung with an ordered checklist: same application, function; non-agent callers, an API; several agent hosts, an MCP adapter over the same service; sensitive data, central identity and per-call authorization. Write each access decision down as a short record with its context and consequences, link it from the catalog, and turn the important ones into fitness checks that fail in CI. The reasoning that protects shared data is rarely in the code, so it has to live somewhere a newcomer will find it.

This is the last chapter. The Glossary holds every term in one place, and About lists the sources, the sister sites and the label convention. If you started here, Start shows the five rungs this checklist chooses between.