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.
- Consumer teams · their hosts and clients
- Claims assistant: The claims team's agent host. Reads roof facts and rule outcomes for its own business unit, through the remote MCP server.
- 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.
- Underwriter cockpit: The only path to record_underwriter_decision: a person with role underwriter, using their own delegated token, client uw-cockpit.
- Support desk: Sees a status summary only: no roof age, no evidence ids.
- Analytics jobs: Reads aggregates per business unit, never one submission (UW-M12).
- Ticketing and batch jobs: Non-agent callers use the REST adapter with a token issued for the assessment service.
- Identity and security governance · who may hold what
- 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.
- 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.
- Platform team · reach
- 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.
- Catalog and lifecycle: Records each tool's version, owner, maintainer, scopes, principal types, risk tier and state; the source for gateway and server policy.
- Audit store and traces: Append-only evidence of every call, allowed or refused, joined to the trace by trace id.
- Server maintainers · form
- 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.
- Assessment domain · meaning and data
- REST adapter: The HTTP API for programs that are not agents; another adapter over the same service.
- 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.
- 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.
| Component | Owner | Its one job | Where the site teaches it |
|---|---|---|---|
| Assessment service and database (scoped accounts) | assessment domain | owns rules, data, transactions | The database decision |
| Direct path (in-process call) | underwriting team (ADR-001) | the workbench calls the service with no hop | Playbooks |
| REST adapter | assessment domain | non-agent callers, token audience the service | Start |
MCP server uw-assessment | server maintainers | thin adapter: discovery, per-call authorization, audit | First server |
| Gateway | platform team | early rejection, routing, per-client rate limits | Enterprise authorization |
| Identity provider and token exchange | identity and security governance | issues tokens; trades them for downstream tokens | Enterprise authorization |
| Catalog and lifecycle | platform team, with the domain owner and security | which tools exist, in which state, owned by whom | Governance |
| Audit store and traces | platform team; read by audit and compliance | evidence of every call and decision | Observability and audit |
| Underwriter cockpit | underwriting team | the person's decision path | Who 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).
| Team | Principal and client | Scopes | Visible tools | Data it may see | Owns | Must never get |
|---|---|---|---|---|---|---|
| claims | agent claims-assistant, client claims-assistant, unit commercial-west | uw.read | get_roof_assessment, search_guidance, check_eligibility | full assessment and rule outcome, own unit only | its host, client, token use, what adjusters are shown | any write scope; another unit's submissions |
| underwriting (agent) | agent underwriting-agent, client uw-workbench (direct path in production, ADR-001) | uw.read uw.recommend | the three reads, record_recommendation | full assessment, own unit | the recommendation it writes, idempotency keys | uw.decide usable by any agent |
| underwriting (person) | user underwriter, role underwriter, client uw-cockpit | uw.read uw.decide | the three reads, record_underwriter_decision | full assessment and the recommendation | the decision and its reason | a decision written by anyone but the person |
| support | service support-desk, unit commercial-west | support.read | get_assessment_status | a status summary: no roof age, no evidence | the broker conversation | uw.read; roof ages; evidence ids |
| analytics | service analytics-jobs, unit all | analytics.read | get_assessment_stats | counts per business unit, no submission ids | the statistics it publishes | any 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.
| Team | Client | Scopes | Visible tools | Calls / allowed / refused / rate limited | Bucket |
|---|---|---|---|---|---|
| claims | claims-assistant | uw.read | get_roof_assessment, search_guidance, check_eligibility | 6 / 4 / 1 / 1 | 3, refill 1 per s |
| underwriting | uw-workbench | uw.read uw.recommend | the three reads and record_recommendation | 4 / 4 / 0 / 0 | 10, refill 5 per s |
| underwriting | uw-cockpit (the underwriter) | uw.read uw.decide | the three reads and record_underwriter_decision | 1 / 1 / 0 / 0 | 5, refill 1 per s |
| support | support-desk | support.read | get_assessment_status | 3 / 2 / 1 / 0 | 5, refill 2 per s |
| analytics | analytics-jobs | analytics.read | get_assessment_stats | 4 / 2 / 1 / 1 | 2, 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.
- 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.
- 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.
- 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.
- 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.
- Identity provider to uw-assessment: downstream token · scope assessment.read. Subject the claims assistant, actor the MCP server, 60 s.
- 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.
- Assessment service to uw-assessment: PropertyAssessment · roof 22 · EV-ROOF-0412. The same DTO every architecture on this site returns.
- uw-assessment to Audit store: AUD-0002 allowed. Who, sanitized arguments, decision, outcome, correlation id, trace id, policy version.
- 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.
- 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.
- 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.
- 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.
| Case | What happens | Component that catches it | Read |
|---|---|---|---|
UW-M03 | the intake agent calls record_recommendation by name, although it was not listed | server, per-call decision: 403 insufficient_scope, audit event, 0 rows | Who gets access |
UW-M04 | a token issued for https://crm.insurer.example arrives | server token validation (gateway too, if present): 401 invalid_token | Enterprise authorization |
UW-M08 | the assessment service times out | server's deadline and bounded retry for reads; one attempt for writes, safe retry by idempotency key | Resilience |
UW-M09 | injected text in passage P-NOTE-17 asks for record_underwriter_decision with approve | server: no uw.decide; even a misgranted one fails the principal type check; 0 decision rows | Threat model |
UW-M11 | the claims assistant asks for SUB-2001 (commercial-east) | server tenant check: not_found, the same answer as a missing submission | Who gets access |
UW-M12 | analytics asks for one submission | server scope check: 403; get_assessment_stats allowed, no submission ids | Sharing 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.
| Plane | Components in this design | Changes how often | Who may change it |
|---|---|---|---|
| Control | identity provider policy and exchange policy; scope approvals; catalog and lifecycle; gateway and server policy configuration; rate-limit and breaker settings | rarely, through review | security, platform team, domain owner, per the RACI |
| Data | host and MCP client; gateway; MCP server; assessment service; database; audit store writes | on every request | nobody 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.
- Control plane · reviewed changes
- Scope approvals: Which scopes exist and which principal types may hold them.
- Catalog and lifecycle: Which tools exist, in which state, with which owner and tier.
- Identity provider policy: Which tokens may be issued and exchanged, for which audience and scope.
- Gateway and server policy: Configuration derived from the catalog: rate limits per client, breaker thresholds, principal types per tool.
- Data plane · every request
- Host and MCP client: Sends the request the model wrote, with its own token.
- Gateway: Rejects what any server would reject.
- MCP server: The full per-call decision, then the service call with an exchanged token.
- Service and database: Executes with a scoped account and writes in one transaction.
- 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.
| Stage | Process / network hops | Trust boundaries | Identity at the call | Who deploys |
|---|---|---|---|---|
| 1. Direct function call | 0 / 0 | application to database | none at the call; the application's database account | consumer application owner; the assessment domain (database) |
| 2. Model-callable tool | 0 / 0 | model output to application code; application to database | the application session | consumer application owner (application, tool definitions, adapter); the assessment domain |
| 3. Private HTTP API | 1 / 1 | agent application to the API (bearer token, audience the API); API to database | bearer token issued for the assessment API | consumer application owner; the assessment domain; the platform team (optional gateway) |
| 4. Local MCP server (stdio) | 1 / 0 | host to server process (same OS user); server to database | the OS process owner; principal from the environment variable UW_MCP_PRINCIPAL | the user or consumer application owner; the server maintainer; database credentials end up on each machine |
| 5. Remote MCP server (Streamable HTTP) | 2 / 2 | host to MCP server (audience https://mcp.uw.insurer.example); MCP server to the service (exchanged token, audience https://assessment-svc.internal.example); service to database | access token with an audience, validated on every request; a separate downstream token | each 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 offersread_fileandsearch_codeto every team's coding agent with a token per developer;open_pull_requestis 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#
| Check | Pass when |
|---|---|
| One owner per box | Every component names a team; every cross-lane arrow names its credential |
| Credentials | Only the domain service holds database accounts, one purpose each |
| Thin adapters | No business rule in the MCP server, the REST adapter or the gateway |
| Decision at the server | The full per-call decision, tenant check included, runs at the server |
| No passthrough | A test proves the caller's token never reaches the service |
| Human path | Only a person's delegated token from the cockpit can record a decision |
Exercises#
- A fifth team, pricing, wants the rule outcome of
check_eligibilityfor its own business unit, but not the roof facts behind it. What do you give it, and which component changes? - The platform team proposes to move the tenant check from the server to the gateway "so every server gets it for free". What breaks?
- The identity provider has an outage for ten minutes. Which calls in the walk still succeed in this design, and why?
AnswersOne line each
- A new client id and a scope review;
check_eligibilityreturns 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. - The gateway does not know which unit
SUB-2001belongs to without the domain's data, and any path that bypasses the gateway would skip the check; keep the decision at the server. - 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.