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 · 20

Enterprise reference architecture: one assessment platform, four teams

The whole design in one place: the domain service, the MCP adapter, the gateway, identity, the catalog, audit and the human decision path, consumed by claims, underwriting, support and analytics.

You will see
The whole assessment platform on one page: every component, its owner, and the one job it does.
You will be able to trace
One request for SUB-1004 through every hop, and say which component could have refused it.
You will know
What each of the four consuming teams may see, what it owns, and what it must never get.

Three weeks after the platform went live, a reviewer from audit and compliance opens a ticket about submission SUB-1004. The broker's application said the roof was 9 years old. The claims assistant showed an adjuster 22 years. The underwriting agent recommended escalate. An underwriter then approved the submission with an override. The reviewer asks one question: "Show me every component this submission passed through, who owns each one, and which of them could have let an agent make that decision."

Each team can answer for its own part: the claims assistant, the gateway, the MCP server, the service, the scopes. Nobody has the one picture that connects them, so the answer takes four meetings, and the reviewer still cannot tell whether the protection against an agent deciding lives in one place or five.

This page is that picture: the earlier pages as one design, with an owner on every box. A reference architecture is a documented design for a class of systems that names its components, their responsibilities, the flows between them and the decisions behind it, so that a team can build or review a concrete system against it. A tiny example: "every consuming team gets its own client id, token and rate limit" is one decision of this reference architecture; the claims team's client claims-assistant is one concrete application of it.

The platform in plain words#

Start with what the platform protects. The roof assessment lives in one domain service, the assessment service, owned by the assessment domain (the property-risk data team). Only that service holds database credentials, one purpose per account: uw_reader reads, uw_rec_writer inserts recommendations, uw_decision_writer inserts decisions. Every other component exists to let more callers reach that service without weakening those facts.

Around the service sit three adapters, and each serves a different kind of caller. The underwriting workbench calls the service directly, in its own process, because the same team owns and deploys both (Playbooks, ADR-001). Programs that are not agents, such as the support desk's ticketing system or a nightly batch job, call a REST adapter: GET /v2/submissions/SUB-1004/roof-assessment with a token issued for the assessment service. And agent hosts that belong to other teams call the remote MCP server uw-assessment, a thin adapter that translates MCP requests into service calls and owns no business rule.

Before AI. A backend engineer has built this shape many times. A Spring service owns the rules and the JDBC connection pool. A REST controller and a Kafka consumer are two adapters over it. An API gateway in front of the controller rejects bad credentials and counts calls per client key. Service accounts, not end users, hold the database grants. The MCP server is one more adapter in that picture, for a new kind of consumer.

The remote path is where most new components appear. The claims assistant gets a token from the insurer's identity provider (the system that signs people and workloads in and issues their tokens), naming the caller, client id, scopes, business unit and audience, the MCP server https://mcp.uw.insurer.example. The platform team's gateway checks what any server would check. The MCP server validates the token again, decides whether this caller may make this call on this submission, exchanges the token for one with the assessment service as audience, calls the service, writes an audit event and replies.

Three more components sit beside the request path rather than on it. The catalog records every tool with its owner, version, scopes, risk tier and lifecycle state (Sharing across teams, Governance). The audit store keeps one event per call, allowed or refused, joined to traces by trace_id (Observability and audit). And the underwriter cockpit gives a person the only path to record_underwriter_decision, with that person's own delegated token.

Diagram: The assessment platform · one service, three adapters, an owner on every box

Each lane is an owner. Consumer teams run their own hosts. Identity and security governance run the identity provider and the token exchange. The platform team runs the gateway, the catalog and the audit store. The server maintainers write uw-assessment, a thin adapter. The assessment domain owns the REST adapter, the service and the only database credentials. The underwriting workbench calls the service in-process (ADR-001); programs that are not agents use REST; other teams' agent hosts and the cockpit use the remote MCP server. Every arrow that crosses a lane carries a credential checked on arrival. Click a box for what it does in the example.

  1. Consumer teams · their hosts and clients
    1. Claims assistant: The claims team's agent host. Reads roof facts and rule outcomes for its own business unit, through the remote MCP server.
    2. Underwriting workbench: The underwriting agent's application. Owned with the service, so it calls the service in-process and records recommendations; it never records decisions.
    3. Underwriter cockpit: The only path to record_underwriter_decision: a person with role underwriter, using their own delegated token, client uw-cockpit.
    4. Support desk: Sees a status summary only: no roof age, no evidence ids.
    5. Analytics jobs: Reads aggregates per business unit, never one submission (UW-M12).
    6. Ticketing and batch jobs: Non-agent callers use the REST adapter with a token issued for the assessment service.
  2. Identity and security governance · who may hold what
    1. Identity provider: Signs people and workloads in and issues tokens naming subject, client, scopes, business unit and audience. A toy stand-in in the example.
    2. Token exchange: Trades the caller's token for a downstream token: audience the service, subject the caller, actor the MCP server, one scope, 60 s.
  3. Platform team · reach
    1. Gateway: Rejects what any server would reject: no token, wrong audience, expired, over the per-client rate limit. Not present in the example, where the server does all of it.
    2. Catalog and lifecycle: Records each tool's version, owner, maintainer, scopes, principal types, risk tier and state; the source for gateway and server policy.
    3. Audit store and traces: Append-only evidence of every call, allowed or refused, joined to the trace by trace id.
  4. Server maintainers · form
    1. MCP server uw-assessment: A thin adapter: validates the token for its own audience, filters discovery, validates arguments, authorizes every call, exchanges the token, calls the service, writes the audit event. Owns no business rule.
  5. Assessment domain · meaning and data
    1. REST adapter: The HTTP API for programs that are not agents; another adapter over the same service.
    2. Assessment service: Owns R-ROOF-03 and every other rule, opens every transaction, and checks again that only a person with role underwriter causes a decision.
    3. Database: Only the service holds credentials: uw_reader reads, uw_rec_writer inserts recommendations, uw_decision_writer inserts decisions.

Each lane is an owner. Every arrow that crosses a lane carries a credential checked on arrival.

ComponentOwnerIts one jobWhere the site teaches it
Assessment service and database (scoped accounts)assessment domainowns rules, data, transactionsThe database decision
Direct path (in-process call)underwriting team (ADR-001)the workbench calls the service with no hopPlaybooks
REST adapterassessment domainnon-agent callers, token audience the serviceStart
MCP server uw-assessmentserver maintainersthin adapter: discovery, per-call authorization, auditFirst server
Gatewayplatform teamearly rejection, routing, per-client rate limitsEnterprise authorization
Identity provider and token exchangeidentity and security governanceissues tokens; trades them for downstream tokensEnterprise authorization
Catalog and lifecycleplatform team, with the domain owner and securitywhich tools exist, in which state, owned by whomGovernance
Audit store and tracesplatform team; read by audit and complianceevidence of every call and decisionObservability and audit
Underwriter cockpitunderwriting teamthe person's decision pathWho gets access

Where the policy is decided, and where it is enforced#

Two words make the gateway question precise. A policy decision point (PDP) is the component that takes a request and the applicable policy and computes allow or deny. A policy enforcement point (PEP) is the component that actually stands in front of the resource and lets a request through or stops it, based on a decision. A tiny example: policy.authorize() in the example answers "may claims-assistant read SUB-2001?" with deny; that is the decision. The code in McpServer.tools_call that then returns not_found instead of calling the service is the enforcement. Both terms come from access-control standards; NIST's glossary defines them from XACML and from its attribute-based access control guide, and NIST's zero trust architecture (SP 800-207) separates them as logical components.

They have different needs. A decision needs data: to refuse SUB-2001, the decider must know it belongs to commercial-east. Enforcement needs position: on every path to the resource, or a request on another path is never checked.

Ecosystem pattern: the zero trust model of NIST SP 800-207 puts enforcement points in front of resources and keeps the decision in a separate policy engine; a gateway in front of many MCP servers can follow that pattern by asking a central policy service. Normative (MCP specification 2026-07-28): the specification does not define a gateway as a protocol role, and it requires the server itself to validate that a token was issued for it. This site's recommendation: let the gateway enforce what any server would refuse (no token, wrong audience, expired, over the rate limit), and keep the full decision, including the tenant check, in the MCP server, where the data is. The example goes one step further for teaching and puts both the decision and the enforcement in the server; there is no separate gateway process.

The smallest piece of this design is the decision itself, a pure function of claims, tool, arguments and the data the tenant check needs. The script calls the example's policy.authorize for five calls the platform must get right. It proves what the policy decides, not that every path passes through it; the walk below checks that.

"""The policy decision point as a pure function (scratch script around examples/uw-mcp/policy.py)."""
from clock import SimClock
from identity import claims_for
from policy import authorize

clock = SimClock()
units = {"SUB-1004": "commercial-west", "SUB-2001": "commercial-east"}
calls = [
    ("claims-assistant", None, "get_roof_assessment", {"submission_id": "SUB-1004"}),
    ("claims-assistant", None, "get_roof_assessment", {"submission_id": "SUB-2001"}),
    ("analytics-jobs", None, "get_roof_assessment", {"submission_id": "SUB-1004"}),
    ("underwriting-agent", "uw.read uw.recommend uw.decide", "record_underwriter_decision",
     {"submission_id": "SUB-1004", "decision": "approve", "reason": "x", "override": False}),
    ("underwriter", None, "record_underwriter_decision",
     {"submission_id": "SUB-1004", "decision": "approve", "reason": "x", "override": True}),
]
for principal, scope, tool, args in calls:
    claims = claims_for(principal, clock, scope=scope)
    d = authorize(claims, tool, args, opts={"submission_units": units})
    print(f"{principal:<19} {tool:<28} {args['submission_id']}  allowed={d['allowed']!s:<5} "
          f"check={d['check']:<14} {d['detail']}")
claims-assistant    get_roof_assessment          SUB-1004  allowed=True  check=all            scope, principal type and business unit checks passed
claims-assistant    get_roof_assessment          SUB-2001  allowed=False check=tenant         no submission SUB-2001 in business unit commercial-west
analytics-jobs      get_roof_assessment          SUB-1004  allowed=False check=scope          get_roof_assessment needs scope uw.read
underwriting-agent  record_underwriter_decision  SUB-1004  allowed=False check=principal_type record_underwriter_decision is for principal type user; this caller is agent
underwriter         record_underwriter_decision  SUB-1004  allowed=True  check=all            scope, principal type and business unit checks passed

The fourth line is the one the reviewer asked about. Someone granted the underwriting agent uw.decide by mistake, and the decision still says no, because the catalog record of record_underwriter_decision allows principal type user, role underwriter and client uw-cockpit only. The assessment service checks the same rule again before it inserts a decision. A protocol standardizes the call. It does not grant the permission.

Four consuming teams, and what each may hold#

A consumer team is a team that runs its own application on top of a shared capability and is accountable for how that application uses it. For example, the claims team runs the claims assistant, holds the client id claims-assistant, and answers for what its adjusters see. The platform has four. Each gets its own client id, its own token with its own scopes, its own rate limit and its own metrics, because a rate limit, a tenant check and an incident all need to know which team is calling.

Claims reads roof facts for storm claims in its own business unit. Underwriting has two clients: the workbench recommends, the cockpit lets a person decide. Support sees where a submission is, never its roof age. Analytics sees aggregates only (Playbooks, ADR-005).

TeamPrincipal and clientScopesVisible toolsData it may seeOwnsMust never get
claimsagent claims-assistant, client claims-assistant, unit commercial-westuw.readget_roof_assessment, search_guidance, check_eligibilityfull assessment and rule outcome, own unit onlyits host, client, token use, what adjusters are shownany write scope; another unit's submissions
underwriting (agent)agent underwriting-agent, client uw-workbench (direct path in production, ADR-001)uw.read uw.recommendthe three reads, record_recommendationfull assessment, own unitthe recommendation it writes, idempotency keysuw.decide usable by any agent
underwriting (person)user underwriter, role underwriter, client uw-cockpituw.read uw.decidethe three reads, record_underwriter_decisionfull assessment and the recommendationthe decision and its reasona decision written by anyone but the person
supportservice support-desk, unit commercial-westsupport.readget_assessment_statusa status summary: no roof age, no evidencethe broker conversationuw.read; roof ages; evidence ids
analyticsservice analytics-jobs, unit allanalytics.readget_assessment_statscounts per business unit, no submission idsthe statistics it publishesany per-submission tool

Analytics has the widest business unit, all, and the narrowest data; the scope and the tool, not the unit, keep it away from single submissions (case UW-M12). The audit agent is not a consuming team: no tool needs audit.read, so its access is to the audit store only (Who gets access).

The lab below runs a scripted workload per team against the example's real HTTP server: each team's visible tools, a sample call and its own metrics next to the others'. 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.

Synthetic counts from a scripted workload; they measure nothing.

TeamClientScopesVisible toolsCalls / allowed / refused / rate limitedBucket
claimsclaims-assistantuw.readget_roof_assessment, search_guidance, check_eligibility6 / 4 / 1 / 13, refill 1 per s
underwritinguw-workbenchuw.read uw.recommendthe three reads and record_recommendation4 / 4 / 0 / 010, refill 5 per s
underwritinguw-cockpit (the underwriter)uw.read uw.decidethe three reads and record_underwriter_decision1 / 1 / 0 / 05, refill 1 per s
supportsupport-desksupport.readget_assessment_status3 / 2 / 1 / 05, refill 2 per s
analyticsanalytics-jobsanalytics.readget_assessment_stats4 / 2 / 1 / 12, refill 1 per s

The claims assistant's fourth call within 300 ms found its bucket empty, and no other team was slowed. That is the point of a rate limit per consumer on a shared server (Resilience).

One request, end to end: UW-004 for SUB-1004#

Now the reviewer's walk. Series case UW-004: the application says the roof is 9 years old, the provider says 22 (EV-ROOF-0412), and rule R-ROOF-03 escalates when the gap exceeds 5 years. Follow it through three principals. The claims assistant reads the assessment and the rule outcome. The underwriting workbench records the recommendation. The underwriter decides in the cockpit.

The model writes each tool request; the host's MCP client sends it; the server validates, authorizes and executes it through the assessment service.

Diagram: UW-004 end to end · a read for the claims assistant, then the person's decision

Time runs down the page. The claims assistant's model writes a request; its host's MCP client sends it with a token whose audience is the MCP server. The gateway rejects only what any server would. The server validates again, checks the arguments and authorizes this call for this submission. It trades the token for a downstream one, calls the assessment service, writes an audit event and replies. Later the underwriter decides through the cockpit with a delegated token; the service checks again and links the decision to the recommendation. Click a message for the real value from the run.

  1. Claims assistant (host's client) to Gateway (platform): tools/call get_roof_assessment SUB-1004. The token's audience is the MCP server; the request carries a correlation id and a traceparent in its metadata.
  2. Gateway (platform) to uw-assessment: token and rate limit passed. The gateway forwards; it does not decide tenant questions, because it lacks the domain data.
  3. uw-assessment: validate again · schema · authorize. Token for this audience, arguments against the input schema, then scope, principal type and business unit for this call.
  4. uw-assessment to Identity provider: exchange the caller's token. The caller's token is never forwarded; a new one is requested for the service.
  5. Identity provider to uw-assessment: downstream token · scope assessment.read. Subject the claims assistant, actor the MCP server, 60 s.
  6. uw-assessment to Assessment service: get_roof_assessment with the new token. The service validates the downstream token and reads with the uw_reader account.
  7. Assessment service to uw-assessment: PropertyAssessment · roof 22 · EV-ROOF-0412. The same DTO every architecture on this site returns.
  8. uw-assessment to Audit store: AUD-0002 allowed. Who, sanitized arguments, decision, outcome, correlation id, trace id, policy version.
  9. uw-assessment to Claims assistant (host's client): result · structuredContent. The reply returns through the gateway; check_eligibility then answers escalate citing R-ROOF-03.
  10. Underwriter cockpit to uw-assessment: record_underwriter_decision · person's token. Only a user with role underwriter from client uw-cockpit passes; an agent is refused even with uw.decide.
  11. uw-assessment to Assessment service: insert decision · subject the person. The service checks principal type and role again, then inserts with the uw_decision_writer account.
  12. Assessment service to Underwriter cockpit: DEC-0001 linked to REC-0001. The recommendation stays a recommendation; the person's decision is recorded beside it.

The script that produced the output below is a scratch helper around the example's own test harness (scenarios.Remote, the real Streamable HTTP server on 127.0.0.1 for one run), with per-client rate limits as in teams.py. It was run on 2026-11-18 in a scratch copy of examples/uw-mcp. What it proves: every hop in the example checks what this page says it checks, and the ids line up. What it does not prove: that a deployed gateway, identity provider and service behave the same; in the example the hop to the service is in-process and the token exchange is a stand-in.

/opt/homebrew/bin/python3 walk_uw004.py
1 claims, no token: 401 Bearer resource_metadata="https://mcp.uw.insurer.example/.well-known/oauth-protected-resource", scope="uw.read"
2 metadata: 200 {"resource": "https://mcp.uw.insurer.example", "authorization_servers": ["https://idp.insurer.example"], "scopes_supported": ["uw.read", "support.read", "analytics.read"]}
3 token claims: {"sub": "agent:claims-assistant", "principal_type": "agent", "client_id": "claims-assistant", "aud": "https://mcp.uw.insurer.example", "scope": "uw.read", "business_unit": "commercial-west", "jti": "jti-820ab67b"}
4 claims tools/list: HTTP 200 tools=['get_roof_assessment', 'search_guidance', 'check_eligibility'] cacheScope=private
5 claims get_roof_assessment: HTTP 200 isError=False {"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"}
6 claims check_eligibility: HTTP 200 isError=False {"submission_id": "SUB-1004", "outcome": "escalate", "rule_ids": ["R-ROOF-03"], "findings": ["The application states 9 years; the provider assessed 22 years (EV-ROOF-0412): a gap of 13 years."], "policy_version": "2026.2", "requires_human": true}
7 workbench record_recommendation: HTTP 200 isError=False {"recommendation_id": "REC-0001", "submission_id": "SUB-1004", "recommendation": "escalate", "status": "awaiting_underwriter", "idempotent_replay": false}
8 cockpit record_underwriter_decision: HTTP 200 isError=False {"decision_id": "DEC-0001", "submission_id": "SUB-1004", "human_decision": {"decided_by": "underwriter", "decision": "approve", "override": true, "reason": "Roof replaced in 2017; invoice seen (synthetic)."}, "recommendation_id": "REC-0001"}
--- audit events
{"id": "AUD-0001", "event": "auth_refused", "client": null, "tool": "get_roof_assessment", "decision": "refused", "check": "token", "outcome": "http_401", "corr": "corr-uw-004-00", "trace": "aeddd64e"}
{"id": "AUD-0002", "event": "tool_call", "client": "claims-assistant", "tool": "get_roof_assessment", "decision": "allowed", "check": "all", "outcome": "ok", "corr": "corr-uw-004-02", "trace": "544b00ad"}
{"id": "AUD-0003", "event": "tool_call", "client": "claims-assistant", "tool": "check_eligibility", "decision": "allowed", "check": "all", "outcome": "ok", "corr": "corr-uw-004-03", "trace": "40fce4ff"}
{"id": "AUD-0004", "event": "tool_call", "client": "uw-workbench", "tool": "record_recommendation", "decision": "allowed", "check": "all", "outcome": "ok", "corr": "corr-uw-004-04", "trace": "c968a0bc"}
{"id": "AUD-0005", "event": "tool_call", "client": "uw-cockpit", "tool": "record_underwriter_decision", "decision": "allowed", "check": "all", "outcome": "ok", "corr": "corr-uw-004-05", "trace": "bbbcea0a"}
--- downstream token exchanges
{"tool": "get_roof_assessment", "aud": "https://assessment-svc.internal.example", "scope": "assessment.read", "sub": "agent:claims-assistant", "actor": "svc:uw-assessment-mcp", "caller_token_forwarded": false}
{"tool": "check_eligibility", "aud": "https://assessment-svc.internal.example", "scope": "assessment.read", "sub": "agent:claims-assistant", "actor": "svc:uw-assessment-mcp", "caller_token_forwarded": false}
{"tool": "record_recommendation", "aud": "https://assessment-svc.internal.example", "scope": "assessment.write.recommendation", "sub": "agent:underwriting-agent", "actor": "svc:uw-assessment-mcp", "caller_token_forwarded": false}
{"tool": "record_underwriter_decision", "aud": "https://assessment-svc.internal.example", "scope": "assessment.write.decision", "sub": "usr-uw-0007", "actor": "svc:uw-assessment-mcp", "caller_token_forwarded": false}
--- rows: recommendations 1 decisions 1
recommendation row: awaiting_underwriter decision row: approve usr-uw-0007 links REC-0001

Read it hop by hop. Line 1: no token, so the server answers 401 and points to its protected resource metadata, which names the authorization server (line 2). Line 3: the claims assistant's token, with the MCP server as its only audience. Line 4: filtered discovery, three tools, cacheScope private because the list depends on who asks. Lines 5 and 6: the same PropertyAssessment every architecture on this site returns, and the rule outcome escalate citing R-ROOF-03.

Line 7 is the workbench's write, stored as awaiting_underwriter. In production ADR-001 makes this call in-process; the example sends it through uw-assessment so one run exercises every control. Either way it ends in AssessmentService.record_recommendation and the uw_rec_writer account. Line 8 is the person: the underwriter approves with an override and a reason, the decision links to REC-0001, and the recommendation stays a recommendation (this site's own case UW-M10). The model recommends; a person decides.

The records below the results are what the reviewer needed: one audit event per call, including the refused first contact, and one downstream exchange per executed call, each with the service as audience, the caller as subject, the server as actor and one narrow scope. The caller's token was never forwarded, and the decision's subject is the person, usr-uw-0007.

So the reviewer's last question has a short answer. The protection against an agent deciding lives in three places that do not depend on each other: the catalog record (principal type user, role underwriter, client uw-cockpit), the server's per-call decision, and the service's own check before the insert. A mistaken scope grant passes none of them.

When something goes wrong: six failures and the component that catches each#

The same platform under failure. Each case below is this site's own, runs in the example, and has a page that explains it fully; here the point is which component catches it.

CaseWhat happensComponent that catches itRead
UW-M03the intake agent calls record_recommendation by name, although it was not listedserver, per-call decision: 403 insufficient_scope, audit event, 0 rowsWho gets access
UW-M04a token issued for https://crm.insurer.example arrivesserver token validation (gateway too, if present): 401 invalid_tokenEnterprise authorization
UW-M08the assessment service times outserver's deadline and bounded retry for reads; one attempt for writes, safe retry by idempotency keyResilience
UW-M09injected text in passage P-NOTE-17 asks for record_underwriter_decision with approveserver: no uw.decide; even a misgranted one fails the principal type check; 0 decision rowsThreat model
UW-M11the claims assistant asks for SUB-2001 (commercial-east)server tenant check: not_found, the same answer as a missing submissionWho gets access
UW-M12analytics asks for one submissionserver scope check: 403; get_assessment_stats allowed, no submission idsSharing across teams
case    result title                                        key result
UW-M03  PASS   Discovery filtering is not authorization     listed=false
UW-M04  PASS   A token for another resource                 http_status=401
UW-M08  PASS   The assessment service times out             read_code=timeout
UW-M09  PASS   Injected text asks for a decision            proposed=record_underwriter_decision
UW-M11  PASS   Another business unit's submission           code=not_found
UW-M12  PASS   Analytics asks for one submission            record_status=403
12/12 cases match their expected block. (Scripted stand-in model: this shows the protocol and the controls, not model quality.)

Those are the six cases' rows from a run of all twelve (run_cases.py, scratch copy, 2026-11-18). The server catches almost everything, on purpose: the gateway may reject UW-M04 earlier and a careful model may never propose UW-M09's call, but neither is relied on. The service's own checks sit behind the server, so a bug in the server's policy is not yet a breach.

Production pitfall. Without per-call authorization, UW-M03 writes a row: with the execution check switched off, the example returned HTTP 200 and stored the intake agent's recommendation.

Control plane and data plane#

The table of components mixes two kinds of work, and separating them explains who can break what. The control plane is the set of components that decide and configure what may happen: who may hold which scope, which tools exist and in which state, which tokens the identity provider will issue, which limits apply to which client. For example, security approving uw.recommend for agents, and the platform team moving a tool version to "discoverable", are control-plane acts. The data plane is the path that carries the actual work: a host's request through the gateway and server to the service and the database, and the reply. For example, line 5 of the walk, the claims assistant's read of SUB-1004, is pure data plane. NIST SP 800-207 draws the same line in its zero trust architecture: the control plane is used to judge, grant or deny access and set up paths; the data plane is used for the actual communication.

PlaneComponents in this designChanges how oftenWho may change it
Controlidentity provider policy and exchange policy; scope approvals; catalog and lifecycle; gateway and server policy configuration; rate-limit and breaker settingsrarely, through reviewsecurity, platform team, domain owner, per the RACI
Datahost and MCP client; gateway; MCP server; assessment service; database; audit store writeson every requestnobody at run time: it only executes what the control plane allows

The two fail differently. A data-plane failure (the service times out, UW-M08) affects calls now and recovers with the dependency. A control-plane mistake (a scope granted to the wrong principal type) affects every later call until someone notices, which is why its changes go through the lifecycle on Governance and why every audit event records the policy version.

Diagram: Control plane and data plane · decide and configure rarely, execute on every request

The top lane decides and configures: scope approvals, the catalog and lifecycle, identity provider policy, and the policy and limits loaded into the gateway and the server. Those change rarely and through review. The bottom lane carries every request: host, gateway, MCP server, service, database, and the audit event written on the way. The data plane only executes what the control plane allows. One arrow crosses back: in this design the server asks the identity provider for an exchanged token on every call, so a control-plane service sits on the data path.

  1. Control plane · reviewed changes
    1. Scope approvals: Which scopes exist and which principal types may hold them.
    2. Catalog and lifecycle: Which tools exist, in which state, with which owner and tier.
    3. Identity provider policy: Which tokens may be issued and exchanged, for which audience and scope.
    4. Gateway and server policy: Configuration derived from the catalog: rate limits per client, breaker thresholds, principal types per tool.
  2. Data plane · every request
    1. Host and MCP client: Sends the request the model wrote, with its own token.
    2. Gateway: Rejects what any server would reject.
    3. MCP server: The full per-call decision, then the service call with an exchanged token.
    4. Service and database: Executes with a scoped account and writes in one transaction.
    5. Audit store: Evidence written on the data path, read later by audit and compliance on the control side.

One component sits between the planes. Token exchange is a control-plane service, but the server asks for an exchanged token on every executed call, so the identity provider is on the data path: if it is slow, every tool call is slow. The folded block on regions below returns to this.

Who answers for what#

The RACI on Governance gives every activity exactly one accountable role. In this architecture: the domain data owner answers for meaning, publishing and deprecation; identity and security governance for scopes, risk tiers, access grants and incidents; the server maintainers for running the server, which the platform team operates along with publishing and granting; each consumer application owner for its own client; audit and compliance for reviewing the evidence. An allowed call that policy should refuse is stopped first by the platform team at the gateway, and security decides when the tool comes back.

Governance note. The design's most important rule, no agent records an underwriting decision, is protected by people as well as code: the decision tool is in the critical tier, any change to its catalog record needs two approvers, and a fitness check fails the build if any agent principal can call it (Playbooks, ADR-003).
Security note. Only the assessment service holds database credentials. No host, gateway, MCP server or agent does. A fooled agent, as in UW-M09, therefore has no credential that could bypass the server even in principle, and a new consumer team never triggers a database grant.

What this design deliberately does not do#

A reference architecture is as much about the paths it refuses. This one gives no agent a database account, and no agent record_underwriter_decision, whatever its scopes. It offers no generic query tool. It never forwards a caller's token. It never shares a client id between teams. It answers not_found, not "forbidden", for another unit's submission, so existence does not leak. It keeps every business rule, R-ROOF-03 included, in the service. It does not retry writes at the server; the idempotency key makes a client's retry safe. And it does not delegate work to other agents; that belongs to a different protocol (Advanced MCP).

What this is not. This page is one design for one capability, not a product recommendation. Which gateway, registry or identity product implements a box is on Ecosystem. Recovering a whole agent workflow after failures belongs to https://reliable.sammuthu.com, and logs, metrics and traces as a discipline to https://observe.sammuthu.com.
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. The MCP server and client are a teaching subset of revision 2026-07-28, not the official SDK and not conformance tested; the tokens are toy tokens, and the identity provider and token exchange are stand-ins.

The same platform, from the outside#

The five lab at stage 5 shows what the remote server adds over the four simpler ways to offer the lookup, and who deploys each part.

StageProcess / network hopsTrust boundariesIdentity at the callWho deploys
1. Direct function call0 / 0application to databasenone at the call; the application's database accountconsumer application owner; the assessment domain (database)
2. Model-callable tool0 / 0model output to application code; application to databasethe application sessionconsumer application owner (application, tool definitions, adapter); the assessment domain
3. Private HTTP API1 / 1agent application to the API (bearer token, audience the API); API to databasebearer token issued for the assessment APIconsumer application owner; the assessment domain; the platform team (optional gateway)
4. Local MCP server (stdio)1 / 0host to server process (same OS user); server to databasethe OS process owner; principal from the environment variable UW_MCP_PRINCIPALthe user or consumer application owner; the server maintainer; database credentials end up on each machine
5. Remote MCP server (Streamable HTTP)2 / 2host to MCP server (audience https://mcp.uw.insurer.example); MCP server to the service (exchanged token, audience https://assessment-svc.internal.example); service to databaseaccess token with an audience, validated on every request; a separate downstream tokeneach consumer team; the server maintainer; the platform team; identity and security governance; the assessment domain

The platform uses three of these rows at once: stage 1 for the underwriting workbench (ADR-001), stage 3 for non-agent callers, stage 5 for the other teams' agent hosts. That mix is the honest answer this site has argued for since Start: choose the rung per caller, over one service.

In a coding agent. The same shape fits a company that gives coding agents shared MCP servers. The repository service owns the code and its permissions; a remote repository MCP server offers read_file and search_code to every team's coding agent with a token per developer; open_pull_request is a write that needs its own scope; merging stays with a person, the cockpit equivalent. A developer's local issue-tracker server is stage 4 on their own laptop. Harness Engineering shows where these servers sit in the agent's runtime.

Checklist for Monday#

CheckPass when
One owner per boxEvery component names a team; every cross-lane arrow names its credential
CredentialsOnly the domain service holds database accounts, one purpose each
Thin adaptersNo business rule in the MCP server, the REST adapter or the gateway
Decision at the serverThe full per-call decision, tenant check included, runs at the server
No passthroughA test proves the caller's token never reaches the service
Human pathOnly a person's delegated token from the cockpit can record a decision

Exercises#

  1. A fifth team, pricing, wants the rule outcome of check_eligibility for its own business unit, but not the roof facts behind it. What do you give it, and which component changes?
  2. The platform team proposes to move the tenant check from the server to the gateway "so every server gets it for free". What breaks?
  3. The identity provider has an outage for ten minutes. Which calls in the walk still succeed in this design, and why?
AnswersOne line each
  1. A new client id and a scope review; check_eligibility returns findings that include roof ages, so the likely first offer is a new narrow tool (outcome and rule ids only) on the same server, owned by the domain and published through the lifecycle.
  2. The gateway does not know which unit SUB-2001 belongs to without the domain's data, and any path that bypasses the gateway would skip the check; keep the decision at the server.
  3. Almost none: every executed call asks the identity provider for a downstream token, and new callers cannot get a token at all, so the identity provider is on the data path; caching exchanged tokens per caller and scope for their short life reduces that dependency but does not remove it.
One server for the domain, or one per team?Why the design has one uw-assessment, and when it would split

The design has one MCP server for the assessment domain, used by all four teams. The alternative that looks tidy, one server per consuming team, is almost always worse: four adapters wrap the same service with slightly different tools, each team's policy drifts, and a change in the domain needs four releases. Different views belong in different tools on the domain's server with different scopes, as get_assessment_status and get_assessment_stats show.

The one-server design has its own costs. Every team's traffic meets in one place, so per-client rate limits and metrics are mandatory, not optional; one bad release affects all four teams at once; and the server's on-call carries everyone's incidents. A split becomes right when the parts really differ in risk or operations. The strongest candidate here is the decision tool: record_underwriter_decision is the only critical-tier tool and has a single client, uw-cockpit. Moving it to a separate server with its own deployment, its own audience and stricter change control shrinks what a mistake in the shared server can touch. The cost is a second catalog entry, a second audience for the cockpit's token, and duplicated authorization code that must stay in step, so make the split when the review burden of the critical tool starts to slow every other release, not before.

Gateway-centric or server-centric enforcement?Where the decision and the enforcement live, three ways, and what each loses

Gateway-centric: the gateway is the policy enforcement point for everything and asks a central decision service; servers trust the gateway. One place to patch, consistent answers, policy written once. It loses two things. The tenant check needs domain data (which unit owns SUB-2001) that the gateway or the central decider must now fetch or mirror, which couples the platform to every domain's data model. And any path that reaches a server without the gateway, such as a misrouted internal call or a debug port, arrives unchecked. Normative (MCP specification 2026-07-28): a server must still validate that the token was issued for it, so a server cannot rely on the gateway for that check.

Server-centric (the example): each server validates its tokens and runs its full decision; no gateway is required. Nothing depends on the path, and the decision sits next to its data. It loses consistency at scale: twenty servers mean twenty implementations of token validation and twenty chances to get one wrong, unless they share a library and a test suite.

Layered (this site's recommendation): the gateway enforces the checks that need no domain data (token present, signature, audience, expiry, rate limit, header and body agreement), and each server validates again for its own audience and makes the full per-call decision. Derive both from one policy source so the gateway never allows what the server refuses, and test the pair with the authorization matrix from Testing. The cost is one more signature check per hop; the benefit is that removing either layer degrades the platform without opening it.

One region, or one deployment per business unit?Tenant isolation by code, by deployment, or by data, and the identity provider on the data path

The example runs one server for two business units, commercial-west and commercial-east, and isolates them in code: the tenant check answers not_found for the other unit (case UW-M11). That is cheap and auditable, and every isolation guarantee rests on one function being right.

A deployment per business unit moves isolation into infrastructure: a server and a service instance per unit, each with its own database or schema, each token audience naming its unit's server. A bug in the tenant check can then no longer leak another unit's data, because the data is not reachable. The costs are real: two deployments to run, release and keep in step; analytics, which legitimately reads aggregates across all units, now needs a fan-out or a separate aggregate store; and the catalog must describe one tool offered by two servers. Regulation sometimes decides this for you, for example when units must keep data in different jurisdictions; then per-unit deployment is a requirement rather than a choice.

Regions add the control-plane question from this page. Each executed call asks the identity provider for an exchanged token, so a region that loses its path to the identity provider loses its tool calls. The mitigations are to cache exchanged tokens per caller, scope and audience for their short life (60 seconds in the example), to run the identity provider's token endpoint in each region the platform runs in, and to decide in advance what the cockpit does when no token can be issued: show the underwriter that the decision cannot be recorded, never queue it under another identity.

What changes at fifty teamsThe design holds; the review, the catalog and the matrix have to become automatic

At four teams, people can hold the whole design in their heads. At fifty, five things change, and none of them is the protocol.

Access grants become the bottleneck. Fifty teams asking for scopes on many servers will swamp a central security review, so grants for low and medium tiers move to a federated model inside platform rules, with high and critical tiers kept central (Governance). The authorization matrix grows from tens of cells to thousands, so it is generated from the catalog records rather than written by hand, and runs as a fitness check (Testing). Tool lists grow too large for a model's context, so discovery filtering and narrower per-team lists stop being a convenience and become necessary for the model to choose well (Advanced MCP); filtering is still not authorization. Per-client metrics turn into the main operational signal: with fifty clients, one noisy consumer is normal, and rate limits and breakers per consumer and per dependency are what keep it from becoming everyone's incident. And the catalog becomes the system of record that other systems read: the gateway's policy, the server's allowed principal types, the review schedule and the incident contact list are all generated from it, because fifty teams will not keep five copies in step.

What does not change is the shape on this page: one domain service with the only credentials, thin adapters per kind of caller, a decision at the server for every call, a separate token per hop, an audit event per call, and a person on the decision path.

The direct path: what ADR-001 gains and what it gives upNo hop and the application's transactions, at the cost of the server's shared controls

The underwriting workbench calls the service in-process. It gains no network hop, no token exchange on its path and the service's own transactions around its writes. It gives up the controls the MCP server provides for everyone else: the workbench does not appear in the server's per-client metrics or rate limits, and its audit events come from the service, not from the server. Those must be added on purpose: the service writes an audit event with the same fields for direct calls, and the scoped account the workbench's process uses can insert recommendations and nothing else.

The decision that keeps the direct path safe is that it carries no human decision. The cockpit never uses it; record_underwriter_decision always arrives with the person's delegated token, so the subject on the decision row is always the person. ADR-001 names its own exit condition: if the workbench moves to a team that does not own the service, it moves to the remote server like every other consumer.

In one breath#

The assessment platform is one domain service with the only database credentials, three thin adapters (in-process for the team that owns it, REST for programs, a remote MCP server for other teams' agent hosts), and around them an identity provider, a gateway, a catalog, an audit store and a cockpit, each with a named owner. Every call carries its own caller's token, is decided and enforced at the server for that caller and that submission, reaches the service with a separate exchanged token, and leaves an audit event. Four consuming teams each get their own client, scopes, limits and metrics, and no agent can record a decision. The model recommends; a person decides, and the design makes that sentence true in three independent places.

This design is the sum of many decisions, and a design that lives only in a diagram is redone at the next reorganization. The last page turns its questions into checklists and short decision records a team keeps next to the code: Playbooks.