Skip to content

[Access] Add MCP portal request flow architecture diagram#31011

Draft
kennyj42 wants to merge 2 commits into
cloudflare:productionfrom
kennyj42:kjohnson/mcp-portal-architecture-diagram
Draft

[Access] Add MCP portal request flow architecture diagram#31011
kennyj42 wants to merge 2 commits into
cloudflare:productionfrom
kennyj42:kjohnson/mcp-portal-architecture-diagram

Conversation

@kennyj42

Copy link
Copy Markdown
Collaborator

What this PR does

Adds an SVG architecture diagram and a new 'How it works' section to the MCP portals page. The diagram shows:

  • MCP client connecting to the portal
  • Cloudflare Access handling authentication (JWT validation, policy evaluation, OAuth 2.0, Managed OAuth)
  • MCP server portal handling session management, tool namespacing, credential routing, server toggling, context optimization, built-in tools, code mode sandbox, and transport detection
  • Gateway (optional, dashed) handling HTTP logging, DLP inspection, policy enforcement, and egress IP
  • Upstream MCP servers in three auth flavors: OAuth, unauthenticated, bearer
  • Background sync path showing direct connection to upstream servers (bypasses Gateway, ~2h interval)
  • A legend distinguishing request flow, optional Gateway path, and background sync
  • Numbered step labels (Connect, Authenticate, Session created, Tool call proxied, Upstream request)

The accompanying text walks through the 5-step flow and calls out that background sync does not route through Gateway.

Why

No architecture diagram existed. Internal engineers needed 30+ message threads to explain the CNAME/routing model. This diagram gives users a mental model of how the portal proxies requests, where auth happens, and what the optional Gateway path adds.

@github-actions

github-actions Bot commented Jun 6, 2026

Copy link
Copy Markdown
Contributor

Hey there, we've marked this pull request as stale because there's no recent activity on it. This label helps us identify PRs that might need updates (or to be closed out by our team if no longer relevant).

@github-actions github-actions Bot added the stale label Jun 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants