MCP host, client and server architecture
The MCP host, client and server roles as the specification defines them, both protocol revisions, and a reusable pattern with a policy gateway and approvals.
The Model Context Protocol (MCP) is an open protocol, based on JSON-RPC 2.0, that lets AI applications get context and actions from external programs in a standard way. It is not a model and not an LLM API: it defines only how context is exchanged. This page explains the host, client and server roles as the specification defines them, then sets out a reusable pattern for connecting AI hosts to Salesforce, Marketing Cloud, Data 360, Braze and custom APIs, with identity, policy, audit and human approval in the path.
The per-product adapters in this pattern are a proposed GeekMidst design; they do not exist yet. Several vendors already host their own MCP servers, listed below with the status each vendor states. GeekMidst can design and implement the pattern through MCP server development and MCP integration consulting. The one MCP server GeekMidst runs today is the public, read-only server at the /mcp endpoint on this website, which serves published website content; see the MCP integration project.
Business context
Teams want AI assistants to answer questions from CRM, marketing and data platforms, and sometimes to act on them. Without a shared pattern, each assistant gets its own credentials and each team connects its own servers, so nobody can say who can use which tool. A shared pattern gives one place to decide access, one audit trail and one approval step.
Hosts, clients and servers
An MCP host is the AI application, such as a chat app, an IDE or an agent. It creates one MCP client per MCP server, and each client keeps a dedicated connection to its server. A server exposes three primitives: tools (functions the model can call), resources (data addressed by URIs) and prompts (reusable templates the user chooses).
Servers run over two transports. stdio is for a local process; it takes credentials from the environment, and the authorisation spec says it should not use the HTTP OAuth flow. Streamable HTTP is for remote servers: one endpoint, each client message a new POST, and a response as plain JSON or an SSE stream. Servers must validate the Origin header and answer 403 when it is invalid.
Protocol revisions
| Revision | How a client connects | What a server must handle |
|---|---|---|
| 2025-11-25 (legacy) | initialize handshake, then notifications/initialized | Optional MCP-Session-Id; MCP-Protocol-Version header on later requests |
| 2026-07-28 (current) | No handshake; every request carries _meta with protocol version and client capabilities | server/discover; Mcp-Method and Mcp-Name headers; ttlMs and cacheScope on list and resources/read results; no sessions |
A server may serve both revisions on one endpoint: an initialize request selects legacy behaviour, and requests carrying _meta are served statelessly. The TypeScript SDK v2 client defaults to legacy mode and the Python client probes server/discover first, so supporting the legacy handshake remains the safe baseline. That is an inference from SDK defaults, not something the spec states.
Reusable MCP pattern: host to product APIs
Reference architecture: a reusable pattern, not a live client integration
Select a component to see what it is responsible for and how data moves to and from it.
Components and data flows (text version)
| Component | Type | Responsibility |
|---|---|---|
| Usernamed person | People | The person asking questions or requesting actions, signed in with their own identity. |
| AI host applicationchat app, IDE or agent | AI and agents | The AI application. It chooses tools and creates one MCP client per server it connects to. |
| MCP clientsone per server | AI and agents | Protocol clients inside the host. Each keeps a dedicated connection and negotiates the protocol revision. |
| Human approvalsensitive actions | People | A named person confirms write or sensitive tool calls after seeing what will change. |
| Identity and policy gatewayproposed | Identity, policy and governance | Authenticates the user, applies tool allowlists, read/write rules and rate limits, and obtains a separate token for each downstream server. |
| Audit log and monitoringevery call | Identity, policy and governance | Records who called which tool, the decision, outcome and timing, and raises alerts on failures. |
| MCP server registryinternal allowlist | Integration layer | Your list of approved servers, tool versions and owners. Not the public MCP Registry, which is in preview. |
| Vendor-hosted MCP serversSalesforce, MCE, Data 360, Braze | External or custom system | Servers run by the vendor, with the vendor's status, licensing and permissions. |
| GeekMidst adaptersproposed, not built | Integration layer | Proposed per-product servers for Salesforce, Marketing Cloud, Data 360, Braze or a custom API, where no vendor server fits. |
| Salesforce APIsREST, Apex, Flow | Salesforce product | Salesforce platform APIs, called within the signed-in user's permissions. |
| Marketing Cloud APIsEngagement | Engagement platform | Marketing Cloud Engagement REST and SOAP APIs. |
| Data 360 APIsquery, segments | Data and analytics | Data 360 query and Connect APIs, which count toward their own limits. |
| Braze REST APIendpoint-scoped keys | Engagement platform | Braze REST endpoints with per-endpoint permissions and documented rate limits. |
| Custom APIsyour services | External or custom system | Internal services exposed through narrow, documented tools. |
Data flows
- User → AI host application: question or request. The user's request, made with their own identity.
- AI host application → MCP clients: tool selection. The host picks a tool; the client sends tools/call to the gateway endpoint.
- MCP clients → Identity and policy gateway: MCP requests. Every request carries a bearer token issued for the gateway. Invalid or expired tokens get 401.
- Identity and policy gateway → Human approval: approval request. For write or sensitive tools, the gateway pauses the call and asks a named person to confirm.
- Human approval → Identity and policy gateway: decision. Approved calls continue; rejected calls return a tool error the model can explain.
- Identity and policy gateway → Audit log and monitoring: call record. Each call, decision and outcome is logged without storing secrets.
- Identity and policy gateway → MCP server registry: server lookup. The gateway checks that the server and tool are approved and which version is current.
- Identity and policy gateway → Vendor-hosted MCP servers: vendor server calls. Uses a token issued for that vendor server, never the client's token. Braze allowlists client domains and admins approve redirect URIs, so confirm each vendor accepts the gateway as a client.
- Identity and policy gateway → GeekMidst adapters: adapter calls. Calls to proposed adapters, which validate inputs against their schemas.
- Vendor-hosted MCP servers → Salesforce APIs: Salesforce. Salesforce Hosted MCP Servers run each call as the authenticated user.
- Vendor-hosted MCP servers → Marketing Cloud APIs: Marketing Cloud. The Engagement MCP Server acts within package scopes and the user's permissions.
- Vendor-hosted MCP servers → Data 360 APIs: Data 360. The Data 360 MCP Server counts toward Connect API limits and Flex Credits.
- Vendor-hosted MCP servers → Braze REST API: Braze. The Braze MCP server uses OAuth with the user's Braze login and exposes no user-level PII tools.
- GeekMidst adapters → Salesforce APIs: scoped calls. Adapters hold server-side credentials scoped to their tools only.
- GeekMidst adapters → Braze REST API: scoped calls. One Braze key per adapter purpose; 429 responses are backed off using rate-limit headers.
- GeekMidst adapters → Custom APIs: custom calls. Narrow, parameterised calls to your own services with timeouts.
Component responsibilities
| Component | Responsible for | Status |
|---|---|---|
| AI host and MCP clients | Choosing tools; one client per server | Your chosen host |
| Identity and policy gateway | Authentication, allowlists, read/write rules, rate limits, per-server tokens | Proposed pattern |
| Human approval | Confirming write or sensitive calls | Proposed pattern |
| Server registry | Approved servers, versions, owners | Proposed pattern |
| Vendor-hosted servers | Vendor tools under vendor licensing | Vendor's stated status (see below) |
| GeekMidst adapters | Tools where no vendor server fits | Proposed; not built |
| Audit and monitoring | Who did what, when, with what result | Proposed pattern |
Vendor-hosted MCP servers and their stated status
| Server | Publisher | Status as stated by the vendor |
|---|---|---|
| Salesforce Hosted MCP Servers | Salesforce | GA 29 April 2026; Enterprise Edition and above; intended for customers with Flex Credits |
| Headless 360 MCP Server | Salesforce | Beta |
| Salesforce DX MCP Server | Salesforce | Local server; whole-server GA not confirmed |
| Marketing Cloud Engagement MCP Server | Salesforce | GA 2 June 2026 |
| Data 360 MCP Server | Salesforce | GA per Salesforce news, 19 August 2026 |
| Braze MCP server | Braze | Generally available per a Braze article dated 23 July 2026 |
| Hosted Tableau MCP | Tableau | Status not confirmed; Tableau's own page conflicts |
Data flow, step by step
- The user asks the host a question or requests an action.
- The host chooses a tool, and its client sends
tools/callto the gateway. - The gateway authenticates the user's token and checks the allowlist, read/write rules and rate limits.
- Sensitive calls wait for approval from a named person.
- The gateway routes the call to a vendor-hosted server or an adapter, with a token issued for that server.
- The product API runs within the user's permissions, and the result returns to the host.
- The call is logged with its decision, outcome and timing.
Trust boundaries and authentication
There are three boundaries: the host environment, your gateway and the vendor platforms. The spec forbids token passthrough: an MCP server must not accept tokens that were not issued for it. A gateway that proxies to other servers therefore holds its own downstream tokens and must get per-client consent before forwarding to a third-party authorisation server. Tool annotations such as readOnlyHint are hints, and clients must treat them as untrusted unless the server is trusted. The details are on our MCP security architecture page.
Failure scenarios and how to handle them
| Failure | Effect | How to handle it |
|---|---|---|
| Protocol revision mismatch | 400 with an unsupported-version error | Support the legacy handshake and 2026-07-28 on one endpoint |
| Token invalid or expired | 401 | Client refreshes or re-authorises; never fall back to shared keys |
| Tool input invalid | Tool execution error with isError | Validate against the input schema and return a clear message |
| Vendor server down or slow | Tool unavailable | Timeouts, a fallback message and an alert |
| Rate limit reached | Calls refused | Per-user limits at the gateway; respect vendor limits |
| Instructions hidden in returned data | Model misled | Treat tool output as data; confirm writes with a person |
Operational monitoring
Track calls per tool and user, error rates, authentication failures, approval decisions and latency. Alert on spikes in write requests or denials, and review the allowlist and approvals monthly.
Alternative approaches and trade-offs
Connect hosts straight to vendor servers: fastest to start, but each host is governed separately. Use a gateway: one place for policy and audit, at the cost of a component to run; Salesforce recommends an MCP gateway such as MuleSoft AI Gateway for cross-vendor governance. Skip MCP and call APIs directly from your own app when the workflow is fixed; see MCP vs direct API integration.
Implementation checklist
- 01
List use cases
Questions and actions the AI should support, per team
- 02
Check vendor servers first
Status, licensing and permissions for each product
- 03
Decide read and write scope
Read-only first; writes only with approval
- 04
Choose the gateway
Build, buy or use a platform option
- 05
Register servers
Approved servers, tools, versions and owners
- 06
Design adapters where needed
Narrow tools with input schemas, tested in a sandbox
- 07
Support both protocol revisions
Legacy handshake plus 2026-07-28
- 08
Monitor and review
Calls, errors, approvals and allowlist reviews
Related services and solutions
MCP server development
Designing and building MCP servers
→MCP integration consulting
Connecting AI hosts to business systems
→MCP architecture guide
A longer guide to the same topic
→MCP security architecture
Authorisation and tool controls
→Salesforce MCP integration
Salesforce-specific design
→What is MCP for Salesforce teams
A plain-language introduction
→Questions we hear
Do GeekMidst MCP adapters for Salesforce or Braze exist?
Should we use a vendor's MCP server or build our own?
Which protocol revision should we support?
Is MCP a security layer?
Sources
- https://modelcontextprotocol.io/docs/learn/architecture
- https://modelcontextprotocol.io/specification/2026-07-28/changelog
- https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http
- https://developer.salesforce.com/blogs/2026/04/salesforce-hosted-mcp-servers-are-now-generally-available
- https://braze.com/docs/developer_guide/mcp_server/
Plan your MCP architecture
Tell us which AI hosts and products you want to connect. We can propose a pattern with vendor servers, adapters, policy and approvals.
