The MCP security platform, on one page: every block, its minimal contract, and the RFCs behind it

Part 5 of the MCP Security series. Parts 1-2 argued the design, Part 3 built and broke it, Part 4 signed it. This closing piece is the blueprint: the whole platform in one animated schema, then each block reduced to its minimal contract - the fields and checks you cannot skip, each traced to an RFC or a tested invariant. Everything deeper is folded away; open a cut only when you want the wire bytes, the war story, or the vendor matrix behind the rule.

How to read this page: the diagram above is the system - every green node enforces, every red exit is a call dying, each block links to its section. Per section you get a minimal contract table - implement exactly that and you have the security property - and the cuts hold the rest. The one-sentence thesis: one login is the product; one token is the vulnerability; every block exists to keep those two apart.

The platform promise, in one line: the agent never holds a credential that opens more than one door. One SSO login → many short-lived audience-bound tokens → every call mediated, checked, brokered, isolated, audited.

TL;DR - the minimal design, in five minutes

If you read nothing else, build this. It is the smallest configuration where every claim in this article still holds, and each line names the block that explains it.

The thesis in one line: one login is the product; one token is the vulnerability; every block below exists to keep those two apart.

The nine things that make it defensible. Drop any one and a specific attack comes back - the parenthetical is the block that tells you which:

1. Backends on an internal network, no host-published ports, egress deny-by-default. Build this first; it is the only item that reduces risk on its own. (B6)
2. One visible authorization server. The agent sees exactly one issuer; a 401 carries RFC 9728 metadata naming it. Your IdP and every backend stay behind the gateway. (B1)
3. Validate iss → aud → exp → scope on every request, and never forward the agent’s token downstream. Audience validation is unconditional; token passthrough is the one thing that unravels everything else. (B1)
4. One invocation chokepoint. Every path - REST, native MCP, portal - funnels into one function. A second code path is where the bypass lives. (B3)
5. Deny-by-default authorization at two levels: roles for route classes, and the same resolver for discovery and invoke, so what you cannot list you cannot call. (B2)
6. The agent never holds a credential. The gateway either exchanges its token for a backend-audienced one (RFC 8693) or decrypts a stored credential just-in-time and injects it server-side. Plaintext lives for one call. (B5)
7. Policy fails closed. Engine unreachable, malformed input, or an empty bundle → 503, never allow. (B3)
8. Nothing runs unscanned, and nothing stays approved forever. A day-1 scan gates quarantine exit; a schedule re-checks it. The scan is input to a human approval, never a substitute - and quarantine is the state a second human moves it out of, against pinned evidence. (B4, B8)
9. Synchronous audit, hashed arguments, append-only at the database, shipped off-box. A call that cannot be audited does not proceed. (B7)

The minimum stack: an IdP whose client registrations you control, a secrets store, a policy engine, a database whose grants you own, and a container runtime with private networking. Nothing exotic - but an env var is not a secrets store, and append-only is a database grant, not a convention.

What you can defer without lying about what you have: RFC 8693 exchange (stored credentials cover most real backends, and are first-class here, not a fallback), the taint floor in enforce mode (notify first, with a recorded date it stops being acceptable), signed provenance attestations, and HA. What you cannot defer is items 1 through 5 - they are structural, and retrofitting any of them costs more than building the rest.

And the honest one: if you have one agent, one backend, one user and no credential worth stealing, build none of this. The design earns its complexity where several identities meet several backends whose credentials have different blast radius.

Prerequisites - what has to be true before Block 1

Nothing below is exotic, but each item is load-bearing in a way that only shows up at the wrong moment. Read this as the bill of materials, the identity question that decides your integration count, and the four organisational facts that decide whether the build is possible at all.

The five components you must have somewhere. An identity provider you control the client registrations of - not merely “we have SSO”, but the ability to register a confidential client, add a scope, and read the token you get back. A place to root the credential key hierarchy, and a decision about its shape - the two options are not interchangeable. Either the platform reads a root secret and does its own crypto (the reference build: Vault with AppRole), or the root never leaves the store and the platform sends material in to be wrapped and unwrapped. The first discloses every stored credential the moment the platform is compromised; the second discloses only what was unwrapped while the attacker held access, and each unwrap is a record on someone else’s log. Both are defensible, they are not the same, and Block 5’s contract reads differently under each - so pick deliberately and write down which one you built. An env var is neither. A policy engine you can push signed bundles to. A database whose grants you own, because Block 7’s append-only property is a grant, not a setting. A container runtime with private networking - the isolation block is unimplementable if every service must publish a host port.

The one-IdP case: how it actually works. Start with the good news, because it is the case worth designing for when you can get it. If the backend your MCP server calls is registered in the same IdP the user logs into, one IdP and one integration is enough. Three hops, one human login.

Notation first, because the RFCs don’t give these tokens names: T_mcp and T_backend are my shorthand for two ordinary OAuth 2.1 access tokens (RFC 6749 §1.4, JWT-profiled by RFC 9068) that differ only in their aud claim. Nothing in any RFC calls them that. What is specified is every parameter below.

1. User → gateway. Authorization code + PKCE (RFC 7636, mandatory in OAuth 2.1) against the client-facing AS, discovered from the WWW-Authenticate challenge via RFC 9728 protected-resource metadata. The client sends resource=<gateway URI> (RFC 8707); the AS then audience-restricts the token it issues to that resource. How it does so is the AS’s business - 8707 does not mandate copying the URI verbatim into aud - but in every IdP in the matrix the observable result is T_mcp with aud = the gateway. The only login the human ever sees.
2. Gateway → AS. RFC 8693 token exchange, and this is the hop worth knowing parameter by parameter: grant_type=urn:ietf:params:oauth:grant-type:token-exchange, subject_token=T_mcp, subject_token_type=urn:ietf:params:oauth:token-type:access_token, plus audience and/or resource naming the backend, and a scope. The first three are what the RFC requires; the last three are OPTIONAL in 8693 and non-negotiable here - naming a backend audience and requesting a scope no wider than the subject token’s is the whole point of the hop, and an AS that ignores both hands you back something as powerful as what you sent. The AS returns access_token + issued_token_type (both REQUIRED) - that is T_backend. Client authentication at the token endpoint is the ordinary OAuth rule, not an 8693 invention; making the gateway a confidential client is this design’s choice, and it is what the agent cannot forge: it does not hold that client secret. RFC 8693 §4.1 also defines the act claim for recording the delegation chain - optional, and only ZITADEL implements it visibly among the eleven.
3. MCP server → backend. T_backend goes on the outbound call. The backend validates it by JWKS (RFC 7517 key set, at+jwt typ per RFC 9068) or by introspection (RFC 7662, active: true), checks aud is itself, and authorizes on sub - the user - not on the gateway.

Two credentials, one issuer, one connector. The two-token split is not a workaround for a vendor gap - it is the security property (Block 5: the agent never holds a credential that opens more than one door). What one IdP buys you is that both tokens come from the same place: one trust relationship to configure, one revocation surface, one place the user’s identity lives end to end.

What that IdP must have, and how the eleven actually implement it. The eleven are the ones fact-checked for Block 1’s matrix - Keycloak, PingFederate, Auth0, Entra ID, Okta, AWS Cognito, Ory Hydra, Spring Authorization Server, Authlete, ZITADEL, authentik - and the full grid with sources is in that cut. Step 2 is load-bearing: no exchange, no chain. Everything else decides how much you emulate:

The honest summary of the matrix: not one of the eleven supports the whole workflow cleanly. Keycloak - the worked example above - has exchange, introspection, JWKS and strict rotation, so all three hops run, but audience binding is emulated in the gateway rather than requested on the wire. That is the shape of every row: you pick which RFC you emulate, not whether you emulate one. Test each capability with a live positive and a live negative call before it appears in a design document - metadata that advertises a grant is a claim, not a fact, and Block 1’s metadata mirage is exactly this failure.

Where one IdP stops being enough, and what the second integration is. The one-IdP case has a hard boundary: the backend must be a client of your IdP. The moment it is not - GitHub, Jira Cloud, a vendor SaaS, a Postgres box, anything with its own identity plane or none at all - step 2 has nowhere to go. Your IdP cannot mint a token for an issuer that does not trust it, and no amount of configuration changes that. You need a second integration, and it takes one of two shapes:

• The backend’s own OAuth. Each user authorises the platform at that backend’s authorization server, once, and the resulting refresh token is stored per user, encrypted, and exchanged for a fresh access token at call time. A second consent screen the user will see, and a second token lifecycle to own.
• Stored credentials, per user or per service. Backends with no delegated flow at all - a database, an internal API with a static key, a legacy vendor. A per-user credential preserves who did what; a service account collapses attribution to the platform and has to be compensated with tighter policy and audit.

Both live in Block 5, both are typed at onboarding, and both are normal - most real estates have more backends in this category than in the first. Plan for two integrations by default; treat the single-IdP case as the reward for a homogeneous estate rather than the assumption the design rests on.

Four organisational prerequisites, and these are the ones that actually kill projects. A dual-control approver pool - Block 3’s quarantine gate and Block 4’s approval both assume a second human exists and answers; one person with two accounts is not dual control, it is a checkbox. Somewhere to send audit that is not the platform: a SIEM or log store on a different access boundary, or Block 7’s tamper story is only as good as the operator’s restraint. Named credential owners for every backend, because Block 5’s stored-credential path silently becomes a graveyard of unowned secrets otherwise - the rotation path has to belong to someone before the credential exists. And an onboarding process with a queue and an SLA, because a security gate whose median wait is a week is a gate engineers route around, and a routed-around gate is worse than no gate: it moves the traffic somewhere you cannot see it.

What you do not need, so you don’t over-scope: a service mesh (nice hardening, not identity - Part 3 demoted mTLS deliberately), a dedicated MCP registry product, Kubernetes (compose with internal networks satisfies every isolation contract here), or an LLM in the security path. The manifest audit optionally uses one; nothing else does, and nothing fails closed on its absence except the audit you explicitly required.

Block 1 · Authentication & identity

The property this block buys: every request carries a verified identity, and the agent only ever sees one authorization server - the enterprise IdP and every backend stay behind the gateway on the credential plane. An access token is a credential for a protected resource (RFC 6749 §1.4); RFC 9700 §4.10.2 requires resource servers to reject tokens not minted for them.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata=
  "https://mcp.example.com/.well-known/oauth-protected-resource/mcp"

{
  "resource": "https://mcp.example.com/mcp",
  "authorization_servers": ["https://idp.example.com/"],
  "scopes_supported": ["mcp.tools.list", "mcp.tools.invoke"],
  "bearer_methods_supported": ["header"]
}

GET /oauth/v2/authorize?
  response_type=code&client_id=<MCP_CLIENT>&
  redirect_uri=http%3A%2F%2F127.0.0.1%3A49152%2Fcallback&
  scope=openid%20mcp.tools.list%20mcp.tools.invoke&
  resource=https%3A%2F%2Fmcp.example.com%2Fmcp&
  code_challenge=<S256_CHALLENGE>&code_challenge_method=S256&
  state=<RANDOM_STATE>
Host: idp.example.com

{
  "access_token": "<T_MCP>",
  "token_type": "Bearer",
  "expires_in": 600,
  "refresh_token": "<ROTATING_REFRESH_TOKEN>",
  "scope": "mcp.tools.list mcp.tools.invoke"
}

Block 2 · RBAC & entitlement

The property this block buys: knowing who you are never implies what you may touch. Roles gate route classes; entitlement gates individual servers - and what you cannot discover, you cannot invoke.

Block 3 · Security checks: quarantine · policy · content trust

The property this block buys: every call - REST or native MCP - funnels through one chokepoint where a fixed, fail-closed pipeline runs in a defined order. No second path, no equivalent copy.

Reference-implementation status, so you can calibrate the last row: the taint floor ships off (TAINT_FLOOR_ENABLED=false) and, when enabled, defaults to TAINT_FLOOR_MODE=notify - it audits the violation and allows the call. enforce (deny, JSON-RPC -32003) is one setting away and is what the contract above means; notify is what you get out of the box, deliberately, because a floor you turn on blind will deny work you didn’t know was tainted. Run notify with an expiry recorded at the moment you enable it - a date, in the config, not a reminder in someone’s calendar - and treat reaching that date with the floor still in notify as an unenforced control in your own posture reporting, not as a configuration you chose. Without the date this is where taint enforcement goes to live permanently: detecting, permitting, and counted in the dashboard as a control that stops the thing it only watches. The contract is the destination; the default is the on-ramp; the date is what keeps it an on-ramp rather than a lay-by.

Block 4 · Server vetting & supply chain

The property this block buys: nothing runs behind the gateway that hasn’t been scanned, pinned, and approved - and nothing stays approved just because it passed once. Runtime mediation (Block 3) exists because scanners miss semantic capability; scanning exists because runtime controls shouldn’t be the first time you learn a server ships a credential stealer. Day 1 gates the door; the schedule keeps it gated.

Reference-implementation status, because this last row is the one people will check: the cadence half is built - a background scheduler re-enqueues every approved server with a source repo onto the isolated scanner worker, oldest-scanned first, and stamps freshness. Two things it deliberately does not do yet. It does not flip submission_status: a failing rescan updates the scan verdict and shows up in review, but an approved server stays approved until a human moves it - auto-re-quarantine on a CVE feed update is a self-inflicted outage waiting for a bad advisory. And the drift half is only half: mutating a tool’s description, schema or upstream URL through the registry triggers a re-audit that force-quarantines on critical risk (INV-005 / DET-F7, tested), but nothing yet periodically re-fetches tools/list from a remote server and diffs it against the approved snapshot. That poll is the actual rug-pull detector for servers you don’t build, it is maybe fifty lines against work already there, and it is not written. Treat it as the roadmap row, not the shipped one.

Block 5 · Profiles & credential broker

The property this block buys: the agent never sees a credential at all, and each backend sees exactly one - its own, for this call, and nothing that would open a different door. (The backend obviously receives the credential meant for it; that is what injection is. The property is scope and custody, not invisibility: the agent holds nothing, the ciphertext is bound to one row context, and no backend ever holds authority over another.) Profiles decide which tools an identity gets; the broker resolves, decrypts just-in-time, injects server-side, and forgets.

POST /oauth/v2/token HTTP/1.1
Host: idp.example.com
Authorization: Basic <GATEWAY_CLIENT_CREDENTIALS>
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange&
subject_token=<T_MCP>&
subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token&
requested_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token&
resource=https%3A%2F%2Fapi.internal.example.com%2F&
scope=backend-a.read

{
  "access_token": "<T_BACKEND_A>",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "backend-a.read"
}

Block 6 · Isolation

The property this block buys: a fully hostile backend MCP server gets nothing - no raw credential, no reachability except through the proxy, no lateral movement. Isolation is what makes every other block’s guarantee stick.

Block 7 · Audit

The property this block buys: every decision every block above made is reconstructable afterwards - without the audit trail itself becoming the credential leak.

Block 8 · Server onboarding & lifecycle

The property this block buys: a server is unreachable from the moment it is submitted until a second human approves it against pinned evidence, and one action makes it unreachable again. Block 4 produces the evidence; this block owns the states. It is last in the article and earliest in the lifecycle, because four other blocks read the row it writes: entitlement resolves against it (B2), the quarantine gate reads its state (B3), the broker reads its injection mode (B5), egress policy reads its declared allowances (B6). A server onboarded with no integrity level, no trust tier and no declared egress is a server those four treat as unconstrained - not because they are broken, but because they are configured by a row nobody filled in.

Reference-implementation status: release is enforced inline in the generic registry PATCH path. A bare admin cannot release a tool whose parent server is unapproved or whose scan failed, so the gate itself holds - but there is no dedicated release endpoint, no released_by / released_at, and no distinct release audit event. Which means the “record what was approved” row above is a contract the reference build does not yet meet through that path: it records that a release happened, not the digest, verdict and snapshot it happened against. It is written down in openspec/traceability.md as an open item rather than smoothed over, because this is the row where a design document would normally claim a property the code does not have.

The final design - what actually gets deployed

Eight blocks is the logical view. This is the physical one: what runs where, what may talk to what, and what order to build it in so that stopping halfway still leaves you safer than when you started.

Three planes and one edge

Every component belongs to exactly one plane, and the plane decides its reachability. This is the whole deployment model:

• Edge - the only thing with a published port. TLS terminates here; unauthenticated requests get the RFC 9728 401 and go no further.
• Agent plane - where a request is about an identity: the gateway’s ingress, RBAC, entitlement, the checks pipeline. Nothing here holds a long-lived secret.
• Credential plane - the broker, the secrets store, the IdP-facing token exchange. Reachable only from the gateway process, never from a backend, never from the host.
• Backend plane - MCP servers. No inbound route except from the proxy, egress deny-by-default. Assume every member is hostile; the design is only interesting if that assumption is load-bearing.

The reference deployment runs eleven-plus services across eight internal: true networks precisely so that “no published port” is a property of the file rather than a habit - with a CI check that greps every compose variant, including dev overrides, and fails the build when an internal service republishes itself. That check exists because the dev override is how this fails, every time.

One call, end to end

The blueprint compresses to fifteen steps. Each maps to a block; each can only fail closed:

1. Agent calls the MCP endpoint with no token → 401 + resource metadata (B1).
2. Agent discovers the one authorization server, runs authorization-code + PKCE with resource (B1).
3. Agent presents the access token. Gateway validates iss → aud → exp → scope, resolves the principal on (iss, sub), checks the session jti against the revocation store (B1).
4. RBAC: may this principal reach this route class at all? DB-authoritative roles only (B2).
5. Entitlement: is this server visible to this principal? Same resolver that filtered tools/list (B2) - discovery and invoke cannot disagree, because they are one function.
6. Every path - REST, native MCP, portal - arrives at the single invocation chokepoint (B3).
7. Quarantine gate: is this tool approved, and is its onboarding configuration internally consistent? (B3 enforces the state, B8 set it)
8. Injection screen over arguments, from the one canonical phrase list (B3).
9. Taint check: does the caller’s effective integrity floor permit a privileged call? Marker written before anything forwards (B3).
10. Policy engine: one input document, explicit allow required; unreachable, malformed, or empty-bundle → 503 (B3).
11. Profile resolution: which named tool set does this identity have? No profile → no tools (B5).
12. Broker: exchange (RFC 8693) or decrypt a stored credential just-in-time, bound by AAD to this exact row context (B5).
13. Inject server-side into the single upstream request; re-resolve and pin the backend IP at call time; zero the buffers in finally (B5, B6).
14. Backend validates the token it received on its own boundary and returns (B5).
15. Audit writes synchronously, before the response leaves - principal and acting client separately, hashed arguments, decision and reason codes, taint state (B7).

Steps 3 through 10 are pure rejection logic and cost single-digit milliseconds. Step 12 is the only one holding plaintext, and it holds it for the duration of one HTTP request.

Build order

Build it in the order that leaves each stopping point defensible, not in the order that demos best:

1. Isolation and the edge first (B6). Backends with no host ports, egress deny-by-default. This alone, with no other block, materially reduces risk - and retrofitting it once thirty servers exist is the migration nobody funds.
2. Ingress authentication + audit (B1, B7). Identity and a record of it. You now know who did what, which is the precondition for every argument that follows.
3. The single chokepoint (B3, structural half). One function every path funnels to - before you have anything interesting to put in it. Building the chokepoint after the checks is how the second code path is born.
4. RBAC and entitlement (B2). Cheap, and closes the listing-leaks-capability gap.
5. The broker (B5). The largest single lift, and the one that removes agent-held credentials. Start with stored credentials for real backends; add RFC 8693 exchange where the IdP actually supports it.
6. Policy engine and injection screening (B3, remainder). Per-call argument policy, once the chokepoint is proven.
7. Onboarding states and vetting (B8, B4). The state machine and its quarantine gate first, then the scans that feed the approval - the states are worth having with a human reading a scan verdict by eye; the scans are worth little without a state that holds the server unreachable until someone reads them. Late, because they gate onboarding: build them before there is anything to onboard and they gate nothing but your own progress.
8. Taint floor in notify (B3), promoted to enforce before the expiry you recorded when you switched it on.

Lab, not production - the honest delta

The reference implementation is a personal open-source build that runs on one machine. It is a faithful implementation of every contract above and it is not a production deployment, so here is the delta rather than a disclaimer:

None of these change a contract. They change who you can defend the deployment against.

When this is the wrong design

The bear case, stated plainly because a blueprint without one is marketing.

The chokepoint is the cost. Every call pays validation, policy evaluation and synchronous audit. If your workload is thousands of low-value tool calls per second, this architecture is the wrong shape - you want the enforcement at a coarser boundary and sampling instead of synchronous audit, and you should say so rather than quietly making audit async, which deletes exactly the events you built it for.

One agent, one backend, one user, no secrets worth stealing? Build none of this. The design earns its complexity at the point where multiple identities meet multiple backends with credentials of differing blast radius. Below that line it is ceremony.

The standards are moving under it. DCR went deprecated inside a single spec cycle; CIMD is young; RFC 9207 is a SHOULD that is expected to become a MUST; cross-app access (ID-JAG) may make part of the broker’s downstream story obsolete in the good way. Anything here traced to an RFC will age slowly; anything traced to the MCP spec should be re-read every release.

And the honest sunset condition: if IdPs ship native audience-bound, exchange-capable, MCP-aware authorization - and the vendor matrix suggests two or three are trying - then Blocks 1 and 5 shrink to configuration and this platform becomes a thin policy-and-audit layer over someone else’s identity plane. That would be a good outcome. Blocks 3, 4, 6 and 7 do not go away in that world, because no IdP will ever mediate a tool call, vet a server’s supply chain, or keep a hostile backend off your network. Those four are the durable half. Build them like they have to outlive the other three.

Close

Eight blocks, one promise: the agent never holds a credential that opens more than one door. Authentication makes identity real and keeps one issuer visible; RBAC and entitlement decide reach; the checks pipeline judges every call at one chokepoint; vetting scans what comes in on day 1 and keeps scanning it after; profiles and the broker mint and inject narrow, short-lived authority - exchanged tokens for OAuth backends, encrypted per-user and service-account stores for everything else; isolation makes the guarantees stick against a hostile backend; audit proves it all happened the way the diagram says; and onboarding holds every server unreachable until a second human approves it against pinned evidence, which is what makes the other seven configurable at all. Each block’s minimal contract is small - a dozen fields and checks traced to RFCs - and each is load-bearing: remove any one row and a specific, named attack comes back.

The reference implementation is open at github.com/webr0ck/mcp-security-platform, and two things in it matter more than the Python. openspec/specs/ is every contract above restated as normative requirements with pass/fail scenarios - eight capabilities, 94 requirements, 323 scenarios, vendor-neutral, in the OpenSpec format so a coding agent can build against it directly. That is the design as it should be. docs/spec/ is the same system as it actually ships, gaps and incident history included. Build from the first; check yourself honestly against the second, and expect the delta - the one I published above is mine.

I write about cyber security - detection, secure architecture, and the tools I build in the open - at purplehootie.com. Views my own.

Standards referenced