Back to the guide

CodeIntegrity · White paper ·

MCP Gateway Architecture Absolutely Matters

Similar features. Different trust boundaries. Very different outcomes.

A feature list cannot tell you where trust ends

Put two MCP gateway demos next to each other. Both connect tools. Both advertise authentication, policies, logs, and a dashboard. Both can show an agent successfully calling a service. The screenshots may look interchangeable. The security properties can be radically different.

One gateway may authorize every request against the caller's identity and the target resource. Another may authenticate once, then route everything through a shared administrator credential. Both can truthfully claim to support authentication. Only a closer look tells you whose authority reaches the downstream system.

The proliferation of open-source gateways makes it easier to start experimenting. It does not make the architectural choices interchangeable. Connector count, GitHub popularity, and an impressive catalog do not establish tenant isolation, effective revocation, or coverage of a write before it happens. This guide does not depend on a count of gateway projects. It offers a way to compare what they actually enforce.

A gateway's most important output is not a successful tool call. It is a bounded delegation of authority. The system takes a request from one principal and decides whether, how, and with which credentials to act on another system. Every cache, connection pool, discovery result, and retry participates in that delegation.

The question to ask is therefore more precise than whether a product has a security feature: where does the feature act, which identity does it use, and what happens when the facts it depends on change?

This paper examines those decisions using the November 2025 MCP specification as its protocol baseline. The design recommendations and hypothetical failure scenarios are our analysis, not a ranking of particular gateway products.

First decide what the gateway is responsible for

The word gateway can describe several distinct architectures. A transport proxy forwards traffic. A tool aggregator combines multiple servers into one endpoint. A credential broker chooses or obtains credentials for downstream services. A policy enforcement point can stop an operation before forwarding it. A product may combine these roles, but they should remain explicit in its design.

Transport termination determines visibility. If a gateway does not inspect the MCP message, it cannot make a decision about the tool arguments inside it. If it only filters discovery, a client that already knows a tool name may still attempt the call. If it records a response after execution, it can report a write that occurred, but cannot prevent that write retroactively.

Map a request through five steps:

  1. Authenticate the caller. Establish the user or service identity and its tenant.
  2. Resolve the operation. Identify the configured upstream, native tool, arguments, and relevant resource.
  3. Authorize the delegation. Decide whether that principal may cause that operation through that connection.
  4. Execute within the grant. Select a credential and route that preserve the intended boundary.
  5. Record the result. Distinguish denial, attempted forwarding, upstream completion, and uncertainty.

This sequence is a reference model. An implementation may distribute it across services, but it still needs to preserve the relationships between the steps.

Ask what bypasses the sequence. Can a developer call the upstream directly with the same credentials? Can an agent reach it through a shell, SDK, or local MCP server? A gateway cannot mediate traffic that does not traverse it. Network restrictions, downstream identity policy, and endpoint controls may be needed to make gateway use an enforceable boundary.

Deployment location follows responsibility. A central gateway makes shared policy easier to operate, but concentrates availability and credential risk. A local gateway can cover workstation integrations, but requires trustworthy distribution and tamper resistance. A hybrid design needs explicit ownership when local and central decisions disagree.

Preserve identity across both sides of the connection

For HTTP transports, the MCP authorization specification describes a client acting on behalf of a resource owner and a server validating access tokens intended for that server. It requires audience validation; possession of an arbitrary bearer token is insufficient. Its HTTP authorization flow does not apply to stdio in the same way. [1]

An aggregating gateway can be a server to the incoming client and a client to an upstream MCP server. Treat those as separate trust relationships. Authenticating to the gateway does not automatically authorize the gateway to act as the user in every connected service.

The MCP security guidance explicitly rejects accepting unvalidated client tokens and passing them through to downstream APIs. [2] The architectural alternative is deliberate credential mediation: validate incoming authority, then select a separately appropriate downstream credential or supported delegation flow. Do not assume every provider supports the same token exchange mechanism.

Consider a hypothetical support agent and a finance agent. Both can authenticate to one gateway. If all downstream calls use a finance administrator account, tenant-aware logs alone do not limit what the support agent can reach. The gateway must enforce the missing resource boundary itself, or use credentials that preserve it downstream. A label attached to an overpowered request is not isolation.

Make credential selection reviewable. A connection should identify its owner, upstream service, intended audience, scope, and renewal behavior. Separate grants where users or tenants differ. Avoid placing raw credentials in logs, tool descriptions, or model-visible errors.

Revocation is the revealing test. Remove a user's grant while the gateway is running. An idle connection, refreshed token, cached allow decision, or another replica must not silently restore that access. Document how quickly new calls stop and what happens to calls already in flight. Expiration is useful, but it is not a substitute for understanding that interval.

Discovery is part of the security boundary

MCP tool definitions include a name, description, and input schema. Tool names are unique within a server, and tool annotations must be treated as untrusted unless their server is trusted. [3] An aggregator therefore has work to do beyond concatenating tool lists.

Two upstream servers can expose the same native name. Preserve a stable upstream identity alongside that name, even if the client sees a friendly alias. Route execution using that explicit mapping. Renaming a connection or parsing a display label should not change which server a policy refers to.

Discovery and execution need consistent authorization. Hiding a tool from a catalog improves the user experience and reduces accidental exposure, but it does not authorize or deny a later call. Reevaluate execution against the current grant and resolved target. A client may have cached an old tool list or constructed a request itself.

Descriptions also influence what an agent chooses to do. If upstream metadata changes, the gateway should have an intentional process for reviewing, versioning, or invalidating the affected definition. An annotation that says a tool is read-only should not become sufficient proof that it cannot change state.

Caching makes these choices concrete. A discovery cache keyed only by server URL can return one caller's catalog to another. A connection pool keyed only by provider name can associate a request with the wrong account. Even when no data leaks, stale metadata can cause the agent to act on assumptions that no longer hold.

The general rule is simple: a cache key must preserve every boundary on which the cached answer depends. Tenant, connection owner, grant version, and upstream identity may all matter. A public, identical catalog can be shared more broadly; a personalized result cannot be treated as public merely because it was expensive to fetch.

Test with two users, conflicting grants, and duplicate tool names. Then change one grant and one tool definition. The interesting result is whether the next call still reaches exactly the right server under exactly the right authority.

Stateless transport does not mean stateless security

The November 2025 Streamable HTTP specification makes session IDs optional. It also describes event replay and stream resumption, including restrictions on replaying messages across streams. [4] These are transport mechanisms. They do not define whether a business operation remains authorized.

A gateway can avoid long-lived transport sessions while still maintaining security state: grants, credential ownership, policy versions, approval records, rate limits, and revocations. Conversely, maintaining a session does not mean that the session ID should carry the authority to act.

This distinction matters when scaling beyond one process. If one replica observes a revocation and another keeps an old allow decision, a load balancer has become a policy lottery. If a reconnect restores an old session with obsolete credentials, recovering availability has also recovered access that should have ended.

Treat a pooled connection as a performance resource, not evidence of continuing permission. Reuse it only when the identity and credential boundaries permit reuse. Reauthorize requests against current policy even when the underlying transport stays open.

Retries introduce a different problem. Suppose a write succeeds upstream, but its response is lost before reaching the gateway. Retrying may repeat the effect. A JSON-RPC request identifier is not, by itself, a downstream business transaction's idempotency guarantee. Use the target service's idempotency mechanism when one exists; otherwise preserve the uncertain outcome and require reconciliation appropriate to the action.

Event replay, retrying a request, and repeating a tool's effect are different operations. A gateway should not blur them into a generic reliability feature. Nor should it claim a disconnected caller automatically canceled work that may still be running upstream.

Ask a candidate system to demonstrate a replica restart during a write, a revoked grant during a reconnect, and two users sharing an upstream host. The architecture matters most when the happy path stops being available.

Separate administration from the execution path

The control plane defines connections, permissions, and policies. The execution path applies those decisions to live calls. They can share a deployment in a small system, but their responsibilities and failure behavior should be distinguishable.

A policy editor should not be able to leave replicas interpreting half-written configuration. Publish a coherent version, validate it, and make activation observable. Record which version governed each decision. Where a credential rotation and policy change depend on one another, define the transition rather than relying on timing.

Consider an administration-service outage. An execution service may continue using a valid, bounded policy snapshot for some operations. That can be reasonable if expiration and revocation requirements permit it. A sensitive operation requiring fresh authority may need to pause. The important property is that the choice is deliberate and inspectable, rather than a hidden fallback to allowing everything.

Administrative features create their own attack surface. A user-supplied server URL can cause the gateway to make network requests. OAuth discovery adds further URLs and redirects. MCP's security guidance calls out server-side request forgery and recommends controls on destinations, redirect handling, and network egress. [2] The service that discovers integrations should not casually inherit the ability to reach cloud metadata or unrelated internal systems.

Auditing belongs in this design too. Capture the authenticated actor, tenant, connection, native tool, policy decision, credential reference, and observed result. Protect sensitive arguments and outputs. A credential reference should help an investigator identify the grant without exposing the secret itself.

An audit event should be honest about uncertainty. A timeout is not proof that nothing happened. A gateway allow decision is not proof that the upstream succeeded. Keep those distinctions intact so incident responders can reconstruct effects instead of interpreting an ambiguous green status.

Evaluate the boundary, not the demo

Use the same controlled tests for every candidate. Include a legitimate counterpart for each prohibited action so you can measure both enforcement and useful access. The scenarios below are evaluation recommendations, not claims that any particular open-source project fails them.

Identity test. Give two users different grants to the same service. Verify the downstream credential and accessible resources for each. Revoke one grant and measure when all replicas stop accepting new calls under it.

Routing test. Register two upstream servers with an identical tool name. Confirm that catalog aliases, execution routing, and policy records retain the correct upstream identity after a connection is renamed.

Discovery test. Remove a tool from a user's allowed catalog, then call it directly by name. Change a tool description and schema after discovery. Verify the documented authorization and invalidation behavior.

Isolation test. Warm caches and connection pools as one tenant, then make the same request as another. Inspect the actual response and upstream account, not only the tenant field in the gateway log.

Failure test. Interrupt the policy service and restart a replica during a controlled write. Confirm the expected fail behavior, policy version, retry behavior, and handling of an unknown upstream outcome.

Bypass test. Attempt the same operation through the permitted client path and an alternative direct path. Identify which component, if any, enforces the boundary on each route. Record uncovered paths explicitly.

Administration test. Try to register a controlled endpoint that redirects to a prohibited destination. Verify that discovery and connection setup observe the intended network restrictions, without targeting real metadata or internal services.

Measure unauthorized effects completed, revocation delay, cross-tenant exposure, incorrect routing, uncertain outcomes, and legitimate-task completion. Latency and throughput still matter, but a fast request under the wrong authority is not a successful security result.

Open source gives teams the ability to inspect and change the implementation. Use that advantage to trace the decisions that matter. Architecture determines whether authentication, policy, discovery, and logging describe the same operation under the same authority. That is why MCP gateway architecture absolutely matters.

Sources and scope

March 2026 edition. Protocol references use the November 25, 2025 MCP specification. The architectural recommendations and evaluation scenarios are CodeIntegrity analysis. This guide does not claim an exhaustive market survey, a project count, or benchmark results for any vendor.

  1. Model Context Protocol: Authorization. HTTP authorization roles, token audience validation, and transport scope.
  2. Model Context Protocol: Security Best Practices. Token passthrough, confused-deputy risks, and server-side request forgery.
  3. Model Context Protocol: Tools. Tool identity, definitions, and the trust status of annotations.
  4. Model Context Protocol: Transports. Streamable HTTP session management, stream resumption, and replay behavior.

About CodeIntegrity

CodeIntegrity focuses on controls over agent access and actions at runtime. To discuss the trust boundaries in your MCP architecture, talk to our team.