Forem: Sitaram Srivatsavai

Build Your First MCP Server in 30 Minutes: A Practical Guide for Salesforce Developers

Sitaram Srivatsavai — Sun, 05 Apr 2026 12:50:02 +0000

Model Context Protocol (MCP) is one of those technologies that sounds abstract until you build something with it. Then it clicks: it's a standardized way for AI agents to call external tools, with a governance layer that lets you control exactly which tools the agent can access.

If you're a Salesforce developer working with Agentforce, MCP matters because it replaces one-off REST integrations with a protocol that's consistent across tools. You register a server, pick the tools you want, and they show up as agent actions — managed the same way as your Flows and Apex actions.

In this guide, I'll walk through building a working MCP server from scratch, connecting it to Agentforce, and explaining the governance patterns that make it production-ready. The server itself is pure TypeScript — nothing Salesforce-specific — so the skills transfer to any MCP-compatible agent platform.

What MCP Actually Is (In 60 Seconds)

MCP is an open protocol — originally created by Anthropic — that defines how AI agents discover and call external tools. It has two sides:

The server advertises a list of tools, each with a name, description, and JSON schema for inputs and outputs. It handles execution when a tool is called.

The client (your agent platform — Agentforce, Claude, LangChain, etc.) discovers available tools, presents them to the LLM as callable actions, and routes tool calls to the server.

The protocol handles discovery, invocation, and response formatting. You focus on the tool logic.

Why not just build a REST API? You can — and for simple integrations, you probably should. MCP adds value when you have multiple tools that an AI agent selects between dynamically, or when you want a governance layer (allowlists) between the tools and the agent. For a single-purpose integration, REST is simpler. For a tool ecosystem, MCP scales better.

What We're Building

A mock "payer policy lookup" MCP server with three tools:

lookup_formulary_coverage — Given a payer, plan, and drug, return coverage status and formulary tier
get_pa_requirements — Return whether prior authorization is required and the criteria
get_utilization_rules — Return step therapy and quantity limit rules

These simulate the kind of external data an AI agent in Life Sciences would need during benefits verification. In production, they'd call a real payer API or clearinghouse. For this tutorial, they're backed by a JSON file.

Step 1: Set Up the Project

mkdir mcp-payer-server && cd mcp-payer-server
npm init -y
npm install @modelcontextprotocol/sdk zod

Create a tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}

Step 2: Create the Mock Data

Create src/payer_rules.json:

{
  "AcmeHealth|Gold Plus|RX-OMNI-10mg": {
    "coverage_status": "Covered",
    "formulary_tier": "Tier 4",
    "prior_auth_required": true,
    "criteria_summary": "Confirm labeled indication. Document prior therapy failure. Baseline labs required.",
    "step_therapy": "Must try Drug A before RX-OMNI",
    "quantity_limit": "30 tablets / 30 days",
    "restrictions": "Specialty pharmacy required"
  },
  "BlueCross|Standard PPO|CardioMax-25mg": {
    "coverage_status": "Covered",
    "formulary_tier": "Tier 2",
    "prior_auth_required": false,
    "criteria_summary": "No prior authorization required for Tier 2 formulary drugs.",
    "step_therapy": "None",
    "quantity_limit": "90 tablets / 90 days",
    "restrictions": "None"
  },
  "MediPlan|Bronze Essential|RX-OMNI-10mg": {
    "coverage_status": "Not Covered",
    "formulary_tier": "Non-formulary",
    "prior_auth_required": false,
    "criteria_summary": "Drug not on formulary. Patient may appeal for exception.",
    "step_therapy": "N/A",
    "quantity_limit": "N/A",
    "restrictions": "Non-formulary — appeal process available"
  }
}

The key format is payer|plan|drug. Three records give you enough to demo a covered/PA-required case, a clean coverage case, and a not-covered case.

Step 3: Build the MCP Server

Create src/server.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import fs from "node:fs";
import path from "node:path";

// Load mock data
const rules: Record<string, any> = JSON.parse(
  fs.readFileSync(
    path.join(import.meta.dirname, "payer_rules.json"),
    "utf-8"
  )
);

function key(payer: string, plan: string, drug: string): string {
  return `${payer}|${plan}|${drug}`;
}

// Create server
const server = new McpServer({
  name: "payer-policy-server",
  version: "1.0.0",
});

// Tool 1: Formulary coverage lookup
server.tool(
  "lookup_formulary_coverage",
  "Check whether a drug is covered under a specific payer and plan. Returns coverage status, formulary tier, and restrictions.",
  {
    payer: z.string().describe("Payer organization name"),
    plan: z.string().describe("Plan name"),
    drug: z.string().describe("Drug name and strength"),
  },
  async ({ payer, plan, drug }) => {
    const row = rules[key(payer, plan, drug)];
    const result = row
      ? {
          coverage_status: row.coverage_status,
          formulary_tier: row.formulary_tier,
          restrictions: row.restrictions,
        }
      : {
          coverage_status: "Unknown",
          formulary_tier: "Unknown",
          restrictions: "No matching plan/drug rule found.",
        };

    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    };
  }
);

// Tool 2: Prior authorization requirements
server.tool(
  "get_pa_requirements",
  "Check whether prior authorization is required and return the criteria summary.",
  {
    payer: z.string().describe("Payer organization name"),
    plan: z.string().describe("Plan name"),
    drug: z.string().describe("Drug name and strength"),
  },
  async ({ payer, plan, drug }) => {
    const row = rules[key(payer, plan, drug)];
    const result = {
      prior_auth_required: row?.prior_auth_required ?? false,
      criteria_summary:
        row?.criteria_summary ?? "No PA criteria found for this combination.",
    };

    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    };
  }
);

// Tool 3: Utilization management rules
server.tool(
  "get_utilization_rules",
  "Return step therapy requirements and quantity limits for a drug under a specific plan.",
  {
    payer: z.string().describe("Payer organization name"),
    plan: z.string().describe("Plan name"),
    drug: z.string().describe("Drug name and strength"),
  },
  async ({ payer, plan, drug }) => {
    const row = rules[key(payer, plan, drug)];
    const result = {
      step_therapy: row?.step_therapy ?? "None documented.",
      quantity_limit: row?.quantity_limit ?? "None documented.",
    };

    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    };
  }
);

// Start server
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Payer Policy MCP Server running on stdio");
}

main().catch(console.error);

Build and test it:

npx tsc
node dist/server.js

That's it. You have a working MCP server with three tools. Each tool has a name, a description (the LLM reads this to decide when to use it), typed input parameters via Zod, and a handler that returns structured JSON.

Step 4: Connect to Agentforce

This is the Salesforce-specific part. If you're using a different MCP client (Claude Desktop, LangChain, Cursor), skip to the next section — the server is the same regardless of client.

In Salesforce Setup:

Register the MCP server. Navigate to the MCP server setup, add a new server, and provide the connection details (URL if hosted remotely, or the stdio command if running locally during development).
Allowlist your tools. This is the governance step. The server exposes three tools, and you explicitly select which ones the agent can use. If you only want the agent to check coverage but not utilization rules, you allowlist lookup_formulary_coverage and get_pa_requirements, and leave get_utilization_rules off the list.
Tools appear in the Asset Library. Each allowlisted tool becomes an action, managed alongside your Flow actions, Apex actions, and Prompt Template actions. Same governance model, same testing approach.
Add to an agent topic. Open your agent in Agentforce Builder, navigate to the relevant topic, and add the MCP actions from the Asset Library. They chain with your other actions like any other step.
Test in Plan Canvas. Run a test prompt and watch the agent discover the tools, select the right one based on the user's request, pass the parameters, and process the response. Plan Canvas shows the full reasoning trace.

Step 5: Test Without Agentforce (MCP Inspector)

If you don't have Agentforce MCP Support access yet, or you just want to test the server independently, use the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/server.js

This opens a browser UI where you can see the tools list, call each tool with test inputs, and inspect the responses. It's the fastest way to validate your server before connecting it to any agent platform.

Why Allowlists Matter More Than You Think

The allowlist isn't just a configuration step — it's the governance mechanism that makes MCP production-ready.

Consider this scenario: your MCP server exposes 10 tools because it serves multiple agent use cases. One of those tools writes data back to an external system. Without an allowlist, every agent that connects to this server can invoke every tool — including the write operation.

With allowlists, you control this per agent topic:

Benefits verification agent gets: lookup_formulary_coverage, get_pa_requirements, get_utilization_rules (read-only)
Enrollment agent gets: lookup_formulary_coverage, submit_pa_request (read + write, with human confirmation gate)
Reporting agent gets: get_utilization_rules only

The principle: give each agent the minimum set of tools it needs. Smaller toolset = more predictable behavior = fewer surprises in production. This matters especially in regulated industries where every tool invocation is potentially auditable, but it's good practice regardless of domain.

Adapting for Other MCP Clients

The server you just built works with any MCP-compatible client. Here are two common alternatives to Agentforce:

Claude Desktop: Add the server to your claude_desktop_config.json:

{
  "mcpServers": {
    "payer-policy": {
      "command": "node",
      "args": ["/path/to/dist/server.js"]
    }
  }
}

Claude will discover the tools automatically and use them when relevant to the conversation.

VS Code (via Copilot or Cline): Add to .vscode/mcp.json:

{
  "servers": {
    "payer-policy": {
      "command": "node",
      "args": ["dist/server.js"]
    }
  }
}

The server code doesn't change. The tool contracts don't change. Only the client configuration changes. That's the whole point of a protocol.

Deploying Beyond Local Development

For a POC, running the server locally is fine. For production or shared demos, you need to host it somewhere accessible. Heroku is the common choice for Salesforce-connected MCP servers (Salesforce explicitly supports this via AppLink), but any Node.js host works — AWS Lambda, Railway, Fly.io, a plain VM.

The key deployment consideration: if you're switching from stdio transport (local) to HTTP/SSE transport (remote), you'll need to swap the transport layer in your server code. The tool logic stays identical.

What You've Built

In about 30 minutes, you've built:

A working MCP server with three tools, typed inputs, and structured JSON outputs
Mock data that covers three test scenarios (covered, not covered, PA required)
A connection path to Agentforce (or Claude, or VS Code)
A governance model based on allowlists that controls which tools each agent can access

The pattern scales. When you need a fourth tool — maybe check_appeal_status or get_copay_accumulator — you add another server.tool() block with its schema and handler. The protocol handles discovery and invocation. You focus on the logic.

And when the mock data needs to become real, you replace the JSON file reads with actual API calls to your payer system or clearinghouse. The tool contracts (names, inputs, outputs) stay the same, so nothing in your agent configuration breaks.

That's what a good integration protocol buys you: the ability to evolve the implementation without changing the interface.

Structured Outputs Are the Contract Your AI Agent Is Missing

Sitaram Srivatsavai — Thu, 26 Mar 2026 23:47:31 +0000

Free-text agent responses look great in demos. They fall apart the moment you try to automate anything downstream. Here's the pattern that fixes it.

Your AI agent just summarized a payer's response to a benefits verification request. The output reads beautifully:

"The patient's coverage appears to be active under the Gold Plus plan. Prior authorization is likely required based on the payer's language, though this isn't entirely clear. The copay seems to be around $50-75, and there may be a quantity limit of 30 tablets per month."

Now try writing code that processes that. Does "appears to be active" mean coverage is confirmed? Is prior auth required or not? What's the copay — $50 or $75? And good luck extracting "30 tablets per month" reliably when the next response says "one month supply" or "qty limit: 30 units."

This is the problem that structured outputs solve. And once I started treating them as the contract between the LLM and the rest of my system, every other design decision got easier.

The Problem: Beautiful Text, Useless Automation

I've built AI agents for regulated workflows in Life Sciences — benefits verification, clinical trial site selection, medical inquiry response. In every case, the agent's output needed to drive downstream automation: update a record's status, create follow-up tasks, route exceptions to the right person, trigger the next step in a workflow.

My first implementations all made the same mistake. I let the LLM return natural language summaries and then tried to parse them. Sometimes I wrote regex. Sometimes I added a second LLM call to "extract the fields." Sometimes I just gave up and had a human re-read the summary and fill in the fields manually.

Every approach was fragile because I was depending on the LLM being consistent in how it phrases things. And consistency is exactly what LLMs don't guarantee.

The Fix: Define a Schema, Enforce It in the Prompt

A structured output is a JSON object with a defined schema that the LLM must conform to. Instead of asking "summarize this payer response," you ask "extract the following fields from this payer response and return them as JSON."

Here's what the output contract looks like for a benefits verification summary:

{
  "coverageConfirmed": true,
  "priorAuthRequired": false,
  "copayNotes": "$50 copay per fill",
  "deductibleNotes": "$500 annual, not yet met",
  "limitationsNotes": "Specialty pharmacy required",
  "missingInfo": ["Effective date not stated"],
  "confidence": 82
}

Every field has a type. Every field has a purpose. And the downstream logic is trivial:

// This is the entire routing logic. No parsing. No interpretation.
if (summary.missingInfo.length === 0 && summary.confidence >= 75) {
  status = "Verified";
} else {
  status = "Needs Follow-up";
  for (const item of summary.missingInfo) {
    createTask(`Follow up: ${item}`, recordId);
  }
}

Compare that to trying to extract the same decisions from a paragraph of prose. The structured output turned a fragile NLP problem into a simple conditional.

How to Get the LLM to Comply

The schema alone isn't enough — you need to tell the LLM exactly what you expect. The prompt template has three parts:

1. Role and constraints:

You are a benefits verification analyst. Extract structured data
from the payer response below. Never invent information that isn't
in the response. If a field cannot be determined, use null for
booleans, "Not stated" for strings, and add the missing item to
the missingInfo array.

2. Context (merge fields from your system):

Patient: Jane Doe
Plan: AcmeHealth Gold Plus
Drug: RX-OMNI 10mg
Payer response: [raw text pasted or ingested here]

3. Output schema with field descriptions:

Return ONLY a JSON object matching this schema:
{
  "coverageConfirmed": boolean — is coverage active for this drug/plan?,
  "priorAuthRequired": boolean — does the payer require prior auth?,
  "copayNotes": string — copay amount and terms, or "Not stated",
  "deductibleNotes": string — deductible details, or "Not stated",
  "limitationsNotes": string — quantity limits, step therapy, etc.,
  "missingInfo": [string] — list of fields that couldn't be determined,
  "confidence": number 0-100 — how complete/clear was the payer response?
}

The field descriptions inside the schema are doing heavy lifting. They tell the LLM what each field means, what the valid values are, and what to do when information is missing. Without them, you get inconsistent interpretations — one run puts copay info in limitationsNotes, the next puts it in copayNotes.

If you're using a platform that supports structured output enforcement natively (OpenAI's response_format, Salesforce's Prompt Builder structured outputs), use it. If not, the prompt-based approach works well as long as you validate the JSON before processing it.

Three Domains, Same Pattern

The schema changes, but the pattern is identical across every use case I've built.

Clinical trial site feasibility:

{
  "enrollmentCapacity": "15-20 patients/year",
  "therapeuticExperience": "3 prior Phase III oncology trials",
  "regulatoryReadiness": "IRB approved, ethics committee pending",
  "riskFlags": ["Ethics committee approval pending"],
  "overallScore": 72,
  "recommendation": "Conditionally activate"
}

The riskFlags array drives automatic task creation — one task per flag. The overallScore drives routing: 80+ with no flags goes to "Activation Ready," 60-79 goes to "Under Review," below 60 goes to "On Hold." No human reads a paragraph and decides what to do. The schema decides.

Medical inquiry response:

{
  "answer": "Based on the Phase III LIBERTY trial...",
  "confidence": "high",
  "sourceDocs": ["DOC-2024-001", "DOC-2024-047"],
  "escalateFlag": false,
  "nextBestAction": "send_response"
}

The nextBestAction field is the routing mechanism. If the confidence is low or escalateFlag is true, the workflow opens a collaborative review instead of queuing the response for send. The sourceDocs array makes the response auditable — a reviewer can verify that the answer is grounded in approved content.

The Audit Advantage

Structured outputs give you something free-text summaries never can: a complete, machine-readable audit trail.

Every time my agent runs, I store three things on the record:

AI_Summary_JSON__c  = raw JSON output (the full structured response)
AI_Last_Run_By__c   = the user who triggered the agent
AI_Last_Run_At__c   = timestamp

Six months from now, when compliance asks "why was this case marked as Verified?", I can show them the exact JSON the agent produced, with the exact confidence score and the exact fields it extracted. I can show who triggered it and when. Try doing that with a paragraph of prose that was copy-pasted into a notes field.

In regulated industries — Life Sciences, healthcare, financial services — this isn't a nice-to-have. It's the difference between "we can demonstrate what happened" and "we think the AI said it was fine."

When NOT to Use Structured Outputs

Structured outputs are the right pattern when the agent's output drives automation. They're the wrong pattern when:

The user is having a conversation and wants a natural language response
The task is creative or exploratory (brainstorming, writing, ideation)
The output is the final product, not an intermediate step in a workflow

If a human is the consumer of the output, natural language is fine. If a system is the consumer, demand a schema.

Start With the Schema

If I could go back and give myself one piece of advice before building my first AI agent, it would be this: design the output schema before you write a single prompt.

The schema forces you to answer the hard questions early. What fields does the downstream system need? What are the valid values? What happens when information is missing? What score threshold triggers which action?

Every prompt you write, every test you create, every piece of routing logic you build — all of it flows from the schema. It's the contract between the AI and the rest of your system. Get it right first, and everything downstream gets simpler.

Get it wrong — or skip it and use free text — and you'll spend the next six months writing parsers, debugging inconsistent extractions, and explaining to stakeholders why the agent "sometimes gets it right."

Define the contract. Enforce it. Version it. Your future self will thank you.

Real-Time Updates in Salesforce Mobile Apps: A Look at Push Notifications and the Mobile SDK

Sitaram Srivatsavai — Fri, 26 Dec 2025 00:03:03 +0000

Imagine a field representative updating an Interaction from a lightning record page on their laptop just before heading out. The update saves to Salesforce, but the iPad app they use in the car is offline-first and still shows stale data. The rep opens the app, expects to see their latest changes, and instead sees yesterday’s state. They now have to run a full sync, which can be slow and bandwidth-heavy, just to retrieve a single updated record.

This is the real problem this article aims to address.

Traditional Salesforce Mobile SDK apps rely heavily on pull-based sync: the device periodically calls REST APIs and applies filters (territory, briefcase, etc.) to refresh local data. This works, but it means:

The device doesn’t know when something changed in Salesforce.
You either poll aggressively (wasting battery and bandwidth), or accept stale data until the next sync.

In this article, we will:

Look at how Salesforce push notifications and the Mobile SDK fit together.
Show how to configure a connected app and iOS client to receive push notifications.
Demonstrate how to send targeted push notifications to specific users from Apex.
Show how to handle silent push notifications in the mobile app to enable near-real-time, selective sync.
Conclude with design trade-offs and when this pattern is appropriate.

This article focuses on behavior and design, not on every detail of every configuration screen.

Two Ways to Use Push in a Mobile App

From a mobile client’s point of view, Salesforce push notifications are just APNs notifications with a JSON payload. How you use them depends on the behavior you want.

Visible Notifications (Alerts, Banners, Sounds)

The default pattern people think of is a visible notification:

APNs payload includes an aps.alert and possibly a sound.
iOS shows a banner, plays a sound, and increments the badge count.
The app can handle taps to navigate to a screen.

This is ideal for:

Approvals and tasks (“You have a new approval request”).
Time-critical alerts (“Appointment starting soon”).

It is not ideal when:

You have many record changes.
You only care about refreshing data silently, not interrupting the user.

Silent Notifications (content-available)
A silent notification is one that:

Uses aps.content-available = 1.
Does not specify an alert, sound, or badge.
Wake your app in the background so it can run code (briefly) without showing UI.

For an offline-first Salesforce app, this is the interesting case:

Salesforce sends a silent push saying “record X changed”.
iOS wakes the app.
The app fetches just record X from Salesforce and updates its local store.
The user sees up-to-date data the next time they open the app, without having seen any banners.

In the rest of the article, we focus on this pattern: using silent push as a sideband trigger for selective sync.

Step 1: Configure Push on the Salesforce Side

To send push notifications from Salesforce to a Mobile SDK app, you need:

A Connected App representing the iOS app.
APNs credentials for that app (Auth Key or certificate).
Push is enabled on the connected app.

At a high level:

In the Apple Developer portal:

Create an App ID with your bundle identifier (e.g. com.company.agent.ipad).
Enable Push Notifications for that App ID.
Create an APNs Auth Key (.p8) with APNs enabled.
Note the Key ID and Team ID.

In Salesforce Setup:

Open your Connected App (used by the Mobile SDK).
In the iOS push configuration: -- Upload the .p8 as Signing Key. -- Enter the Key Identifier and Team Identifier. -- Set Bundle ID to match the iOS app’s bundle id exactly. -- Choose the correct environment (Sandbox for dev builds).

Save the connected app and verify there are no errors.

Once configured correctly, Salesforce can call APNs on behalf of this app. If you saw errors like “provider token is not valid” or “pushing to this topic is not allowed” during setup, they almost always traced back to mismatched Team ID / bundle id / APNs key.

Step 2: Register Devices with the Salesforce Mobile SDK

When you run the iOS app on a real device, the app must:

Ask the user for notification permission.
Register with APNs to obtain a device token.
Register that token with Salesforce through the Mobile SDK.

A simplified pattern looks like this:

import UserNotifications
import SalesforceSDKCore

@main
class AppDelegate: UIResponder, UIApplicationDelegate, UNUserNotificationCenterDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        UNUserNotificationCenter.current().delegate = self
        registerForRemotePushNotifications()
        return true
    }

    private func registerForRemotePushNotifications() {
        let center = UNUserNotificationCenter.current()
        center.requestAuthorization(options: [.alert, .sound, .badge]) { granted, error in
            if granted {
                DispatchQueue.main.async {
                    UIApplication.shared.registerForRemoteNotifications()
                }
            } else {
                // Log or handle denial
            }
        }
    }

    func application(
        _ application: UIApplication,
        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
    ) {
        // Forward the token to Salesforce Mobile SDK
        SFPushNotificationManager.sharedInstance()
            .didRegisterForRemoteNotifications(withDeviceToken: deviceToken)
    }
}

Once this runs after a successful Mobile SDK login, Salesforce creates a MobilePushServiceDevice record for that user + connected app + device. You can verify this with a simple SOQL query, as you already do in your setup docs.

Step 3: Send a Test Push to a Specific User

With the connected app and registration in place, you can send a targeted push from Apex by specifying:

The connected app name.
The user Id (or multiple user Ids).
The JSON payload.

A basic visible test (used during setup) looked like:

String appName = 'Real_time_Sync'; // Connected App API name
String userId  = 'USER_SALESFORCE_ID';    // Test user Id

Messaging.PushNotification msg = new Messaging.PushNotification();

Map<String, Object> payload = Messaging.PushNotificationPayload.apple(
    'Test Push Notification',
    'default',
    1,
    new Map<String, Object>{ 'type' => 'TEST', 'message' => 'Hello from Salesforce' }
);

msg.setPayload(payload);

Set<String> users = new Set<String>{ userId };

try {
    msg.send(appName, users);
    System.debug('Push notification sent successfully!');
} catch (Exception e) {
    System.debug('Push failed: ' + e.getMessage());
}

This is useful to confirm that:

APNs' credentials are valid.
Device is registered.
The app is receiving notifications and logging them. Once that works, you can switch to silent notifications.

Step 4: Send Silent, Data-Oriented Push Notifications

To avoid spamming the user, you convert the payload to a silent notification:

No alert.
No sound.
aps.content-available = 1.
Custom keys at the root for your app (e.g. type, recordIds). A simplified example for Account updates:

trigger accountAlert on Account (after update) {

    final String TARGET_USER_ID = 'TEST_USER_ID'; // Example user

    for (Account acc: Trigger.New) {

        Account oldAcc = Trigger.oldMap.get(acc.Id);

        Boolean nameChanged     = acc.Name     != oldAcc.Name;
        Boolean ownerChanged    = acc.OwnerId  != oldAcc.OwnerId;
        Boolean typeChanged     = acc.Type     != oldAcc.Type;

        if (nameChanged || ownerChanged || typeChanged) {

            List<String> changes = new List<String>();
            if (nameChanged)  changes.add('Name');
            if (ownerChanged) changes.add('Owner');
            if (typeChanged)  changes.add('Type');

            String changedFields = String.join(changes, ', ');

            // APS for silent push
            Map<String, Object> aps = new Map<String, Object>{
                'content-available' => 1
            };

            // Full payload: aps + custom data
            Map<String, Object> payload = new Map<String, Object>();
            payload.put('aps', aps);
            payload.put('accountId', acc.Id);
            payload.put('accountName', acc.Name);
            payload.put('changedFields', changedFields);
            payload.put('type', 'ACCOUNT_UPDATE');

            Messaging.PushNotification msg = new Messaging.PushNotification();
            msg.setPayload(payload);

            Set<String> users = new Set<String>{ TARGET_USER_ID };

            try {
                msg.send('LSC_Real_time_Sync', users);
                System.debug('Silent push notification sent for Account: ' + acc.Name);
            } catch (Exception e) {
                System.debug(LoggingLevel.ERROR,
                    'Silent push notification failed for Account ' + acc.Name +
                    ': ' + e.getMessage());
            }
        }
    }
}

You can apply the same pattern to Interactions or LMR-related objects, and further restrict to:

LastModifiedById == current user to avoid system-generated updates.
Excluding updates from sync queues or integration users. This keeps pushing focused on user-initiated changes.

Step 5: Handle Push Notifications in the iOS App

On the client side, you already have a unified handler to inspect incoming notification data.
At minimum:

Foreground: userNotificationCenter(_:willPresent:withCompletionHandler:).
Tap: userNotificationCenter(_:didReceive:withCompletionHandler:).
Background/silent: application(_:didReceiveRemoteNotification:fetchCompletionHandler:). A simplified version that logs and reacts to custom keys:

func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any],
    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
) {
    handlePushNotification(userInfo: userInfo)
    completionHandler(.newData)
}

func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    willPresent notification: UNNotification,
    withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
) {
    let userInfo = notification.request.content.userInfo
    handlePushNotification(userInfo: userInfo)
    completionHandler([]) // no banner/sound for silent sync
}

private func handlePushNotification(userInfo: [AnyHashable: Any]) {
    // Example: respond to account/interaction updates
    if let type = userInfo["type"] as? String {
        switch type {
        case "ACCOUNT_UPDATE":
            if let accountId = userInfo["accountId"] as? String {
                // Trigger a targeted fetch for this account
                refreshAccount(withId: accountId)
            }
        case "INTERACTION":
            if let ids = userInfo["recordIds"] as? [String] {
                refreshInteractions(withIds: ids)
            }
        default:
            break
        }
    }
}

The refreshAccount / refreshInteractions functions can use SFRestAPI to call your existing, territory-aware sync endpoints and update your local database. The important part is that:
Push only carries IDs and type, not full record data.
The app decides how and when to fetch the rest.

Design Considerations and Trade-Offs

The approach led to some clear conclusions about how to use this pattern safely:

Use push as a sideband hint, not as the primary sync mechanism

Push is best-effort and subject to APNs/iOS behavior.
Regular sync remains the authoritative way to catch all changes.

Limit scope to user-initiated changes

Generate pushes when the current user modifies records via Agentforce/LWC/web UI.
Avoid pushing for backend/sync-queue changes to prevent noise and overload.

Keep payload small and focused

Use push to send only type and a small set of recordIds.
Let the app fetch full records via REST/Composite or your existing sync APIs.

Accept possible duplicate downloads

A record refreshed via push may come down again in the next regular sync because its LastModifiedDate is newer than the last sync date.
With idempotent merge logic, this is a performance cost, not a correctness problem.

Prefer silent notifications for data refresh

Visible notifications are for user awareness; silent notifications are for data state.
For offline-first apps, silent push is usually the right default for “real-time updates”.

Recap

To summarize:

Salesforce + Mobile SDK + APNs give you a way to target specific users with push notifications based on business events.
For real-time data freshness in offline-first apps, silent push notifications are the right primitive: they wake the app, carry record IDs, and let the client fetch updated data.
The full path:

-- Connected App with APNs credentials.
-- Device registration via SFPushNotificationManager.
-- Apex push using Messaging.PushNotification to a user.
-- iOS handlers logging and handling payloads, ready to trigger selective sync.

By scoping push to user-initiated changes and treating it as a sideband channel, you get near real-time updates for critical objects without modifying the core sync algorithm or compromising data integrity.

References

Salesforce

Salesforce Mobile Notifications Implementation Guide (PDF) https://resources.docs.salesforce.com/latest/latest/en-us/sfdc/pdf/salesforce_mobile_push_notifications_implementation.pdf
Mobile Notifications Overview (HTML) https://developer.salesforce.com/docs/atlas.en-us.pushImplGuide.meta/pushImplGuide/pns_overview.htm
Push Notifications and Mobile SDK https://developer.salesforce.com/docs/platform/mobile-sdk/guide/push-intro.html
Enable Push Notifications in a Salesforce Mobile SDK iOS App https://developer.salesforce.com/docs/atlas.en-us.pushImplGuide.meta/pushImplGuide/pns_client_app_ios.htm
Using Push Notifications in iOS (Mobile SDK) https://developer.salesforce.com/docs/platform/mobile-sdk/guide/push-using-ios.html
Messaging.PushNotification Class (Apex Reference) https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_classes_push_notification.htm
Messaging.PushNotification Methods (send, etc.) https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_Messaging_PushNotification_methods.htm
Using Apex Triggers to Send Push Notifications https://developer.salesforce.com/docs/atlas.en-us.pushImplGuide.meta/pushImplGuide/pns_apex_trigger.htm

Apple

Generating a Remote Notification (payload format and 4 KB limit) https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification
Creating the Remote Notification Payload (archived guide) https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/CreatingtheNotificationPayload.html
Payload Key Reference (JSON size and keys) https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/PayloadKeyReference.html
Technical Note TN2265 – Troubleshooting Push Notifications https://developer.apple.com/library/archive/technotes/tn2265/_index.html
Sending Notification Requests to APNs https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns
Troubleshooting Push Notifications (UserNotifications) https://developer.apple.com/documentation/usernotifications/troubleshooting-push-notifications

The end result is a Salesforce mobile app that feels much more responsive: important user-driven changes show up quickly, while the existing offline sync remains the safety net that keeps everything consistent.