%% Governed MCP connection: reference architecture
%% Reference architecture: a reusable pattern, not a live client integration
flowchart TB
  subgraph z0["Customer-controlled: host, gateway, adapter"]
    host["MCP host<br/>IDE, chat app or agent platform"]
    gateway["MCP gateway or registry<br/>allowlists, policies, logs"]
    adapter["Custom MCP adapter<br/>proposed, only for gaps"]
  end
  subgraph z1["Vendor-operated platforms"]
    authz["Authorization server<br/>vendor OAuth, per user"]
    sfmcp["Salesforce Hosted MCP<br/>vendor-run, GA 29 Apr 2026"]
    brazemcp["Braze MCP server<br/>vendor-run, remote"]
    sforg["Salesforce org<br/>CRUD, FLS and sharing enforced"]
    brazews["Braze workspace<br/>non-PII data via MCP"]
  end
  user["Business user or developer<br/>works in an AI client"]
  other["Other approved APIs<br/>called by the adapter only"]
  user -->|"prompts and approvals"| host
  host -.->|"OAuth with PKCE"| authz
  host -->|"MCP requests"| gateway
  gateway -->|"allowlisted tool calls"| sfmcp
  gateway -->|"allowlisted tool calls"| brazemcp
  gateway -->|"allowlisted tool calls"| adapter
  sfmcp -->|"runs as the user"| sforg
  brazemcp -->|"dashboard permissions"| brazews
  adapter -->|"scoped API calls"| other
  classDef salesforce stroke:#125BD8,fill:#e8f0fd
  class sfmcp,sforg salesforce
  classDef engagement stroke:#5747AF,fill:#efedfa
  class brazemcp,brazews engagement
  classDef ai stroke:#5747AF,fill:#f6f4fd
  class host ai
  classDef integration stroke:#334155,fill:#eef2f6
  class adapter integration
  classDef security stroke:#1f2937,fill:#f3f4f6
  class authz,gateway security
  classDef external stroke:#64748b,fill:#ffffff
  class other external
  classDef people stroke:#125BD8,fill:#ffffff
  class user people