In this post, you’ll learn the basic syntax and mental model, typical use cases (including e‑commerce examples), and pilot gates and current constraints, so you can try it safely in a sandbox.

The pilot is open to any Salesforce customer — contact your Salesforce Account Executive or Customer Success Manager to request access.

Why use FORMULA() in SOQL WHERE?

When a filter depends on something that you calculate from fields, such as margin, revenue per head, days idle, or days late to ship, the usual choices are: add a formula field, maintain a duplicate rule in Apex, or query too many rows and throw away what you do not need. 

FORMULA('…') in WHERE is for the case where the rule belongs with the query: you describe the computed condition once, the platform evaluates it as part of filtering, and callers (Apex, APIs, downstream jobs) get a smaller, already qualified result set. This is especially valuable when you can not or do not want to change the data model for every subscriber org, a common scenario for ISVs or developers who want to keep operational segmentation logic visible in SOQL instead of buried in loops.

For example, say you’re working with an Order__c object and need to find every order where profit (revenue minus cost) exceeds $150. Without FORMULA(), the rule lives in Apex after a broader query; with FORMULA(), the rule moves into the WHERE clause itself.

For example, say you’re working with an Order__c object and need to find every order where profit (revenue minus cost) exceeds $150. Without FORMULA(), the rule lives in Apex after a broader query; with FORMULA(), the rule moves into the WHERE clause itself.

// Without FORMULA(): business rule lives in Apex after a wider query

 List rows = [SELECT Id, Name, Revenue__c, Cost__c FROM Order__c];
  List highMargin = new List();
  for (Order__c o : rows) {
      if (o.Revenue__c != null && o.Cost__c != null
          && (o.Revenue__c - o.Cost__c) > 150) {
          highMargin.add(o);
      }
  }

--With FORMULA(): same rule expressed in the WHERE clause 

SELECT Id, Name FROM Order__c WHERE FORMULA('Revenue__c - Cost__c') > 150

The formula expression supports addition and subtraction (+ and -). Expressions can evaluate to DOUBLE, INTEGER, DATETIME, DATE & CURRENCY.

In practice:

• INTEGER behaves like DOUBLE
• DATE behaves like DATETIME

So the rest of this post focuses on the three illustrative types: DOUBLE, DATETIME, and CURRENCY.

This pattern fits Apex and SOQL developers, ISV teams shipping logic across subscriber orgs where schema changes are hard, and anyone trying to move off the “query a large candidate set, filter in code” approach.

Beyond fitting that audience, FORMULA() in WHERE matters today because it:

• Eliminates unnecessary formula fields
• Reduces Apex complexity
• Improves performance by filtering at the query level
• Is especially valuable for ISVs who can’t modify customer schemas

Syntax: FORMULA() in WHERE

Today, FORMULA() in SOQL is available as a pilot capability: it is only supported in the WHERE clause (not HAVING).

The general shape is:

WHERE FORMULA('…') <operator> <literal>

The string is a formula expression evaluated for each row as part of filtering.

Example: E-commerce order management 

Imagine that you’re building an order analytics dashboard for a growing e-commerce platform.

Your custom Order__c object tracks:

• Revenue__c (Currency): Total order value
• Cost__c (Currency): Fulfillment cost
• OrderDate__c (Date): When customer placed order
• ShipDate__c (Date): When order shipped
• Status__c (Text): Order status

Previously, filtering orders by calculated metrics meant either:

1. Creating formula fields like Profit__c, ShippingDelay__c, ProfitMargin__c
2. Querying all orders and filtering in Apex loops

Let’s see how FORMULA() eliminates both.

The screenshot below shows a Sample Order__c records table that includes seven orders (ORD-001 through ORD-007) with Revenue, Cost, OrderDate, ShipDate, and Status columns used throughout the FORMULA() examples.

Three key use cases

For our e-commerce example, FORMULA() is particularly helpful in the following three use cases:

1. Find high-profit orders using currency arithmetic.
2. Detect late shipments using datetime arithmetic.
3. Filter by premium order criteria using combined conditions.

1. Find high-profit orders (CURRENCY arithmetic)

Our business requirement for this first use case is to identify orders with profit > $250 for priority fulfillment review.

The old way

 // Query everything, filter in memory
  List allOrders = [
      SELECT Id, Name, Revenue__c, Cost__c
      FROM Order__c
      WHERE Status__c = 'Shipped'
  ];

  List highProfitOrders = new List();
  for (Order__c order : allOrders) {
      if (order.Revenue__c != null &&
          order.Cost__c != null &&
          (order.Revenue__c - order.Cost__c) > 250) {
          highProfitOrders.add(order);
      }
  }

// Result: 3 orders (ORD-001, ORD-003, ORD-005)

The new way

SELECT Id, Name, Revenue__c, Cost__c
FROM Order__c
WHERE Status__c = 'Shipped'
AND FORMULA('Revenue__c - Cost__c') > 250

The following screenshot shows a SOQL query using the FORMULA() function to filter orders by profit: SELECT Id, Name, Revenue__c, Cost__c FROM Order__c WHERE Status__c equals “Shipped” AND FORMULA('Revenue__c - Cost__c') is greater than 250.Query results show three records: ORD-001 with 500 revenue and 200 cost, ORD-003 with 800 revenue and 300 cost, and ORD-005 with 1200 revenue and 400 cost.

2. Detect late shipments (DATETIME arithmetic)

Our business requirement here is to find orders that shipped more than three days after order date for SLA analysis. 

SELECT Id, Name, OrderDate__c, ShipDate__c
FROM Order__c
WHERE FORMULA('ShipDate__c - OrderDate__c') > 3

The screenshot below shows a SOQL query using the FORMULA() function to calculate shipping delays: SELECT Id, Name, OrderDate__c, ShipDate__c FROM Order__c WHERE FORMULA('ShipDate__c minus OrderDate__c') greater than three. Query results display two records: ORD-002 ordered April 5 and shipped April 12, and ORD-005 ordered April 15 and shipped April 25, both exceeding the three-day shipping threshold.

3. Premium order criteria (combined conditions)

Our business requirement for the third use case is to find “premium” orders: high revenue (> $600) AND fast shipping (≤ 2 days).                                                                                                           

SELECT Id, Name, Revenue__c, OrderDate__c, ShipDate__c
FROM Order__c
WHERE Revenue__c > 600
AND FORMULA('ShipDate__c - OrderDate__c') <= 2

The screenshot below shows a SOQL query combining standard field filter with the FORMULA() function: SELECT Id, Name, Revenue__c, OrderDate__c, ShipDate__c FROM Order__c WHERE Revenue__c is greater than 600 AND FORMULA('ShipDate__c minus OrderDate__c') is less than or equal to two. Query results show two records: ORD-003 with 800 revenue, ordered April 10 and shipped April 11, and ORD-007 with 650 revenue, ordered April 20 and shipped April 21, with both records meeting the high-revenue and fast-shipping criteria.

Conclusion

By applying the ideas in this post, you can express computed filters directly in SOQL. FORMULA() in WHERE turns the question from “what rows might be relevant?” into “what rows already match my computed rule?” with less schema churn. This tends to shrink Apex branching, reduce one-off formula fields for query-only rules, and make the business condition readable next to the SELECT, which helps both integrations and teams reviewing SOQL in code review and operations.

Beyond individual queries, the same pattern reinforces a broader habit: keep data access and the rule that defines “the right rows” together, so batch jobs, services, and packaged logic stay easier to maintain, especially when subscriber org schemas are not yours to reshape at will. As always, treat what you validate in a non-production org as the contract for syntax, supported types, and supported operators.

We would love your feedback on the capabilities of this pilot, and your comments will influence the GA release. Please post your questions and/or feedback on the Pilot to the Salesforce Developers Trailblazer Community. Just let us know!

Resources

• Pilot enrollment: Contact your Salesforce Account Executive or Customer Success Manager to request access to the SOQL FORMULA() pilot
• Trailhead: SOQL for Admins – Create SOQL Queries to get data from your Salesforce org

About the author

Dikshita Patel is a Software Engineer on Salesforce’s Enterprise API team, where she builds Platform APIs allowing developers, partners, and customers to query and access Salesforce data without using the Salesforce user interface. You can follow and connect with her on LinkedIn.

The post Simplify Your SOQL Queries Using SOQL FORMULA() in WHERE appeared first on Salesforce Developers Blog.

The MCE MCP Server is Salesforce’s first-party, enterprise-grade, hosted MCP server for Marketing Cloud Engagement. It’s a first step towards a truly headless experience, exposing MCE’s core marketing capabilities as tools that any MCP-compatible AI agent can call — in plain language, without writing code or navigating the UI. 

The server allows almost any external agent that supports MCP to manage data extensions, journeys, automations, and more. Note that Marketing Cloud API limits and guidelines apply (see documentation for more information).

In this post, we’ll walk you through the MCE MCP Server setup, tools, and typical use cases.

How to set up the MCE MCP Server

An agent’s permissions are a combination of the scopes in a dedicated, installed package and your own user permissions. If your installed package has access to read data extensions, but you (as a user) do not, then the MCP server does not have access. Likewise, you can limit what it can do by not granting permissions to the installed package, even if the user still has them. 

From the install package, you’ll be able to get an MCP URL that you and potentially other teammates can use. This is specific to your organization and the install package. It’s not sensitive, but it’s worth keeping in a safe place for convenience. Registering it with Claude Code, for example, is simple.

claude mcp add --transport http  https://

Other agents will be very similar. You should only need to do this once, and then authenticate from inside the agent. The details on how this works will vary depending on how the agent implements OAuth login flows, but you will be prompted to log into your Marketing Cloud account if you are not already logged in. This gives the agent a token that it can use to act on your behalf, but only for a limited time. 

For more information on MCE MCP Server setup, please see the documentation.

MCE MCP Server capabilities and tool reference

The MCE MCP Server is designed to simply wrap existing functionality provided by the Marketing Cloud Engagement APIs. For example, to get lists of data extensions, we offer a tool called sfmc_get_data_extensions. This is nearly 1:1 with a request to data/v1/customobjects on the original REST route, but made more easily discoverable for an agent. It can read the embedded documentation and discover that it needs to provide a $search variable with the search string.

As an example, this is how this tool is shown to the agent:

{
  "name": "sfmc_get_data_extensions",
  "description": "Retrieve a list of data extensions. GET /data/v1/customobjects.\n\nIMPORTANT: The $search query parameter is REQUIRED and must be a valid search term (no wildcards like * or %).\nYou must provide query_json with the structure: {\"$search\": \"term\"}\n\nExamples:\n- Search for 'customer': {\"$search\": \"customer\"}\n- Search for 'email': {\"$search\": \"email\"}\n\nSee resource 'sfmc://docs/data/v1/customobjects' for full API documentation.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query_json": {
        "type": "string",
        "description": "JSON object string containing $search parameter. REQUIRED format: {\"$search\": \"search_term\"}. The search term cannot be empty or contain wildcards (* or %)."
      }
    },
    "required": [
      "query_json"
    ]
  },
  "annotations": {
    "title": "sfmc get data extensions",
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": true
  }
}

Just as our documentation promised, the resulting tool call is simple. 

{ "$search": "test" }

The results are also pretty straightforward, even for a human to read.

Status: 200 OK
URL: https://mcfdpyw7c97kdckv65lk2j1vspd0.rest.marketingcloudapis.com/data/v1/customobjects?%24search=test

{
  "count" : 8,
  "page" : 1,
  "pageSize" : 25,
  "links" : { },
  "items" : [ {
    "id" : "bdc04e14-0209-f111-a5e8-5cba2c701e38",
    "name" : "test_7",
    "key" : "test_7",
    "description" : "Subscribers who purchased in 2018",
    "isActive" : true,
    "isSendable" : false,
    "isTestable" : false,
    "categoryId" : 1998298,
    "ownerId" : 11280369,
    "isObjectDeletable" : true,
    "isFieldAdditionAllowed" : true,
    "isFieldModificationAllowed" : true,
    "createdDate" : "2026-02-13T11:33:22.133",
    "createdById" : 11280369,
    "createdByName" : "GI Admin",
    "modifiedDate" : "2026-02-13T11:33:22.133",
    "modifiedById" : 11280369,
    "modifiedByName" : "GI Admin",
    "ownerName" : "GI Admin",
    "partnerApiObjectTypeId" : 310,
    "partnerApiObjectTypeName" : "DataExtension",
    "rowCount" : 0,
    "dataRetentionProperties" : {
      "isDeleteAtEndOfRetentionPeriod" : false,
      "isRowBasedRetention" : false,
      "isResetRetentionPeriodOnImport" : false
    },
    "fieldCount" : 15
  }, ...

It’s worth noting that the result is NOT JSON as far as the agent is concerned. It’s simply text, which in this case represents the result of making an API call to a REST endpoint. It is up to the agent to interpret this information and use it, and that’s what provides the maximum flexibility.

While the original intent of this API was to integrate with custom software, an AI agent can instead make it available interactively and with minimal friction. You don’t need to know about $search (did you forget the dollar sign?) or its syntax, the agent can deal with that. If the tool fails, it has access to the error message and relevant documentation to try again with different arguments without requiring a human to copy and paste an error code into a search engine. In this case, the tool offered sfmc://docs/data/v1/customobjects as a resource to selectively load and find out more about custom object definitions if necessary.

Another advantage is that if you are making a complex request, the AI agent (like Claude Client) can sequence tools that need to be executed in order to achieve the given functionality. For example, If you just tell the AI client to “Update the loyalty status of subscriberId 5544 to gold in XYZ DE,” the agent first gets the XYZ DE, fetches the row in DE, and updates the row without user intervention.

See the MCE MCP tool reference for more information.

What you can build with MCP + Marketing Cloud

We tested a range of use cases, from creating a new campaign journey using a single prompt to sending transactional messages in real time. AI agents are not necessarily the most creative things around, but our test agent was able to put most of the pieces we needed together, and it prompted for more context if it needed clarity on intent. Typically, you really want to hand off mundane tasks that you’d rather not deal with to an agent, such as the following.

• Create a Data Extension from a plain English description: Ask your AI agent, “Create a Data Extension for Holiday Shoppers with Email, First Name, Last Name, and Purchase Date.” The agent maps field descriptions to Marketing Cloud datatypes, sets SubscriberKey as the primary key, and returns the CustomerKey and a direct link to the new Data Extension — no Contact Builder navigation required.
• Launch a basic automated campaign without touching Journey Builder: Ask, “Create a Welcome Email journey that sends immediately when someone joins the Welcome List DE.” The agent verifies the entry source DE, builds the Entry → Email → Exit structure, resolves the email asset, and creates the journey in Draft. It then asks if you want to activate it.
• Build a nurture series conversationally: Ask, “Create a 3-email Welcome Series: send Email 1 immediately, wait 3 days, send Email 2, wait 7 days, send Email 3.” The agent parses the wait durations, names each activity descriptively, resolves all email assets, and returns the Journey Builder URL ready to review and activate.
• Add Einstein optimization to any journey step: Ask, “Add Einstein Send Time Optimization before the promotional email in my Black Friday Journey.” The agent verifies that Einstein STO is provisioned for your Business Unit, and inserts the activity immediately before the specified email.
• Propagate a new data field across every dependent DE and query in one command: Ask, “Add Propensity_Score (Number) from the Customer_Signals DE to all downstream Data Extensions and queries.” The agent traces transitive dependencies across all Query Activities and target DEs, shows you a full impact report (X DEs, Y query steps across Z automations), and — on your confirmation — adds the field to every DE, and updates every SELECT clause in dependency order. It then returns a summary of what changed and any errors encountered. This supports a dry-run mode to preview all changes before touching anything.

Having said that, we encourage you to try all your use cases with this MCP server and let us know if we are missing any crucial or nice-to-have tools on IdeaExchange.

Permissions, destructive operations, and safety guardrails

We’ve done our best to make this service as flexible and useful as possible, for as many people as possible. We decided early on to even support “destructive” operations like deleting data, even though that’s almost always a bad idea to hand off to an agent. Operations like this are annotated as destructive in a way that the agent can read, but the agent is still capable of choosing to execute them if it has the permissions to do so. It’s crucial to think through the “worst case” when assigning permissions during setup, because an agent can make mistakes. Customers are also sensitive to reputational harm if an unintentional send is triggered, so bear that in mind as well! Please make sure that you review your Installed Package scopes before using them. More details in this documentation.

Future growth

The MCE MCP Server is designed to be extended in the future, so be sure to check back often. We plan to extend coverage to other important Marketing Cloud APIs and improve what we’ve already built. Agents and the LLMs that power them are also continuously releasing and improving, so workflows that weren’t possible before might get more practical over time. 

We plan on continually improving the server and extending it to other Marketing Cloud APIs over time. Please keep an eye on our release notes, and provide feedback through your account manager or provide on IdeaExchange.

Resources

• Documentation: MCE MCP Server Setup Guide
• Documentation: MCE MCP Server Tool Reference

About the author

​​Swetha Pinninti is a Director of Engineering at Salesforce on the Marketing Cloud Einstein team. 

Patrick Frampton is a Lead Member of Technical Staff at Salesforce on the Marketing Cloud Einstein team.

The post The MCP Server for Marketing Cloud Engagement is Now GA appeared first on Salesforce Developers Blog.

This post breaks down the structure of a Salesforce agent skill using Apex as an example. For clarity, we’ll use Claude Code to highlight specific examples, but the principles apply to any agent. We’ll cover what a skill is, the project structure, and how to get started creating your first skill.

What is an agent skill?

An agent skill is a structured prompt package that transforms Claude from a general-purpose assistant into a specialist. Rather than relying on the model’s training data alone, a skill provides explicit workflow contracts, reference material, code templates, and automated validators that load into context when the skill activates.

The large language models (LLMs) that power Claude already know the programming languages across the Salesforce ecosystem: Apex, LWC, SOQL, etc. But knowing a language and consistently producing high-quality code that adheres to best practices are two different things. A skill bridges that gap.

Each skill lives in a folder with a predictable structure:

skills/authoring-apex/
├── SKILL.md              # The execution contract
├── references/           # Decision trees, patterns, guardrails
├── assets/               # Example code
└── hooks/scripts/        # Python validators

At minimum, you need a SKILL.md, which is the entry point that Claude reads when the skill activates. Everything else is scaffolding that you add as the skill grows. Start with one SKILL.md and one reference doc, and add hooks when you want mechanical enforcement rather than relying on instructions alone.

Skills activate based on frontmatter. Frontmatter is the YAML metadata block between the ‘---’ delimiters at the top of a markdown file. It’s not rendered as content, but it’s there to be read as machine-readable configuration. In a skill, the frontmatter tells an agent when to activate: the name field identifies the skill, and the description field contains the trigger rules that the agent uses to decide whether this skill is relevant to the current task.

In the example below, the description uses a TRIGGER when / DO NOT TRIGGER when structure that gives the agent both positive and negative match criteria. This eliminates the ambiguous middle ground (like “is this SOQL query part of Apex authoring or the SOQL skill?”) that causes misfires when you only tell the model what to activate on.

---
name: authoring-apex
description: >
  TRIGGER when: user writes, edits, or reviews Salesforce Apex code —
  .cls or .trigger files including service classes, selector classes,
  trigger handlers, test classes, batch jobs, queueable classes,
  invocable methods, or Apex REST endpoints.
  DO NOT TRIGGER when: user works on LWC JavaScript, Flow XML,
  standalone SOQL queries, or running existing tests.
---

This is a simplified version. In practice, the description is more comprehensive: listing every class type (schedulable, AuraEnabled, HttpCalloutMock) and naming which skill handles each excluded case (e.g. “use authoring-lwc” for LWC JavaScript). The more specific the boundary, the fewer misfires.

When a matching task is detected, Claude loads the SKILL.md and follows the workflow. You can also trigger a skill manually with /skill-name in the prompt. Either way, the full skill context — workflow, references, templates — is injected automatically. You never paste the SKILL.md content into the conversation yourself.

The skill format itself (a SKILL.md with frontmatter, references, and assets) is an open specification maintained by Anthropic under Apache 2.0 and open to community contributions. The SKILL.md, references, and templates that you write are portable. The hooks mechanism (hooks.yaml with PostToolUse lifecycle events) is Claude Code-specific — if you use another agent runtime, you’d wire validation differently, but the skill content travels with you. This makes skills headless. Use them with Agentforce Vibes, Claude Code, Cursor, VS Code, Gemini CLI, OpenAI Codex, Windsurf, Roo Code, Goose, or any of the 30+ agents that support the open specification.

The structure of an agent skill

SKILL.md: The execution contract

This is the key, non-reorderable workflow with hard exit criteria for each phase that will be followed when the skill is used. Here is a simplified example showing the structure. Your real SKILL.md would have more detail in each phase, but the shape is the same: ordered phases with exit criteria.

Follow this workflow in order. Do not skip, merge, or reorder steps.
If blocked, stop and ask for missing context. If not applicable, mark `N/A`
with a one-line justification in the report.

## Required Inputs

Gather or infer before authoring:

- Class type (service, selector, batch, queueable, invocable, trigger handler)
- Target object(s) and business goal
- Sharing default (`with sharing` unless justified)
- Trigger framework already in use (or explicit choice)

The phases:

### Phase 1 — Author
1. **Discover project conventions** — scan for existing patterns, trigger
     framework, naming style
2. **Choose the smallest correct pattern**:

  | Need               | Pattern                              |
  | ------------------ | ------------------------------------ |
  | Business logic     | Service class                        |
  | Data access        | Selector class                       |
  | Trigger logic      | Trigger handler (framework required) |
  | Flow integration   | @InvocableMethod                     |
  | Bulk processing    | Batch Apex                           |
  | Async work         | Queueable                            |

3. **Read the matching template** from `assets/` before authoring
4. **Author with guardrails** — apply every rule in the Rules section below
5. **Generate test class** — delegate to testing skill

### Phase 2 — Validate

6. **Run code analyzer** — remediate all blocking violations; re-run until clean
7. **Execute tests** — capture pass/fail and coverage percentage

### Phase 3 — Report

8. **Report** — files, design decisions, analyzer output, test results, deploy note

If a phase doesn’t apply, Claude must document it as N/A with justification. This maps directly to Anthropic’s best practice of providing “instructions as sequential steps using numbered lists when order or completeness matters.”

references/: The knowledge library

These are your reference documents that target a specific failure mode that general training handles inconsistently. Below are some best practices from Anthropic to follow since the temptation will be to include too much information.

For an authoring-apex skill let’s explore the reference files you might consider including.

This leverages what Anthropic calls providing “context and motivation behind instructions.” The references don’t just say what to do, they explain why, enabling Claude to generalize correctly to novel situations rather than pattern-matching blindly.

As an example the anti-patterns.md could look like this. This structure is designed for practices that are likely to go wrong repeatedly. Every section follows the same BAD/GOOD formula because Claude needs to recognise and avoid independent mistakes. Learn more about these anti-patterns in the documentation.

# Apex Anti-Patterns

## Table of Contents

- [SOQL in Loops](#soql-in-loops)
- 

---

## SOQL in Loops
**Anti-pattern:** Executing SOQL queries inside a `for` or `while` loop.

**Why this fails:** Salesforce enforces a hard limit of 100 SOQL queries
per synchronous transaction. Triggers fire in batches of up to 200 records,
so a single SOQL inside a loop exhausts the limit after just 100 records.

```apex
// BAD: 1 SOQL per iteration — hits 100-query limit at record 101
for (Account acc : accounts) {
    List contacts = [SELECT Id FROM Contact WHERE AccountId = :acc.Id];
}

Fix: Query once in bulk, then iterate over results.

// GOOD: 1 SOQL total
Map<Id, List> contactsByAccount = new Map<Id, List>();
for (Contact c : [SELECT Id, AccountId FROM Contact WHERE AccountId IN :accountIds]) {
    ...
}
// add other entries to align with the anti-patterns in salesforce well-architected

For speciality examples, like transaction security policies, the markdown could follow this structure and cover one specific Apex feature that breaks all the normal rules. It needs to teach Claude when the normal rules don’t apply, what to do instead, and why. There’s no BAD/GOOD pair because the “bad” code (e.g., global without sharing) is actually the correct code in this context. Note that the example in this case refers to a worked example in the assets folder.

# Transaction Security Policy (Apex condition)

## Table of Contents

- [Overview](#overview)
- [Class shape](#class-shape)
- [Sharing](#sharing)
- [Guardrails](#guardrails)
- [Example](#example)

---

## Overview

Enhanced Transaction Security policies call Apex when Condition Builder
is not enough. Implement `TxnSecurity.EventCondition` with a single
`evaluate(SObject event)` method.

## Class shape

- Declare the class **`global`** (required for Setup selection)
- Implement `TxnSecurity.EventCondition`
- Signature: `global Boolean evaluate(SObject event)`

## Sharing

These classes are **not** user-facing controllers. Use `without sharing`.
The normal `with sharing` default does NOT apply here -- applying it
will break the policy silently.

## Guardrails

- One bulk SOQL query max (no SOQL in loops -- governor limits still apply)
- Return `true` to block the transaction, `false` to allow

## Example

See assets/transaction-security-policy.cls

assets/: Few-shot by example

Anthropic highlights that one of the most reliable ways to steer Claude’s output format, tone, and structure is with implicit few-shot examples. Few-shot just means that you provide a few good examples as a template. Each template embeds the non-negotiable requirements: ApexDoc comments, bulk-safe logic, explicit sharing declarations, CRUD/FLS enforcement, and dependency injection for testability. When Claude adapts a template, it inherits these properties by construction rather than needing to recall them from training.

For Apex specifically, the world is your oyster here, but let’s explore some good use cases.

Each template isn’t just “how to write X.” It’s a pre-loaded, few-shot example with the non-negotiable requirements baked into the structure.

hooks.yaml and validator scripts: The safety net

A hook is a shell command that Claude Code runs automatically at a specific lifecycle moment. You configure them in hooks.yaml. The script is whatever that command executes, typically a Python validator that inspects the tool’s input/output and returns structured feedback.

Hooks close the feedback loop without human intervention. Claude writes something, the hook evaluates it immediately, and Claude sees the result in the same conversation turn. The correction happens in context while Claude still has the full problem loaded.

The hooks file wires the validator to the right moment. For example, a preflight check runs when the user submits a prompt.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_SKILL_DIR}/hooks/scripts/preflight-apex-check.py",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

Or a PostToolUse hook fires after every file write or edit.

---
name: authoring-apex
description: ...
hooks:
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "python3 ${CLAUDE_SKILL_DIR}/hooks/scripts/preflight-apex-check.py"
          timeout: 90000
---

Claude Code delivers the hook context as JSON on stdin. The payload shape varies by lifecycle event: PostToolUse includes the tool name, input parameters, and output; UserPromptSubmit includes the user’s prompt text.

Consider a preflight check for your development team. The SKILL.md workflow says “run Code Analyzer” in the validate phase. But what if Code Analyzer isn’t installed or is the wrong version? Without a hook, Claude attempts the command mid-workflow, gets an error, and the developer has to diagnose a missing plugin. With a hook, the check runs the moment Apex work begins.

import json, subprocess, sys

MINIMUM_VERSION = "5.5.0"

def parse_version(v):
    """Parse version string into comparable tuple."""
    return tuple(int(x) for x in v.split(".")[:3])

def main():
    hook_input = json.load(sys.stdin)
    prompt = hook_input.get("prompt", "").lower()

    # Only check when Apex work is likely
    apex_keywords = ["apex", ".cls", "class", "trigger", "service", "selector", "batch"]
    if not any(kw in prompt for kw in apex_keywords):
        sys.exit(0)

    try:
        result = subprocess.run(
            ["sf", "plugins", "--json"],
            capture_output=True, text=True, timeout=15
        )
        if result.returncode == 0:
            plugins = json.loads(result.stdout)
            for plugin in plugins:
                if plugin.get("name") == "@salesforce/plugin-code-analyzer":
                    version = plugin.get("version", "0.0.0")
                    if parse_version(version) >= parse_version(MINIMUM_VERSION):
                        sys.exit(0)
                    else:
                        print("=== Preflight Check ===")
                        print(f"  [WARNING] Code Analyzer {version} is below minimum {MINIMUM_VERSION}.")
                        print(f"  Install: sf plugins install @salesforce/plugin-code-analyzer@latest")
                        sys.exit(0)
    except (FileNotFoundError, subprocess.TimeoutExpired, json.JSONDecodeError):
        pass

    print("=== Preflight Check ===")
    print("  [WARNING] Salesforce Code Analyzer is not installed.")
    print("  The authoring-apex skill requires it for validation.")
    print("  Install: sf plugins install @salesforce/plugin-code-analyzer")
    sys.exit(0)

if __name__ == "__main__":
    main()

The developer is told up front that their toolchain is incomplete rather than discovering it mid-workflow when the validate phase fails. 

That’s what separates an instruction from a hook. The SKILL.md says “run Code Analyzer in the validate phase.” The hook proves that it can run before the workflow even starts. Instructions are aspirational; hooks are mechanical. You want both capabilities.

Why agent skills need human and mechanical validation

Skills are not a silver bullet. They dramatically narrow the probability distribution of Claude’s outputs, but they operate on a fundamentally non-deterministic system. Two things work against you:

You can’t fully specify behavior. No matter how precise your SKILL.md, real-world requirements contain novel combinations that aren’t covered by templates or references. Claude must still make judgement calls and newer models interpret prompts more literally, so slight underspecification produces inconsistent results. If your SKILL.md says “add error handling” without specifying the pattern, you’ll get different approaches each time.

Outputs are probabilistic. Even with structured prompts, role assignment, examples, and validation hooks, you’re optimizing a hit rate. You move from 60% correct to 95% correct — a massive improvement —  but the remaining 5% is why validators exist. This is why the architecture includes both preventive measures (structured prompts, references, templates) and detective measures (automated validators, scoring rubrics, blocking on errors). The skill assumes Claude will sometimes get it wrong and builds correction into the workflow rather than pretending perfection is achievable.

Getting started

Anthropic’s golden rule for prompts applies directly: “Show your prompt to a colleague with minimal context and ask them to follow it. If they’d be confused, Claude would be too.” A well-built agent skill is unambiguous to both a human reader and the model.

You don’t need to build a skill from scratch. Anthropic provides a skill-creator skill that walks you through the full process: capturing intent, writing the SKILL.md, creating test cases, running evals, and iterating until the output meets your bar. Install it and tell Claude what you want the skill to do; it handles the scaffolding, interviews you on edge cases, and generates a working draft you can refine.

If you’d prefer to work from an existing Salesforce-specific example, the Agentforce Vibes skill library includes production-ready skills for Apex, LWC, Flow, and more. Install them, use them, and look at how they’re structured; they follow similar patterns described in this post. The Agentforce Vibes skill library puts rules and rationale inline in the SKILL.md and uses complete Apex source files as templates rather than Markdown reference docs. This keeps the skill self-contained in fewer files, though it trades modularity: updating one rule means editing the main workflow file. 

The skill grows with your needs. Start with the skill-creator or an existing skill, customize what doesn’t fit your project, and build new skills only when you have a gap not covered by existing ones.

Resources

• GitHub: Salesforce’s collection of agent skills
• Trailhead: Prompt Fundamentals
• Trailhead: Prompt Engineering Techniques
• GitHub: Anthropics Skill Creator
• Documentation: Claude Code 

About the author

Dave Norris is a Developer Advocate at Salesforce. He’s passionate about making technical subjects broadly accessible to a diverse audience. Dave has been with Salesforce for over a decade, has over 40 Salesforce and MuleSoft certifications, and became a Salesforce Certified Technical Architect in 2013.

The post Build a Salesforce Agent Skill with Claude Code appeared first on Salesforce Developers Blog.

In this post, we’ll show you how to integrate Discovery Framework, an Omniscript-based digital form engine in Agentforce for Financial Services, directly into an Agentforce agent. 

By the end, you’ll have a working solution that renders structured forms inside the Agent window, replacing error-prone conversational capture with a reliable, UI-driven experience. This solution is for Salesforce Developers and architects building Agentforce experiences for the financial services industry. It requires familiarity with Apex, Lightning Web Components (LWC), and Omniscript basics.

The problem: Conversational capture falls short

In financial services, a typical transaction dispute intake process has five stages:

1. Identifying the impacted customer and account
2. Identifying the impacted transaction with enrichment for ease of identification
3. Capturing the reason for dispute and disputed amount
4. Creating a case for dispute intake
5. Capturing a dispute questionnaire

For high-volume contact center agents, Stage 5 is the hardest. Questionnaires are dynamic, changing based on payment network rules and transaction type.

A pure conversational experience creates real problems:

• Users can’t navigate backwards to update responses
• Special UI patterns (radio buttons, checkboxes) don’t translate to text
• Any AI paraphrase of a question risks capturing the wrong answer
• Questions must appear in strict order, with required/optional labels intact
• Longer questionnaires need save-and-resume support

The screen recording below shows an agent in conversational mode, asking dispute questionnaire questions one at a time.

The solution: Discovery Framework in agents

Agentforce Financial Services provides Discovery Framework, a feature that creates digital forms to collect and validate data while avoiding time-consuming, error-prone manual methods.

This framework was originally built for non-agentic, UI-driven scenarios. When you bring it into agents, you give users navigable, structured forms that address all five problems discussed above.

Key benefits:

• Navigation between questions with ability to update responses
• Proper rendering of radio buttons, checkboxes, and other form controls
• Exact question display without AI interpretation
• Correct ordering and required/optional field marking
• State persistence for incomplete forms

The framework renders a structured form directly in the agent output, with no conversational questions and no AI paraphrase risk. The screen recording below shows an agent in a Discovery Framework experience with structured form fields, radio buttons, and navigation controls embedded in the Agent interface.

Prerequisites: This experience is available only in UI-based channels — Lightning Experience, Messaging for Experience Sites, and third-party sites. It is not supported in Voice or Short Message Service (SMS) channels, where complex UI elements can’t be displayed.

Technical architecture overview

The integration uses Agentforce’s support for custom Lightning types and custom LWC components. Here’s the component architecture:

1. Discovery Framework Omniscript: The digital form definition with assessment questions
2. Custom LWC component: Wraps the Omniscript and handles data binding
3. Apex class: Executes business logic when the Agent action runs
4. Custom Lightning type: Associates the Apex output type with the LWC renderer
5. Agent action: Uses the Apex class as its reference action and the custom Lightning type as its output renderer

When an Agent action executes via a subagent, the custom Lightning type renders in the output, displaying the Discovery Framework Omniscript directly in the Agent window.

The architecture diagram below illustrates the runtime flow: a subagent triggers an agent action, which then executes Apex class business logic and renders the custom Lightning type LWC component, wrapping the Discovery Framework Omniscript in the Agent interface.

To learn more about the underlying capability, see Enhance the Agent UI with Custom LWCs and Lightning Types.

Steps to implement Discovery Framework in Agentforce

The implementation involves five steps. You start by creating a Discovery Framework Omniscript, then build the Apex classes that define the agent action’s business logic. Next, you create a Lightning web component to wrap and render the Omniscript inside the Agent window. You then configure a custom Lightning type to associate the Apex output with the LWC, and finally, you set up the agent action, which uses the Apex class as the reference action and the Lightning type as the output render. Let’s take a detailed look.

Step 1: Create a Discovery Framework Omniscript

First, we’ll need to create a series of assessment questions, then add them as steps in an Omniscript (a drag-and-drop digital form builder in Discovery Framework). See the Discovery Framework documentation for a step-by-step walkthrough.

For this example, we’ll create two sample dispute questions of type Radio Button with Yes/No responses.

Omniscript properties:

• Type: FinancialServices
• SubType: DisputeQuestionnaire
• Language: English

Important: Configure the Omniscript for a smaller viewport, so it renders correctly inside the agent window. Open the Omniscript properties panel and set the Viewport width to a maximum of 600px. Enable Responsive Mode if available. This ensures that the form fits within the agent output area without scrolling issues.

Navigation configuration:

• Enable Allow Save for Later to let users save incomplete forms
• Enable Show Progress Indicator to display form completion status
• Configure step-by-step navigation with Previous and Next buttons
• Select Hide step chart in Step Chart Options

For detailed instructions on creating Discovery Framework Omniscripts, see the Discovery Framework documentation.

To learn more, watch the video: Discovery Framework for Financial Services Cloud 

Step 2: Create Apex classes

Next, we’ll create an Apex class that captures the business logic for the agent action. In this example, the class creates a real Case record and returns the case number and ID. You’ll want to adapt the logic to your business needs.

The following Apex classes define the input, output, and business logic for the agent action. Each class plays a specific role in handling the incoming dispute request, structuring the output data, and executing the case creation logic.

Here is sample code for the Apex classes noted above.

DisputeQuestionnaireInput.cls
This class serves as the input of the agent action and contains a disputeRequest String field.
See sample code.

DisputeQuestionnaireOutput.cls
This class serves as the output of the agent action and contains a DisputeQuestionnaireCaseOutput object.
See sample code.

DisputeQuestionnaireCaseOutput.cls
This class contains the caseNumber and caseId fields as Strings.
See sample code.

DisputeQuestionnaireAction.cls
This class has the business logic that is executed by the agent to create a case and add it to a DisputeQuestionnaireCaseOutput object which is embedded inside a DisputeQuestionnaireOutput object.
See sample code.

Step 3: Create a Lightning web component

Next, we’ll create a Lightning Web Component that wraps the Discovery Framework Omniscript from Step 1. 

The displayDisputeQuestionnaire Lightning web component wraps the Discovery Framework Omniscript and renders it inside the Agent window. This component includes an HTML, a JavaScript and an XML file. The HTML defines the component structure, the JavaScript handles data binding and event subscription, and the metadata XML registers the component as an Agentforce output target.

Here is a sample code for the displayDisputeQuestionnaire Lightning web component.

displayDisputeQuestionnaire.html
This HTML component wraps the Discovery Framework Omniscript created in Step 1, using <omnistudio-omnistudio-standard-runtime-wrapper>.

<template>
   <div class="slds-card">
           <div class="slds-card">
               <div class="slds-modal__content">
                   <omnistudio-omnistudio-standard-runtime-wrapper
                           type="FinancialServices"
                           subtype="DisputeQuestionnaire"
                           language="English"
                           prefill={prefill}>
                  </omnistudio-omnistudio-standard-runtime-wrapper>
               </div>
           </div>
   </div>
</template>

Note: We’ll use the same Type, SubType, and Language values in the HTML as configured in Step 1, as shown in above code snippet.

See sample code.

displayDisputeQuestionnaire.js
This is the JavaScript for the LWC, supporting the above HTML.

import { LightningElement, api, track } from 'lwc';
import { NavigationMixin } from 'lightning/navigation';
import pubsub from 'omnistudio/pubsub';

export default class DisplayDisputeQuestionnaire extends NavigationMixin(LightningElement) {
   _value;
   @api
   get value() {
       return this._value;
   }
   set value(value) {
       this._value = value;
   }
   @track prefill; assessmentId; caseNumber; caseId;
   connectedCallback() {
       this.caseNumber = this.value?.caseOutput?.caseNumber || null;
       this.caseId = this.value?.caseOutput?.caseId || null;
       pubsub.register('omniscript_action', {
           data: this.handleOmniAction.bind(this),
       });
   }
   handleOmniAction(data) {
       this.assessmentId = data?.assessmentId || null;
   }
}

See sample code.

displayDisputeQuestionnaire.js-meta.xml
This is the js-meta.xml for the LWC, which captures the target as AgentforceOutput.
See sample code.    

Key implementation details:

• The component subscribes to omniscript_action events to capture form completion
• The prefill property allows pre-populating form fields with contextual data
• The value property receives output from the Apex class
• Navigation handles redirecting users to the created Case record after completion
• The lightning__AgentforceOutput target in the metadata XML is required for the component to render in Agentforce

Step 4: Create a custom Lightning type

Next, we’ll create a custom Lightning type to associate the Apex output types from Step 2 with the LWC from Step 3.

The displayQuestionnaireResponse Lightning type defines the custom Lightning type. This Lightning type includes the JSON files, which tells Agentforce how to map your Apex output to the LWC renderer and validates the data structure at runtime.

Here is a sample code for the displayQuestionnaireResponse Lightning type.

renderer.json
Therenderer.json file maps the root output ($) to your LWC component.
See sample code.

schema.json
The schema.json file defines the data type structure matching your Apex output class.
See sample code.

For detailed setup instructions, see Enhance the Agent UI with Custom LWCs and Lightning Types.

Step 5: Create an agent action

Finally, we’ll create an agent action that uses the Apex classes from Step 2 for execution and the custom Lightning type from Step 4 for output rendering.

Agent action configuration steps:

1. Navigate to Setup > Agentforce > Agent Actions
2. Click New Agent Action
3. Set Reference Action Type to Apex
4. Select DisputeQuestionnaireAction as the Apex class
5. Set Output Rendering to the DisputeQuestionnaireResponse custom Lightning type
6. Configure input parameters to match the Agent Topic context
7. Add instructions for when the agent should invoke this action

Example subagent instruction:

When a customer wants to dispute a transaction, execute the Process Dispute Request action to capture detailed dispute information through a structured questionnaire. When this agent action fires as part of a subagent, the Discovery Framework Omniscript renders directly in the Agent window.

The screenshot below shows a sample agent action configuration in Agent Builder, with the disputeQuestionnaireResponse Lightning type created in Step 4 set as the output renderer.

Rendering the Discovery Framework Omniscript in an Agent Script action

If your Agent is built using Agent Script, you can also render the Discovery Framework Omniscript in an action which is part of the Agent Script. 

For the dispute example, the code snippet below would help to render the output of the action using the Discovery Framework Omniscript.

outputs:
    caseOutput: object
        label: "Case Output"
        description: "The dispute case details including case number and case Id"
        complex_data_type_name: "c__DisputeQuestionnaireResponse"
        developer_name: "caseOutput"
        is_displayable: True
        filter_from_agent: False

Testing the integration

The following are steps to test the complete integration.

1. Create a subagent that invokes your new agent action
2. Start a conversation with the agent
3. Trigger the dispute intake flow
4. Verify that the Discovery Framework form renders in the Agent interface
5. Complete the questionnaire and verify that data is captured correctly
6. Confirm that the Case record is created with the captured information

Troubleshooting tips:

• If the form doesn’t render, verify that the Omniscript Type, SubType, and Language match exactly in both the Omniscript definition and LWC component
• If data doesn’t pass correctly, check that @AuraEnabled annotations are present on all Apex output class properties
• If navigation fails, ensure that the LWC component’s js-meta.xml includes the lightning__AgentforceOutput target

Extending this pattern

This mechanism isn’t limited to Discovery Framework Omniscripts; you can apply it to any Omniscript in your org, as long as the user experience fits within a compact viewport.

Additional use cases:

• Loan application intake: Multi-step loan applications with document upload
• Insurance claims processing: Complex claim forms with conditional logic
• Customer onboarding: Know Your Customer (KYC) questionnaires with validation rules
• Financial planning: Goal-setting forms with calculation logic

The key requirement: design Omniscripts for responsive display within the agent interface viewport constraints.

Conclusion

With these five steps, you can replace fragile conversational question-and-answer flows with a reliable, structured form experience — directly inside Agentforce. This approach combines the conversational intelligence of Agentforce with the rich data collection capabilities of Discovery Framework, delivering the best of both worlds.

By following this approach, you maintain accurate data capture without AI hallucination, while giving users intuitive, navigable forms that feel natural within the Agent conversation flow. Try it out and share what you build. Post questions on the Salesforce Developer Community or Stack Overflow.

Resources

• Documentation: Transaction Dispute Management Intake in Financial Services Cloud
• Documentation: Discovery Framework
• Video: Discovery Framework for Financial Services Cloud
• Developer Guide: Enhance the Agent UI with Custom LWCs and Lightning Types 

About the author

Aditya Bhansali is a Lead Member of Technical Staff in the Agentforce Financial Services organization, where he leads Salesforce engineering teams in building enterprise products on the Salesforce Platform. He shares updates on LinkedIn.

The post Capture Rich Data within Agent Conversations by Using Discovery Framework appeared first on Salesforce Developers Blog.

In this post, we’ll explore the benefits of working with MCP servers, then we’ll focus specifically on how to configure Claude for MCP, and finally, we’ll share some sample use cases.

What are Salesforce Hosted MCP Servers?

The Model Context Protocol (MCP) is an open standard that lets agentic tools like Postman or AI agents like Claude interact with external tools and data sources from various vendors. In the context of Salesforce, it means that you can run SOQL queries, modify records, and execute actions directly from a third-party agent. In other words, you don’t have to log into Salesforce and you’re no longer limited to using Agentforce to interact with your data from agents.

In order to perform operations on Salesforce with agents, you use MCP servers that expose tools and prompts. You can configure and host your own Salesforce MCP Server or use the Salesforce Hosted MCP Servers that are now generally available. We’ll only focus on the latter in this post since this approach saves you from the burden of hosting, securing, and maintaining the server.

Standard Salesforce Hosted MCP Servers

In addition to the Salesforce DX MCP Server used for development purposes, Salesforce offers a number of standard hosted MCP servers out of the box for daily operations. These allow agents to access our Headless 360 portfolio ranging from the Salesforce Platform, Data 360, Tableau, and MuleSoft. You can also connect directly to the Slack hosted MCP server.

Custom Salesforce Hosted MCP Servers

If the standard hosted MCP servers do not fit your needs, you can also create custom hosted MCP servers. This option gives you granular control over the tools and prompts that the server exposes, and lets you add custom tools and prompts.

You can build custom MCP tools from the following types:

• Apex Action: Expose invocable Apex Actions (@InvocableMethod annotated Apex methods) as MCP tools
• Lightning Flows: Expose autolaunched flows as MCP tools
• Apex REST: Expose custom Apex REST endpoints as MCP tools.
• AuraEnabled: Expose @AuraEnabled (see docs) annotated Apex methods as MCP tools
• Named Query API: Expose Named Query APIs as MCP tools to provide access to specific parametrized SOQL queries

You can also create custom MCP prompts from Flex prompt templates built with Prompt Builder. Using MCP prompts in an agent lets you call those parametrized prompt templates as commands. For example, if you expose a “Generate Personalized Schedule” prompt template, you can run the following command in Claude (you don’t have to type the full tool name, autocomplete provides the prompt description).

Now that we’ve seen the benefits of working with the Salesforce Hosted MCP Servers, let’s look at how to configure Claude to leverage them.

Configure Claude to work with Salesforce Hosted MCP Servers

Configuring Claude to connect with the hosted MCP servers is a three-step process:

1. Activate Salesforce Hosted MCP Servers
2. Create an external client app
3. Connect Claude to the Salesforce Hosted MCP Servers

Note: Claude is available in different surfaces. In this post, we’ll cover Claude Code (the CLI experience) and Claude Desktop (the desktop app).

As part of the setup, you’ll need to set up an external client app (ECA) so that Claude can authenticate via OAuth 2.0 with Salesforce to use the hosted MCP servers. An ECA tells Salesforce which external applications are allowed to connect to your org and what they’re allowed to do. Standard Salesforce user access permissions apply in addition to the app-level access checks.

Step 1: Activate Salesforce Hosted MCP Servers

The standard Salesforce Hosted MCP Servers are inactive by default. Follow these steps to activate them:

1. In Setup, search for MCP Servers.
2. Click the Salesforce Servers tab.
3. Repeat the following steps for each server that you want to activate:
   1. Click on the server name.
   2. Click Activate.
   3. Copy the server’s API Name without the platform. suffix and the Server URL. We’ll need those in the next step.

Step 2: Create an external client app

Follow these steps to create an ECA:

1. In Setup, search for External Client App Manager and click New External Client App.
2. Under Basic Information, fill in the required fields:
   

   Field name	Field Value
   App Name	Claude MCP Client
   API Name	Claude_MCP_Client (auto-filled)
   Contact Email	Your email address

3. Expand the API (Enable OAuth Settings) section, check Enable OAuth and configure the following app settings:
   1. Callback URL with either:
      • https://claude.ai/api/mcp/auth_callback for Claude Desktop
      • http://localhost:38000/callback for Claude Code. Use this if you only have an Anthropic API key provisioned for you by your enterprise. Otherwise, we recommend setting up connectors in your Claude.ai account, then using them in Claude Code.
   2. Selected OAuth scopes:
      • Perform requests at any time (refresh_token, offline_access)
      • Access Salesforce Hosted MCP Servers (mcp_api)
4. Under Security, apply the following:
   1. Uncheck these boxes:
      • Require secret for Web Server Flow
      • Require secret for Refresh Token Flow
   2. Check these boxes:
      • Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows
      • Issue JSON Web Token (JWT)-based access tokens for named users 

        At this point, your ECA configuration should look like this:
        

5. Click Create to save the app.

Now that the app is created, you need to retrieve the connection information:

1. Navigate to the Settings tab and expand OAuth Settings.
2. Click Consumer Key and Secret.
3. Complete the authentication dialog with the verification code.
4. Copy the Consumer Key and Consumer Secret.

Step 3: Connect Claude to the Salesforce Hosted MCP Servers

The last step of the integration process is to configure the Salesforce MCP Server connections in Claude.

The instructions differ depending on whether you use Claude Code or Desktop (in particular the ECA callback URL). We’ll dive into how to configure Claude Code here, and you can find instructions for Claude Desktop in the docs.

Instructions for Claude Code

1. Run the following command in a terminal where:
   – MY_MCP_SERVER_NAME is replaced by the name of the server that you’re connecting to. You’re free to enter any value, but we recommend that you stick to the following convention: salesforce- followed by the API name of the MCP server. For example: salesforce-sobject-all for the sobject-all server.
   –MY_MCP_SERVER_URL is replaced by the MCP server URL that you copied earlier. Pay attention to the fact that server URLs differ depending on whether you are connecting to a production or sandbox/scratch org.
   –MY_ECA_CONSUMER_KEY is replaced by the ECA consumer key you’ve obtained in the previous step.

   claude mcp add --transport http MY_MCP_SERVER_NAME MY_MCP_SERVER_URL --callback-port 38000 --client-id "MY_ECA_CONSUMER_KEY" --client-secret
   

   For example, to install the sobject-all MCP server from a scratch org, run:

   claude mcp add --transport http salesforce-sobject-all https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-all --callback-port 38000 --client-id "XXX" --client-secret
   

2. When prompted to do so, paste the ECA consumer secret you’ve obtained previously.
3. Launch Claude Code with the claude terminal command.
4. Run /mcpto list the MCP servers.
5. Select your newly added MCP server from the list (it is annotated with a “needs authentication” message).
6. Select Authenticate.
7. When prompted, allow access to the MCP server.

Once you authorize the connection, Claude Code lists your MCP server as “connected.”

Some practical examples of Claude working with Salesforce Hosted MCP Servers

Let’s assume that you work at Coral Cloud Resorts, a fictitious resort that offers tailored experience to their guests using Headless 360. You can use Claude and our MCP servers for a number of tasks.

Analyzing daily bookings

Let’s imagine that as the resort manager, you want to review customer bookings on a weekly basis.

In traditional Salesforce operations, you would build a report and then generate a dashboard out of it. To access it, you would need tens of clicks in Lightning Experience.

With Claude, all you have to do is use natural language, such as “Show me a report of daily bookings. Use the start date to group bookings,” to get the trend of your bookings with some additional insights that would require that you set up Tableau reports. You can also drill down by interacting further with Claude with follow up questions.

❯ Show me a report of daily bookings. Use the start date to group bookings.                                                                                      

⏺ I'll query the bookings grouped by start date now.
  
  Called salesforce-sobject-all (ctrl+o to expand)

⏺ Let me find the correct booking object name in this org.

  Called salesforce-sobject-all 2 times (ctrl+o to expand)

⏺ The date field is Date__c. Let me query the bookings grouped by that field.

  Called salesforce-sobject-all (ctrl+o to expand)

⏺ Here's the daily bookings report:

  ┌────────────┬──────────┬──────────────┬───────────────┐
  │    Date    │ Bookings │ Total Guests │ Total Revenue │
  ├────────────┼──────────┼──────────────┼───────────────┤
  │ 2026-05-10 │ 347      │ 1,096        │ $144,918      │
  ├────────────┼──────────┼──────────────┼───────────────┤
  │ 2026-05-11 │ 316      │ 1,026        │ $132,874      │
  ├────────────┼──────────┼──────────────┼───────────────┤
  │ 2026-05-12 │ 325      │ 996          │ $131,169      │
  ├────────────┼──────────┼──────────────┼───────────────┤
  │ 2026-05-13 │ 347      │ 1,050        │ $135,670      │
  ├────────────┼──────────┼──────────────┼───────────────┤
  │ 2026-05-14 │ 285      │ 887          │ $106,410      │
  ├────────────┼──────────┼──────────────┼───────────────┤
  │ Total      │ 1,620    │ 5,055        │ $651,041      │
  └────────────┴──────────┴──────────────┴───────────────┘

  A 5-day window with fairly consistent volume (~315–347/day), except May 14 which is notably lower at 285 bookings and $106K revenue — about 18% below the average of the other days.

Reading data is nice, but agents can take things further with MCP and take action.

Mass cancelling bookings using a custom server and a flow

Running a resort is no simple feat, and there can be unforeseen events (such as jellyfish invasions) that lead to booking cancellations. Should such unlikely scenarios occur, the resort staff is left scrambling to mass cancel bookings with hundreds of clicks, which is a repetitive and error-prone process.

Instead, you can leverage Headless 360 and expose our existing Cancel Booking flow as a custom hosted MCP server.

Note: in this basic example, you use a flow to cancel a single booking at a time. However, in production, we recommend creating a dedicated flow to process cancellations in bulk to reduce API calls and scale.

Once the custom MCP server is added to Claude, you can run the cancellations with a prompt that combines multiple calls to our various MCP servers. Note how the prompt is structured to keep the human in the loop: you validate the data before running the cancellation batch.

❯ Identify all bookings for tomorrow morning for the "Surf's Up Lesson" and "Tropical Snorkel Adventure" experience.            
  Let me verify the list then cancel them with the following cancellation reason: "Dear guest, we're sorry to cancel your aquatic experience due to a jellyfish invasion. You'll be refunded shortly."                                                  

⏺ Let me query tomorrow's morning bookings for those two experiences.

  Called salesforce-sobject-all (ctrl+o to expand)

⏺ Here are the 12 bookings found for tomorrow morning (May 13) — please verify before I proceed with cancellations:

  Surf's Up Lesson (9:00 AM – 10:00 AM) — 5 bookings

  ┌─────┬────────────┬───────────────────┬──────────────────────────────┬────────┐
  │  #  │  Booking   │       Guest       │            Email             │ Guests │
  ├─────┼────────────┼───────────────────┼──────────────────────────────┼────────┤
  │ 1   │ B-00001602 │ Ferne Ackwood     │ ferneackwood@example.com     │ 1      │
  ├─────┼────────────┼───────────────────┼──────────────────────────────┼────────┤
  │ 2   │ B-00001603 │ Deeyn Dumsday     │ deeyndumsday@example.com     │ 2      │
  ├─────┼────────────┼───────────────────┼──────────────────────────────┼────────┤
  │ 3   │ B-00001604 │ Alessandro Krates │ alessandrokrates@example.com │ 2      │
  ├─────┼────────────┼───────────────────┼──────────────────────────────┼────────┤
  │ 4   │ B-00001605 │ Quinlan Soppit    │ quinlansoppit@example.com    │ 2      │
  ├─────┼────────────┼───────────────────┼──────────────────────────────┼────────┤
  │ 5   │ B-00001606 │ Osborn Libbe      │ osbornlibbe@example.com      │ 3      │
  └─────┴────────────┴───────────────────┴──────────────────────────────┴────────┘

  Tropical Snorkel Adventure (9:00 AM – 1:00 PM) — 7 bookings

  ┌─────┬────────────┬────────────────────┬───────────────────────────────┬────────┐
  │  #  │  Booking   │       Guest        │             Email             │ Guests │
  ├─────┼────────────┼────────────────────┼───────────────────────────────┼────────┤
  │ 6   │ B-00000972 │ Gay Ragge          │ gayragge@example.com          │ 1      │
  ├─────┼────────────┼────────────────────┼───────────────────────────────┼────────┤
  │ 7   │ B-00000973 │ Baxie Donaher      │ baxiedonaher@example.com      │ 5      │
  ├─────┼────────────┼────────────────────┼───────────────────────────────┼────────┤
  │ 8   │ B-00000974 │ Munmro Semken      │ munmrosemken@example.com      │ 3      │
  ├─────┼────────────┼────────────────────┼───────────────────────────────┼────────┤
  │ 9   │ B-00000975 │ Ira Kemble         │ irakemble@example.com         │ 1      │
  ├─────┼────────────┼────────────────────┼───────────────────────────────┼────────┤
  │ 10  │ B-00000976 │ Suzie Patience     │ suziepatience@example.com     │ 3      │
  ├─────┼────────────┼────────────────────┼───────────────────────────────┼────────┤
  │ 11  │ B-00000977 │ Stephine Suttill   │ stephinesuttill@example.com   │ 1      │
  ├─────┼────────────┼────────────────────┼───────────────────────────────┼────────┤
  │ 12  │ B-00000978 │ Christyna Gianelli │ christynagianelli@example.com │ 1      │
  └─────┴────────────┴────────────────────┴───────────────────────────────┴────────┘

  Total: 12 bookings, 25 guests affected.

  All are currently Confirmed. Confirm and I'll cancel all 12 with the jellyfish invasion message.

✻ Cogitated for 18s

❯ confirmed                                                                                                                      

⏺ Let me load the Cancel Booking flow tool and cancel all 12 bookings in parallel.

⏺ Cancelling all 12 bookings in parallel now.

  Called salesforce-coral-cloud-flows 12 times (ctrl+o to expand)

⏺ All 12 bookings cancelled successfully. Here's the summary:

  Surf's Up Lesson — 5 cancelled

  ┌────────────┬───────────────────┐
  │  Booking   │       Guest       │
  ├────────────┼───────────────────┤
  │ B-00001602 │ Ferne Ackwood     │
  ├────────────┼───────────────────┤
  │ B-00001603 │ Deeyn Dumsday     │
  ├────────────┼───────────────────┤
  │ B-00001604 │ Alessandro Krates │
  ├────────────┼───────────────────┤
  │ B-00001605 │ Quinlan Soppit    │
  ├────────────┼───────────────────┤
  │ B-00001606 │ Osborn Libbe      │
  └────────────┴───────────────────┘

  Tropical Snorkel Adventure — 7 cancelled

  ┌────────────┬────────────────────┐
  │  Booking   │       Guest        │
  ├────────────┼────────────────────┤
  │ B-00000972 │ Gay Ragge          │
  ├────────────┼────────────────────┤
  │ B-00000973 │ Baxie Donaher      │
  ├────────────┼────────────────────┤
  │ B-00000974 │ Munmro Semken      │
  ├────────────┼────────────────────┤
  │ B-00000975 │ Ira Kemble         │
  ├────────────┼────────────────────┤
  │ B-00000976 │ Suzie Patience     │
  ├────────────┼────────────────────┤
  │ B-00000977 │ Stephine Suttill   │
  ├────────────┼────────────────────┤
  │ B-00000978 │ Christyna Gianelli │
  └────────────┴────────────────────┘

  All 25 affected guests have been notified and will be refunded.

These are two basic examples of what you can do with Claude and Salesforce Hosted MCP Servers, ranging from standard actions to custom scenarios.

Conclusion

You’ve now had a glimpse at how Salesforce Hosted MCP Servers let you use agents like Claude to interact with Headless 360 without requiring users to log into Lightning Experience. You’ve learned how to configure Claude Code and Claude Desktop to connect with Salesforce Hosted MCP Servers, and you saw some practical examples of what can be done with those servers.

Now, it’s your turn to put Headless 360 to the test by building custom tools and configuring MCP servers to power your business.

Resources

• Documentation: Salesforce Hosted MCP Servers
• Documentation: Claude Code
• Postman collection: Salesforce Hosted MCP Servers

About the Author

Philippe Ozil is a Principal Developer Advocate at Salesforce, where he focuses on the Salesforce Platform. He writes technical content and speaks frequently at conferences. He is a full-stack developer and enjoys working with APIs, DevOps, robotics, and VR projects. Follow him on X, LinkedIn, and Bluesky, and check out his GitHub projects.

The post Connect Claude with Salesforce Hosted MCP Servers appeared first on Salesforce Developers Blog.

Join Salesforce Developer Advocates Stephan Chandler-Garcia and Philippe Ozil to learn how to build with Salesforce Headless 360 and get hands-on with APIs, MCP tools, and agent-ready experiences that extend Salesforce beyond the platform.

June 3 at 10:00 a.m. EDT
Register for free: https://sforce.co/42MBvMA

Salesforce Headless 360 makes every major Salesforce capability available as an API, Model Context Protocol (MCP) tool, or CLI command. MCP is a standardized protocol that lets AI models discover and call external tools, APIs, and data sources at runtime, so any compatible client can connect to any compatible server without custom integration code. This post covers what that means when you build on the platform, and why the fundamentals you’ve been learning matter more than ever.

As the Salesforce Developer Advocacy team lead, I recently posted on the future of the Salesforce Developer role. In that post, I argued that AI is reshaping our work around system design, quality engineering, and cross-system thinking. Headless 360 is the platform shift that turns those arguments into daily practice.

The platform provides context and capability

The LLM provides intelligence. The platform provides everything else: identity, access, capabilities, governance, and the context that makes intelligence useful. When an agent calls an MCP tool, it’s invoking accumulated state. Without it, the agent has nothing to reason over, no permissions to inherit, no business process to follow.

This was always true. Every customer record, every workflow, every approval chain, every permission boundary your org has accumulated – that’s not overhead. That’s the business itself, encoded in a system that enforces it.

That combination of intelligence from the model and everything else from the platform is what separates a prototype from a production system. It’s also what makes Headless 360 different from “just expose some APIs”.

Two kinds of MCP tools

When we talk about MCP tools in the Salesforce ecosystem, we mean two things:

• MCP tools for coding agents. These enable developers to connect Claude Code, Cursor, or any MCP-compatible coding agent to their org and read metadata, generate Apex, run tests, or deploy through the pipeline. The consumer is a developer building software.
• MCP tools for business agents. These enable users to access Salesforce capabilities from any MCP-compatible client: including Slack, ChatGPT, and Claude, among others. These MCP tools also allow agents to access Salesforce capabilities autonomously. The consumer is an agent serving an end user.

Both kinds of MCP tools share the same open surface and the same trust layer. The difference is who’s calling and why. Headless 360 covers both, and both have implications for the expertise you’ve built.

Headless 360 changes how the platform can be consumed. Coding agents can now reach into your org through MCP tools to build and deploy. Business agents can call the same platform to serve customers in Slack, ChatGPT, Claude, or any MCP-compatible client. The Salesforce browser-based UI is one surface among many..

How software is built, delivered, and used is changing all at once

Agentic AI is changing three things simultaneously.

How software is written. Agents are becoming the development team. The first draft of an Apex class, an LWC, a test suite, or an Agentforce agent arrives in seconds. Your job shifts from writing code to specifying intent, evaluating output, and deciding what fits your existing system design.

How quickly it is delivered. Implementations compress from months to days. When an agent can execute against a development org, with human review gates before anything reaches production, the bottleneck moves from execution to clarity of intent.

How it is used. Humans will use Salesforce from anywhere, not necessarily the Salesforce UI. A sales rep gets a customer summary in Slack. A support agent resolves a case in Teams. And increasingly, the consumer isn’t a human at all; it’s a business agent reasoning over your data. The destination isn’t a Lightning Experience tab. It’s wherever the work is already happening.

These three changes are happening simultaneously, and they put pressure on the platform itself. Headless 360 is the platform shift designed to address all three at once.

In addition to these three core dimensions, Headless 360 also changes how governance is enforced and how you think about channel strategy. When the UI is no longer the primary surface, you can’t rely on a mix of UI constraints and schema rules for governance; instead, full schema-level enforcement (via validation rules, your sharing model, and Apex) is required. And rather than building per-channel UIs (for Lightning, mobile, and community, for example), with Headless 360 you define a capability once and let it render wherever it’s called, including Slack, ChatGPT, mobile, or web.

What Headless 360 actually is

Headless 360 makes every major Salesforce capability openly composable by agents, not just by code paths a human developer wrote in advance. The full surface, including 60+ MCP tools, 30+ coding skills, 4,000+ existing APIs, and 220+ CLI commands, is accessible to any authenticated caller that your trust layer authorizes.

This isn’t new territory for Salesforce developers. You’ve been building headless for years. This includes Experience Cloud sites with React frontends, Node.js apps over REST APIs, and mobile apps via the Mobile SDK. What’s new is that AI models can now dynamically discover, use, and compose capabilities at runtime, without custom integration code written in advance for each one. 

When we say “openly composable by agents” the openly matters. Openness is the default posture. Governance is what makes it safe.

Headless 360 in practice

The capabilities Headless 360 unlocks aren’t abstract. Here’s what they look like in practice. 

Build with any coding agent

The 60+ MCP tools and 30+ preconfigured coding skills give any compatible coding agent live access to your org. Agentforce Vibes 2.0 brings that natively inside Salesforce, but the MCP surface is the same regardless of which agent you choose.

Here is a typical session: your coding agent connects to a scratch org via MCP, reads the object model, scaffolds an Apex service class with governor-limit-aware test coverage, and pushes it through your DevOps pipeline. Same deployment gates, same quality checks, same review process as code written by hand. The pipeline doesn’t care who initiated it. It cares whether the gates pass.

The platform doesn’t privilege one agent over another. Your org’s capabilities are the constant. The tooling around it is your choice. For more on the MCP tools and how they work, see our post Introducing MCP Support Across Salesforce.

Render in any UI framework

Headless decouples capability from rendering. In practice, this means the platform no longer constrains your UI framework. A clear example of this is multi-framework support.

With multi-framework support, React developers can now build on Salesforce using the same patterns they already know, with no requirement to use LWC. A front-end engineer who’s never touched Salesforce can build a governed, data-connected application using familiar tools, because the platform adapts to their stack.

That hiring constraint where you needed someone who knew LWC or Aura? It’s no longer a hard constraint. The platform meets developers where they already are.

Deploy on any surface

The Headless Experience Layer is a new runtime that decouples capability definitions from their rendering surface. You define a UI fragment and the Headless Experience Layer (HXL) handles rendering it as a Slack block, a mobile card, a ChatGPT response, or a voice interaction. Business logic, data, and permissions stay separated from the screen, so you define intent once and render natively everywhere, including Slack, mobile, ChatGPT, Claude, Teams, or any MCP-compatible client.

This is where the two MCP lanes start to converge. The same openness that lets a coding agent build against your org will also let a business agent serve your customers from it. Today, the build-time surface is mature. The runtime surface already supports straightforward use cases, such as a support agent pulling a case summary inside a Slack thread. The broader vision is that the same capability can be delivered across surfaces such as voice interactions or partner mobile apps, and that ultimately capabilities can be made available on any surface.

Protect with built-in governance

Headless doesn’t mean ungoverned. Governance is what makes it safe to build with any coding agent, render in any UI framework, and deploy on any surface. 

When a coding agent pushes an Apex class, it goes through the same validation, tests, and deployment gates as code written by a human. When an agent queries customer data through MCP, it hits the same sharing rules and field-level security as a user in Lightning.

Four things are enforced on every API call, every MCP tool invocation, and every CLI command:

• Identity. The agent acts as a specific user, not an anonymous caller. Permissions are scoped to that identity.
• Access. Sharing rules, field-level security, and permission sets enforce what the caller can see and do.
• Invocation scope. The agent can invoke only those tools and actions that have been explicitly exposed.
• Governance. Validation rules, triggers, approval chains, and governor limits all fire regardless of entry point.

The platform is open about what can be accessed. It is not open about who can access it, or how. That’s what makes it safe for openness to be the default posture.

Why most agentic prototypes don’t reach production

If you’ve tried to ship an agent, you’ve likely encountered this problem. The demo works. The stakeholder asks a question that breaks it. For example:

• “Will it respect the sharing rule on this object?”
• “What happens if the user doesn’t have permission to update that field?”
• “How does it know which approval policy applies?”

The LLM alone is not enough. The hard part is everything around it: business context, identity-aware permissions, policy enforcement, and the operational guarantees that make a system safe to run autonomously.

That gap is exactly what the Salesforce platform fills. The context an agent needs didn’t show up because someone wrote a clever prompt. It accumulated over years, in your data model, your validation rules, your sharing architecture, your trigger framework. Headless 360 makes that platform accessible to agents through a governed surface. You don’t rebuild context, permissions, or policy for your agents. They inherit it.

Testing is part of this too. Testing agents is different from testing deterministic code. You’re evaluating whether an agent’s reasoning led to an acceptable outcome across a distribution of inputs. Session tracing, custom scoring evals, and the Agentforce Testing Center are how you build confidence that an agent does the right thing in production. The discipline is familiar if you’ve built test suites for complex Apex, but the techniques are new.

What comes next

Headless 360 ships with MCP tools for coding and business agents, coding skills, multi-framework support, and the Experience Layer. That’s its surface. What makes it work is everything underneath: the state, the governance, the accumulated business logic of a platform you already know.

On the Salesforce Developer Blog and YouTube, we’re going deep on every building block, including skills for coding agents, multi-framework walkthroughs, trust and governance deep dives, testing and observability patterns, and more. Follow along and tell us where to go deeper.

The platform is open. Build on it.

Related Reading

• The Future of the Salesforce Developer in the Agentic AI Era
• Introducing Salesforce Headless 360
• Agentforce Vibes 2.0
• Headless Experience Layer
• Salesforce Multi-Framework
• Agentforce Labs
• Open Source Agentforce Skills

About the Author

Rene Winkelmeyer leads the Developer Advocacy team at Salesforce. His team focuses on Agentforce, Data 360, and the Salesforce Platform. In his spare time, you might find him still coding on GitHub. Follow Rene on LinkedIn.

The post What Salesforce Headless 360 Means For Developers appeared first on Salesforce Developers Blog.

Picture your customer rolling out a Flexcard for quick account overviews. It’s looking great on desktop, but on mobile? Actions don’t fire, data doesn’t render, and users bounce in frustration. These aren’t rare moments; they’re everyday headaches that slow deployments, breaking trust. End-to-end (E2E) testing fixes this mess by mimicking real journeys, so you can catch issues early and deploy with confidence.

Why E2E testing matters for Omnistudio

So, why do we need to test the entire journey rather than just checking if a button works? Testing the full user journey is critical because Omniscripts, Flexcards, and Data Mappers interact across boundaries where unit tests cannot validate the complete process. E2E testing plays out the full story of what a real user does, from start to finish across your components, like a demo of an actual customer journey. 

E2E testing also helps you:

• Simulate full user journeys across Omnistudio components: E2E testing plays out that whole flow, just like a real person clicking through components, spotting weird hiccups along the way.
• Catch integration issues early for partners building solutions: E2E grabs those sneaky spots where Data Mappers don’t feed data right into an Omniscript, saving you from frantic fixes right before demo day.
• Reduce post-go-live bugs: E2E irons out production surprises, reducing post-deployment defect tickets for your teams, giving you greater confidence in deployments.
• Validate real-world flows to record creation: Unit tests poke single buttons (like does this button click? Does that data pull?). E2E runs the full race, like submitting a lead form, watching it zip through conditions, and landing as a shiny new record in Salesforce.
• Find the real problem: When tests flake, E2E pinpoints the issue past the pretty interface and discovers whether or not the backend logic is actually the part causing the crash.
• Confirm that the handoff works: Picture Omniscript passing data to a Flexcard. E2E checks that the pass doesn’t drop, enabling easy jumps between your UI pieces.
• Manage your own path: Users don’t always go straight. E2E tests the sunny “submit and succeed” path plus detours like errors or save-for-later resumes, covering all those branching stories.

High risk components to test first

When figuring out where to focus your testing energy, it helps to know which parts of the system are most likely to break. Based on what teams see in the real world, here are the high-risk areas you need to watch.

Omniscripts account for approximately 50% of reported Omnistudio UI bugs, making them the highest-priority target for E2E testing. Because this is the layer the user interacts with directly and is also most visible, it typically receives the highest number of reported bugs. They juggle steps, conditions, inputs, and data swaps with Data Mappers all in one go. Mess up here, and your whole customer journey, like a service request form, grinds to a halt.

Next is Flexcards because these cards are used to display critical data and handle user actions, and any glitch here is immediately obvious to the user. 

Finally, we have Data Mappers. If mappings fail (say, wrong field names or null values), Omniscripts starve for information, also breaking Flexcards downstream.

Note: All data presented above is derived from internal testing.

Tools for Omnistudio test automation: UTAM, Playwright, and Selenium

Automation sounds cool, but here’s the headache: Omnistudio pieces shift a lot. You might spend days building a perfect test script, and it runs beautifully, until the next release drops. Suddenly, everything breaks. Why? The main culprit here is dynamic element IDs. Because Omniscripts and Flexcards are built on Lightning Web Components (LWC), they sit inside a Shadow DOM. So your usual CSS or XPath selectors become fragile and start failing whenever Salesforce moves with seasonal updates. It breaks everything at the backend. One day your test clicks Submit just fine, and the next, it hunts for a button that moves and your whole pipeline stalls.

To solve this problem, Salesforce created the UI test automation model (UTAM), a proprietary tool designed specifically for LWC in Omnistudio. Omnistudio components are wrapped in Shadow Roots (that’s the Shadow DOM), which blocks standard Selenium selectors like CSS or XPath from reaching elements reliably, especially after Salesforce updates.

<!-- Source: https://mvnrepository.com/artifact/com.salesforce.utam/salesforce-pageobjects -->
<dependency>
    <groupId>com.salesforce.utam</groupId>
    <artifactId>salesforce-pageobjects</artifactId>
    <version>12.0.0</version>
    <scope>compile</scope>
</dependency>

Instead of relying on brittle selectors in scripts, UTAM uses JSON-based page objects. When a button’s location or structure changes in an Omnistudio update, you just update the JSON metadata once, and all your tests are instantly back on track. It creates a stable layer and lets scripts identify UI components consistently, no matter what changes underneath.

Choosing between UTAM, Playwright, and Selenium

Instead of relying on fragile identifiers, a smart move would be to grab the right tools that don’t flake. Use a combination of industry-standard tools and Salesforce-specific frameworks. Here’s when to use what:

• UTAM: Best for long-term maintenance and Salesforce-native components, giving you those stable JSON selectors that survive Omnistudio updates.
• Playwright: Playwright is best for speed and headless CI/CD pipelines. Fire it up without a visible browser to debug fast across browsers. 
• Cucumber with Selenium: Cucumber with Selenium is best for business stakeholder sign-off (BDD). You write tests in plain English and your team reads and approves it.

Launch with tweaks like test parameters (sandbox mode? Slow it down?). Then poke issues using element properties. Is it visible? Enabled? That’s how you spot and squash the real culprits without endless rewrites.

Testing scenarios by Omnistudio component

Now that we’ve covered the hurdles, let’s get practical: what exact scenarios should you click, check, and validate in your Omnistudio flows? Since Omnistudio is made up of different building blocks, we need to look at them individually. Here are the recommended testing scenarios to keep your application running smoothly.

These are the must-hit spots to make sure everything hangs together for real users.

Omniscript testing

These are your flow bosses, so test the moves that users make every day.

• Check step transitions & logic: Don’t just check if the Next button works. You need to validate the conditional visibility. This is the if/else logic, if a user selects Option A, does the form show them the correct follow-up question? If they select Option B, does it take them down the alternative path?
  
  
• Validation rules: Try to break it. Enter the wrong date format or leave a required field blank. Does the system stop you with a helpful error message (validation failure), or does it let you proceed and crash later?
  
  
• Save and resume: This is a big one. For long applications, users might not finish in one sitting. You must test the “Save for Later” functionality to ensure that their data is actually saved and can be resumed exactly where they left off without data loss.
  
  
• The ID trap: When automating these tests, avoid using dynamic IDs generated by the browser as these change frequently. Instead, use data-testid or stable CSS selectors. This keeps your test from breaking every time Salesforce updates the platform.
  
  

Flexcard testing

If Omniscript is the form, the Flexcard is the dashboard that needs to look sharp and act right. It displays data and offers quick actions.

• Validate data rendering: First, perform simple visual checks. Is the data showing up? Whether it is static info or contextual data pulled from the system, it needs to render correctly on the screen.
  
  
• Action buttons: Flexcards aren’t just for looking, they have buttons. Test these actions specifically. Does clicking the button successfully launch the correct Omniscript or navigate the user to the right page?
  
  
• Conditional states: Just like Omniscripts, Flexcards can change based on data. Test these conditional states, such as hover effects or expanded details, to ensure that the card looks different when it is supposed to.
  
  
• Selectors: Stick to application programming interface (API) name–based selectors for your automation to keep things stable. They stay reliable when Salesforce tweaks the UI.

Data Mapper testing

Now we are moving backstage. Data Mappers are responsible for moving data in and out of Salesforce. Even if the UI looks fine, a broken Data Mapper means the process fails.

• Test separately: You don’t always need the UI to test these. Isolate them to see if they work on their own since they’re data pipes.
  
  
• Input and mappings: Check the input payload correctness. If you send data in, does it map to the correct fields in the database?
  
  
• Edge cases: What happens if a field is missing or comes through as null? You need to test these edge cases to make sure that the Data Mapper doesn’t just crash when the data isn’t perfect.
  
  

Integration Procedures (IPs) testing 

Omnistudio’s Integration Procedures is like an engine room that handles multiple steps and actions at once.

• Orchestration sequence: Verify that the sequence fires in the right order without skips. Does the Integration Procedure call the Data Mapper, then the external API, and then send the email?
  
  
• Error branching and timeouts: It’s critical to test system failures.” What happens if an external service takes too long to respond (timeout handling)? Does the IP handle the error gracefully, or does the whole screen freeze?
• Mock services: In your lower testing environments (like sandbox), use mock services to simulate external responses. This lets you test the logic without relying on (or waiting for) real-world third-party systems.

Pretesting checklist for Omnistudio 

Before you even write your first test script or click Run, there are some best practices that you should keep in mind. Testing isn’t just about finding bugs; it’s about making sure that the design actually works for the human using it.

Here is a checklist of what to consider before you start testing.

Verify backend object updates

Don’t get too distracted by the flashy buttons just yet. Start with the win you want. Your primary goal is to verify that the business actually got what it needed. We call this testing the “happy path,” the core journey where everything goes right.

Ask yourself: When the user hits Submit, did the data actually land where it was supposed to? You need to confirm that the backend S-objects or business objects were updated correctly. If the form looks great but the database is empty, the test has failed.

Test dynamic UI state changes

Omnistudio interfaces are dynamic. They change based on who is looking at them. For example, a Flexcard might display different contextual data depending on the customer.

Before testing, verify that the UI visibility logic is sound. Does the screen state change correctly when new info is added? Are buttons going gray when they’re not ready? You need to ensure that the interface is displaying the right information at the right time.

Validate responsive UX

Step back and think about the user: does the flow feel natural on a phone or desktop? Test responsive tweaks and little touches like smooth transitions — no janky jumps that make users ditch the app mid-task. The Omniscript is the “face” of your application, and because it is the part that users touch, it usually receives the highest number of bug reports.

However, remember that a bad UX isn’t always a code error, sometimes it’s just a confusing design. When planning your tests, think about the flow. Is it intuitive? Since the root cause of a UI bug is often actually a backend configuration issue, ensuring a smooth UX means making sure that the backend supports the frontend easily.

Test error messaging paths

What happens when things go wrong? Your testing plan needs to cover more than just success stories. You must account for “unhappy paths,” such as validation failures where a user enters the wrong data.

You also need to verify how the system handles big failures, like an Integration Procedure timeout or an Apex exception. Does the user get a helpful error message, or does the screen just freeze? Check that success pop-ups say things like “Claim submitted, thanks!” and errors spell out next steps, like “Missing phone number, add it here,” instead of vague tech jargon.

Accessibility verification

Don’t leave anyone behind — this is non-negotiable. When designing and testing Omniscripts, you must consider accessibility because the UI needs to work for everyone.

Your tests should ensure that the application caters to all customers, including those who may be visually impaired. Test for screen readers announcing fields correctly, keyboard-only navigation through your Flexcards, and color contrasts that pop for all eyes.

Conditional navigation outcomes

Finally, where does the user go next? Omnistudio relies heavily on conditional logic, basically if/else statements that send users down different paths based on their choices.

You need to verify these alternative paths. If a user clicks Save for Later, does the system actually let them resume later without losing data? If they answer Yes to a specific question, does the navigation direct them to the correct follow-up screen? Make sure that every road leads to the right destination.

Next steps

There you have it. Tackling Omnistudio testing in the simplest way possible without it being a nightmare of flaky scripts and hidden bugs. Start with your highest-traffic Omniscript. Write one UTAM page object for its first step, validate a single field input and step transition, and run it against your sandbox. Once that passes reliably across two Salesforce releases, expand coverage to the scenarios listed above. Build rock-solid flows with clear messaging and confident deployments that your customers love.

Resources

Video: FlexCards and OmniScripts | Salesforce Industries 

Trailhead: Omnistudio Development Essentials 

Trailhead: Omnistudio Omniscript Fundamentals

Video: Build Low-Code Digital Experiences with All-New OmniStudio  | TDX Bengaluru 

About the authors

Anjali Gupta is a Senior Product Manager at Salesforce who is specialised in horizontal cloud and platform. She is focused on Omnistudio roadmap and strategies ensuring customer growth and success. Follow her on LinkedIn.

Payal Verma is a Content Marketing Analyst at Salesforce with over four years of professional experience in product, brand, and content marketing. She has worked across both B2B and B2C markets, developing and executing content strategies for a wide range of formats, including blogs, social media, scripts, eBooks, and guides. Follow her on LinkedIn.

The post Conduct End-to-End Testing for Salesforce Omnistudio-based UIs appeared first on Salesforce Developers Blog.

Custom Lightning types (CLTs) meet this need. They let you render Lightning Web Components (LWC) directly within Agentforce experiences in Lightning Experience, Enhanced Chat v2, and Experience Builder. You can collect structured input through a custom form and display results as rich, styled cards or in your own custom-designed user interface. CLTs are also the foundation of Headless Experience Layer, announced at TDX 2026, which extends rich agentic UI beyond Salesforce — to Slack, ChatGPT, and more. Define Once, Deploy Anywhere, Secure Everywhere — that’s the headless experience layer vision. Building with CLTs today means you’re already working with the primitives that power the next generation of multi-surface agentic experiences.

This post walks through how to work with CLTs in Agent Script to render a rich experience within Agentforce. All code examples come from the Agent Script Custom Lightning Type example recipe.

What are custom Lightning types in Agentforce?

Custom Lightning types create a bridge between your Agent Script, your actions backed by Apex or flows, and your LWC components. They override the default text-based UI with custom LWC components for both input and output.

Below is an example of custom Lightning types in action within the Agentforce experience.

The connection flows through three layers:

• Agent Script declares which action parameters need custom UI
• A Lightning Type Bundle maps each parameter type to an Apex data shape and an LWC component
• An LWC renders the user interface inside the conversation

This three-layer wiring enables you to keep a clean separation of concerns. Your Agent Script handles orchestration, Apex handles the data shape definition and the business logic, and LWC handles the final user experience.

The following diagram shows how a custom Lightning type is mapped with Agent Script and LWCs.

The following sections describe how to build and wire this connection step-by-step.

Step 1: Prepare and deploy your Apex and LWC 

Defining the Apex data shape

Each CLT needs an Apex class that defines the data structure. Use inner classes within your service class, with each field annotated with @InvocableVariable. The Lightning Type Bundle references these inner classes as the schema source.

public class CaseInput {
    @InvocableVariable(label='Subject' required=true)
    public String subject;

    @InvocableVariable(label='Priority')
    public String priority;

    @InvocableVariable(label='Description')
    public String description;
}

One important detail: the wrapper class field names must exactly match the action parameter names from your Agent Script. If your action input is called case_data, the request wrapper field must also be named case_data. A mismatch here silently breaks the entire CLT connection.

View the code: See the full CaseSubmissionService.cls for the complete Apex implementation including the request/response wrappers.

Building the editor and renderer LWC

The editor LWC collects user input inside the chat. Two things make it work with Agentforce: the meta XML must target lightning__AgentforceInput with a targetType matching the CLT name, and the component must dispatch a valuechange event whenever the user modifies the form.

 <target>lightning__AgentforceInput</target>
 <targetType name="c__caseInput" />

The valuechange event payload field names must match the Apex CaseInput class fields. The platform listens for this event to capture and forward the form data to your Apex action.

Here is the simple example snippet showing the valuechange event in practice:

import { LightningElement } from 'lwc';

export default class CustomCaseForm extends LightningElement {
    // Local state variables for the form
    subject = '';
    priority = 'Medium';
    description = '';

    // Handler triggered when the user types in the Subject input
    handleSubjectChange(event) {
        // 1. Update the specific field that changed
        this.subject = event.target.value;

        // 2. Dispatch the FULL state of the form
        this.dispatchFormState();
    }

    // You would have similar handlers for Priority and Description...

    // Centralized method to dispatch the complete current state
    dispatchFormState() {
        this.dispatchEvent(
            new CustomEvent('valuechange', {
                detail: {
                    value: {
                        // ALWAYS include all fields to match the Apex CaseInput class
                        subject: this.subject,
                        priority: this.priority,
                        description: this.description
                    }
                }
            })
        );
    }
}

The renderer LWC displays the result card after the action completes. It targets lightning__AgentforceOutput with a sourceType (not targetType). The component receives the full result object via @api value and uses getters to render the fields with Salesforce Lightning Design System styling.

<target>lightning__AgentforceOutput</target>
<sourceType name="c__caseResult" />

View the code: See the full caseInputEditor and caseResultRenderer components in the repo.

Wiring Lightning type bundles

The Lightning Type Bundle is a folder containing JSON configuration files. The schema.json file points to your Apex inner class using $ syntax. For example, c__CaseSubmissionService$CaseInput references the CaseInput inner class.

{
    "title": "Case Input",
    "lightning:type": "@apexClassType/c__CaseSubmissionService$CaseInput"
}

A second file tells the platform which LWC component to render. Input types use an editor.json file. Output types use a renderer.json file. The "$" root key means “override the UI for the entire type”.

{
    "editor": {
        "componentOverrides": {
            "$": { "definition": "c/caseInput" }
        }
    }
}

View the code: See the complete Lightning Type Bundle files in the repository

Step 2: Create the agent action asset

The GenAiFunction is the metadata layer that registers your action with Agentforce. Without it, Agentforce cannot resolve your CLT bindings. Every CLT-based action needs a corresponding GenAiFunction in the genAiFunctions folder.

The function metadata XML points to your Apex invocable class:

<GenAiFunction xmlns="http://soap.sforce.com/2006/04/metadata">
    <developerName>Submit_Case</developerName>
    <invocationTarget>CaseSubmissionService</invocationTarget>
    <invocationTargetType>apex</invocationTargetType>
    <masterLabel>Submit Case</masterLabel>
</GenAiFunction>

Alongside this XML, you define input and output schema JSON files. These schemas declare the lightning:type for each parameter, which is how the platform knows to look up your Lightning Type Bundle.

The input schema marks case_data as a user input with the CLT type c__caseInput:

{
    "properties": {
        "case_data": {
            "lightning:type": "c__caseInput",
            "copilotAction:isUserInput": true
        }
    }
}

The output schema marks case_result as displayable with the CLT type c__caseResult:

{
    "properties": {
        "case_result": {
            "lightning:type": "c__caseResult",
            "copilotAction:isDisplayable": true
        }
    }
}

See the full GenAI Function files in the repository.

You can build the Agent action metadata directly in the Salesforce user interface. 

To do this, navigate from Setup to Agentforce Assets, then select Actions and create a new agent action by following below steps.

1. Setup → Agentforce Assets → Click on Actions → Click on New Agent Action
2. Fill in the agent action details like Inputs and Outputs description and data types.
3. Ensure you are setting up the Input Rendering and Output Rendering with the right custom Lightning types

Step 3: Define the action in Agent Script

While the following sections cover action definition via metadata in detail, the Agentforce Builder UI enforces proper naming constraints automatically and is the recommended starting point for most teams.

Everything hinges on the action definition in your Agent Script. Two properties control CLT rendering: complex_data_type_name links a parameter to a Lightning type, and is_user_input or is_displayable tells the platform to render the custom component.

actions:
   submit_case:
      inputs:
         case_data: object
            is_user_input: True
            complex_data_type_name: "c__caseInput"
      outputs:
         case_result: object
            complex_data_type_name: "c__caseResult"
            is_displayable: True
      target: "apex://CaseSubmissionService"
      source: "Submit_Case"

Notice the source property at the bottom. This is a critical piece that connects Agent Script to an Agentforce action (represented as GenAiFunction in the metadata as discussed in step 2). The value “Submit_Case" must match the developer name of a GenAiFunction metadata file in your project.

Triggering the CLT editor in Agent Script

One detail that is easy to miss: your Agent Script subagent instructions must include the user_input keyword when calling the action. This tells the platform to render the CLT editor component instead of collecting input through plain text.

reasoning:
   instructions: ->
      | Call {!@actions.submit_case} action's user_input tool to collect the case details.

Without this phrase, the platform falls back to text-based input collection. The user_input keyword is what activates the entire CLT editor rendering pipeline.

Important note: In Agent Script the subagent’s action name and the subagent reasoning action name should be exactly the same.

View the code: See the full instructions for the Agent Script in the repository.

The alignment checklist

CLTs require precise naming across multiple files. If any link in the chain breaks, the platform silently falls back to the default text UI with no error message. The following table shows what must stay aligned:

Check these connections first when debugging. The silent fallback behavior makes misalignment hard to spot.

Conclusion

Custom Lightning types bring the power of Lightning Web Components into Agentforce conversations. You can collect precise, validated data through custom forms and present results in rich, branded cards, all without leaving the Agentforce experience.

The key pieces are the Agent Script action definition and the action in the Agentforce assets, the Lightning Type Bundle, and the LWC components. Each layer has a specific job, and the naming alignment across all four layers is what makes the whole system work.

This pattern opens up new possibilities for building enterprise-grade agent experiences. Forms with dropdowns and validation, structured result cards with conditional styling, and multistep workflows can all be rendered inline within the conversation.

The complete working example is available in the Agent Script Recipes repository under the customLightningTypes recipe. Clone the repo, deploy to a scratch org or Developer Edition org, and start building your own CLT-powered Agentforce agents.

Resources

• Lightning Types Developer Guide
• Agent Script Recipes Sample App
• Agent Script Documentation

About the authors

Mohith Shrivastava is a Principal Developer Advocate at Salesforce with 15 years of experience building enterprise-scale products on the Agentforce 360 Platform. Mohith is currently among the lead contributors on Salesforce Stack Exchange, a developer forum where Salesforce Developers can ask questions and share knowledge. You can follow him on LinkedIn.

Parvinder Singh is a Senior Forward Deployed Engineer at Salesforce with deep expertise in Agentforce and Agent Script, specializing in building intelligent, customized agent experiences for enterprise customers. He is passionate about sharing developer insights with the community and bringing practical, field-tested patterns to life through hands-on content.

The post Use Custom Lightning Types in Agent Script for Rich Agent UI appeared first on Salesforce Developers Blog.

As a Salesforce developer, you know that a new building experience usually means changes under the hood. To support this faster, safer way of working, the underlying metadata had to evolve. This post walks through the new developer workflow, why the metadata changed, and how to structure your packages for deployment.

The new authoring workflow: from script to metadata

To understand the metadata changes, it helps to understand the new mental model for building agents. The new Agentforce Builder introduces a clear separation between your “intent” (what you want the agent to do) and the engine’s “execution” (the active metadata).

Here is how the lifecycle works:

1. Write and build: You author your agent using the Agentforce Builder UI or directly via an Agent Script. This human-readable script is saved as a single .agent file within a new AiAuthoringBundle metadata type, representing your agent’s configuration. At this stage, your work is a draft.
2. Iterate and preview: You test your draft using preview modes (like Simulation mode, which safely isolates your tests from org data).
3. Publish: When you are happy with the draft, you commit your version. This is the crucial moment. It is only during commit that the platform translates your .agent script into the active Bot and GenAiPlannerBundle metadata that is actually used to run your agent.

Why the metadata changed: bundling local assets

So, why did we change the GenAiPlannerBundle metadata structure for this new builder? The answer comes down to isolation and deployment reliability.

Historically, Agentforce assets were global. If you modified a shared subagent for one agent, you triggered a “global ripple” that instantly impacted every other agent using that subagent. To solve this, Salesforce introduced Local Assets (including local subagents and local actions), which clone a global asset and anchor it specifically to one agent version. Once local, you can edit it safely without breaking anything else.

While Local Assets have been available for a while, the GenAiPlannerBundle metadata needed to be updated to fully support them in CI/CD pipelines. Previously, agent metadata was distributed across metadata types. The main change in the new GenAiPlannerBundle is bundleization. In short, we restructured the metadata to ensure that all dependent agent assets related to any given version are deployed and available in one centralized folder structure. This prevents deployment errors and ensures your agent has everything it needs to function exactly as it did in preview.

Under the hood: the new metadata structure

Instead of scattered files, the directory structure now cleanly encapsulates everything specific to each agent version.

AiAuthoringBundles is a directory that contains all the design-time artifacts for the agent. The bundle supports multiple versioned subdirectories (e.g., AgentName_1, AgentName_2, etc.), each with its own .agent file and .bundle-meta.xml descriptor. These correspond to different lifecycle states such as draft and committed versions of the agent. Within each version:

• The .agent file holds the agent’s configuration written in Agent Script: name, label, description, system instructions, subagent definitions, reasoning instructions, variables, conditionals, and tool/action references.
• The metadata descriptor (.bundle-meta.xml) declares the bundleType (e.g., AGENT) and the target agent version it points to.

Bot contains information common to all versions of the agent, such as the agent type and useful settings like whether to log private data. It also holds agent-level context variables, which are distinct from the conversation variables that live inside each BotVersion. BotVersion details include conversation variables, welcome message, and transfer conversation message.

GenAiPlannerBundle contains all data relevant to each published version of an agent. Within each version you can find:

• .genAiPlannerBundle, which is the main metadata file containing the agent’s runtime configuration: subagents, instructions, actions, and orchestration logic.
• agentGraph, a .json file encoding all transitions and conditions between subagents.
• agentScript, an encoded copy of the version agent script. This is a snapshot kept for sync-detection purposes, so Agent Builder can tell the user if the script is out of sync with the published/committed metadata.
• plannerActions, agent-level actions (not tied to any specific subagent).
• localActions, subagent-scoped actions, nested under their subagent folder. The input/schema.json and output/schema.json files define the typed parameters for each action.

Note: GenAiPlannerBundle versions are auto-incremented in commit order, so they won’t necessarily match AiAuthoringBundle version numbers.

Remember that both Bot and GenAiPlannerBundle metadata are created automatically when a version is committed, and AiAuthoringBundle, agentScript, and agentGraph are only present on the new Agentforce Builder agent metadata.

Example: GenAiPlannerBundle XML

When you look at the XML, you’ll see it now clearly reflects these localized subagents and actions:

<GenAiPlannerBundle>
   <description>New agent description</description>
   <localTopicLinks>
       <genAiPluginName>Retrieve_data_from_the_Knowledge_Base_16jxx0000001234</genAiPluginName>
   </localTopicLinks>
   <localTopics>
       <fullName>Retrieve_data_from_the_Knowledge_Base_16jxx0000001234</fullName>
       <description>Use the retriever action</description>
       <pluginType>Topic</pluginType>
       <masterLabel>Retrieve data from Knowledge Base</masterLabel>
       <genAiPluginInstructions>
           <description>You are an AI Agent.</description>
           <sortOrder>1</sortOrder>
       </genAiPluginInstructions>
       <localActionLinks>
            <functionName>File_test_retriever_179xx0000001234</functionName>
       </localActionLinks>
       <localActions>
           <fullName>File_test_retriever_179xx0000001234</fullName>
           <invocationTarget>File_test_retriever_1234</invocationTarget>
           <invocationTargetType>apex:testRetriever</invocationTargetType>
           <source>File_test_retriever</source>
       </localActions>
   </localTopics>
   <plannerType>AiCopilot__ReAct</plannerType>
</GenAiPlannerBundle>

Each <localTopics> block defines a subagent’s full configuration: its unique API name, description, plugin type, deterministically ordered instructions, and all the local actions available to it. Optionally, a reference to the source subagent may also be present.

Each <localActions> block defines the action’s name, master label, invocation target and type, and optionally a source reference to the global action it was cloned from. Additional UX-related settings, such as confirmation behavior and loading text configuration, may also be included.

Sample package.xml with metadata of new model

To successfully retrieve and deploy your agents built with the new Agentforce Builder, ensure your package.xml includes the new bundle types. Below is a sample manifest designed for the Spring ’26 metadata structure.

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>GenAiFunction</name>
    </types>
    <types>
        <members>*</members>
        <name>Bot</name>
    </types>
    <types>
        <members>*</members>
        <name>GenAiPlannerBundle</name>
    </types>
    <types>
        <members>*</members>
        <name>GenAiPlugin</name>
    </types>
    <types>
        <members>*</members>
        <name>AiAuthoringBundle</name>
    </types>
    <version>66.0</version>
</Package>

Note: This manifest uses API version 66.0, which is required to support GenAiPlannerBundle and the new agent metadata types in this example.

Developer tips for the new Agentforce Builder

Here are two ways to take advantage of development lifecycle improvements enabled by this new architecture:

• Use human-readable script files to streamline code reviews. In the legacy Agentforce Builder world, reviewing agent changes meant comparing complex, scattered XML files in your pull requests. Now, you can compare the human-readable .agent script files. This makes peer reviews significantly faster and easier to understand.
• Use AiAuthoringBundle to simplify CI/CD. For most pipelines, you can keep just the AiAuthoringBundle in your source control. When you need the agent in a new org, you deploy it, version commit to generate the runtime metadata, and finally activate it. This can be done automatically using the following commands:sf project deploy start --metadata AiAuthoringBundle --target-org my-orgsf agent publish authoring-bundle --api-name MyAuthoringBundle --target-org my-org

sf agent activate --api-name MyAuthoringBundle --version 2 --target-org my-orgIf your team wants a fully automated pipeline with no manual steps, you can maintain both AiAuthoringBundle and GenAiPlannerBundle in your source control and deploy them simultaneously, achieving a committed state. The system recognizes the incoming script alongside its pre-realized metadata and skips the manual commit step entirely, so your agent is live immediately after deployment.sf project deploy start --metadata AiAuthoringBundle,GenAiPlannerBundle --target-org my-org

Conclusion

The bundleized metadata structure is what makes the isolated, version-safe authoring possible in the new Agentforce Builder. With it, your metadata is cleaner, your code reviews are easier, and your deployments are more reliable. 

Get started with Agent Script and the new Agentforce Builder by completing this Trailhead module, reading more on our blog, watching our Agent Script decoded playlist on YouTube, or registering for one of the upcoming Agentforce Builder workshops.

Resources

• Release Notes:
  • Versioning and Editing Agents
  • Test and Customize your Agents with Improved Agent Versions
• Help Docs:
  • Editing Standard Agent Action Reference Actions 
• Packaging:
  • Package Agentforce Metadata Components
  • Develop and Package Agent Templates Using Scratch Orgs 
• Metadata updates:
  • GenAiPlannerBundle
  • GenAiFunction
  • GenAiPlugin
  • GenAiPluginInstructionDef

Shreyas is a Lead Software Engineer at Salesforce AI in San Francisco and a Fellow of the Institute of Analytics (FIoA). As a lead member of the Agentforce Core Platform team, he co-designed and led the Agentforce Versioning System and Local Assets Configuration changes to bring enterprise-grade ALM to Agentforce. You can follow him on Linkedin.

Alba Rivas works as a Principal Developer Advocate at Salesforce. You can follow her on Linkedin.

The post The New Agentforce Metadata and Development Lifecycle appeared first on Salesforce Developers Blog.

Headless 360 and Salesforce Hosted MCP Servers introduce a shift from UI-first to agent-first. Every capability on the platform — data access, business logic, automation — becomes consumable through CLIs, APIs, and the Model Context Protocol (MCP), an open standard that lets AI agents discover and call tools hosted on external servers. AI agents running in Slack, Claude, ChatGPT, Cursor, or any MCP-compatible client can now reach into Salesforce and invoke your business logic directly. No login screen. No navigation. No UI at all.

In this blog post, we’ll show you how to write custom Apex business logic, expose it as a Hosted MCP Server on Salesforce, deploy the necessary metadata to configure authentication, and connect an external AI agent like Claude to invoke your logic.

What makes Salesforce Hosted MCP different

A Salesforce Hosted MCP Server is a platform-managed endpoint that exposes Apex actions, Apex REST, and external APIs as discoverable tools for AI agents through the Model Context Protocol. Unlike self-hosted MCP servers, it runs on Salesforce infrastructure handling authentication, tool discovery, and request routing without external deployment.

A Salesforce Hosted MCP tool delivers three things that no raw database can match out-of-the-box: 

• Pre-built business object graphs (e.g., Account → Opportunity → Product → Revenue) with relationships already modeled 
• A record-level sharing model that automatically scopes results to what this specific caller is allowed to see 
• Decades of accumulated business process metadata that each customer’s org has already encoded over years of operation

Example: Pipeline intelligence

The example exposes a pipeline intelligence tool built in Apex. An AI agent passes an account name, and the tool returns a complete analysis: open deals with risk levels, weighted pipeline value, product line items, and an overall health assessment.

The Apex @InvocableMethod (see docs) that powers flows and Agentforce actions now also serves external AI agents through MCP. Write the logic once; it runs everywhere.

The Apex class uses global access (required for MCP tool discovery) and structures the method as a deep module, absorbing interpretive logic so that the Agent receives insight, not raw data.

The method starts by resolving the account using fuzzy matching: trying an exact name match first, then falling back to a LIKE pattern.

global with sharing class AccountPipelineService {
    @InvocableMethod(
        label='Get Account Pipeline'
        description='Returns open opportunities with line items and computed business intelligence (risk levels, weighted pipeline, health summary) for a given account name. Supports fuzzy matching.'
    )
global static List getAccountPipeline(List requests) {
  // All private methods is invoked here..
}
private static Account resolveAccount(String accountName, PipelineResult result) {
     List accounts = [
         SELECT Id, Name, Industry, AnnualRevenue
         FROM Account
         WHERE Name = :accountName
         WITH USER_MODE
         LIMIT 1
     ];

     if (!accounts.isEmpty()) {
         result.matchType = 'exact';
         return accounts[0];
     }

     String fuzzyPattern = '%' + accountName + '%';
     accounts = [
         SELECT Id, Name, Industry, AnnualRevenue
         FROM Account
         WHERE Name LIKE :fuzzyPattern
         WITH USER_MODE
         LIMIT 1
     ];

     if (!accounts.isEmpty()) {
         result.matchType = 'partial';
         return accounts[0];
     }

     result.accountFound = false;
     result.message = 'No account found matching: ' + accountName;
     return null;
 }

}

When no account matches, the tool returns a structured response with accountFound: false and a descriptive message, giving the AI agent a clear signal to ask the user for clarification rather than failing silently.

Once the account is resolved, a single SOQL query traverses the full business object graph.

List opportunities = [
     SELECT Id, Name, Amount, StageName, Probability, CloseDate,
         Owner.Name,
         (SELECT Id, Product2.Name, Quantity, UnitPrice, TotalPrice
          FROM OpportunityLineItems)
     FROM Opportunity
     WHERE AccountId = :acc.Id
         AND IsClosed = false
     WITH USER_MODE
     ORDER BY Amount DESC NULLS LAST
 ];

Each deal is then scored for risk based on probability and proximity to close date.

private static String assessRisk(Decimal probability, Integer daysUntilClose) {
     if (daysUntilClose <= 30 && (probability == null || probability < 60)) {
         return 'High';
     }
     if (probability == null || probability < 50) {
         return 'Medium';
     }
     return 'Low';
 }

The overall pipeline health is a multi-factor assessment combining high-risk ratio and weighted conversion strength.

private static String assessPipelineHealth(
     Integer totalDeals, Integer highRiskCount,
     Decimal weightedValue, Decimal totalValue
 ) {
     if (totalDeals == 0) {
         return 'Empty — no open deals';
     }
     Decimal highRiskRatio = (Decimal) highRiskCount / totalDeals;
     Decimal conversionStrength = totalValue > 0 ? weightedValue / totalValue : 0;

     if (highRiskRatio > 0.5) {
         return 'Weak — majority of deals are high risk';
     }
     if (conversionStrength < 0.4) {
         return 'At Risk — low weighted conversion across pipeline';
     }
     if (highRiskRatio <= 0.2 && conversionStrength >= 0.6) {
         return 'Strong — high confidence, low risk';
     }
     return 'Moderate — mixed signals, review recommended';
 }

Key design decisions:

• Fuzzy matching: The tool resolves partial account names (“Acme” finds “Acme Corporation”), reducing errors for AI agents that may not know exact names.
• Computed fields: riskLevel, weightedPipelineValue, and pipelineHealthSummary are calculated inside the method. The AI agent never needs to interpret raw probabilities or close dates.
• WITH USER_MODE: SOQL queries enforce the running user’s field-level and object-level security automatically.
• Cross-object traversal: This is a single tool call that spans Account, Opportunity, OpportunityLineItem, Product2, and User.

Registering the Hosted MCP Server

With the Apex class deployed, the next step is the MCP Server Definition, the metadata that maps your Apex action to a named tool and controls how AI agents discover it.

Below is an example deployable metadata for registering the hosted MCP server. The metadata can be source controlled and CI/CD deployed alongside the Apex class.

<?xml version="1.0" encoding="UTF-8"?>
<McpServerDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Analyzes account pipeline health with deal risk scoring
    and weighted forecasts by traversing Salesforce's native business
    object graph.</description>
    <masterLabel>Pipeline Intelligence</masterLabel>
    <tools>
        <apiDefinition>
            <apiIdentifier>aa:apex-AccountPipelineService</apiIdentifier>
            <apiSource>API_CATALOG</apiSource>
            <operation>AccountPipelineService</operation>
        </apiDefinition>
        <descriptionOverride>Returns open opportunities with line items
        and computed business intelligence (risk levels, weighted pipeline,
        health summary) for a given account name.
        Supports fuzzy matching.</descriptionOverride>
        <toolName>getAccountPipeline</toolName>
        <toolTitle>Get Account Pipeline</toolTitle>
    </tools>
</McpServerDefinition>

Note: MCP Registration can also be done via Salesforce User Interface. The steps are documented in the official documentation.

Why every field here matters

AI agents don’t read your code. When an MCP client calls tools/list, the agent sees exactly four things per tool: a name, a description, an inputSchema, and an outputSchema. That’s the entire basis for deciding whether to call your tool, what to pass, and how to interpret the response.

Each metadata field controls part of that picture.

From Apex annotations to agent-readable schemas

The apiDefinition is the bridge. It references the API Catalog entry auto-created from your global class. Salesforce reads the @InvocableVariable annotations on your input and output classes and generates the inputSchema and outputSchema that agents see.

// Input class → becomes inputSchema (wrapped in an inputs[] array)
 @InvocableVariable(required=true description='The name of the Account to look up pipeline for. Supports partial matching.')
 global String accountName;

 // Output class → becomes outputSchema (nested inside a response envelope as outputValues)
 @InvocableVariable(description='Overall pipeline health: Strong, Moderate, At Risk, or Weak')
 global String pipelineHealthSummary;

 @InvocableVariable(description='Pipeline value weighted by probability — realistic expected revenue')
 global Decimal weightedPipelineValue;

The description text you write in each @InvocableVariable annotation becomes the documentation that the agent reads. Without it, the agent sees field types but not meaning. Write them with the agent as your audience for example:

• Input fields: What to provide. “Supports partial matching” tells the agent it doesn’t need an exact name.
• Output fields: How to interpret. “Negative means overdue” on daysUntilClose prevents misreading.
• Enumerated values: List them. “Strong, Moderate, At Risk, or Weak” — no guessing.

Writing an effective descriptionOverride

The descriptionOverride drives tool selection for the Agent. A good description answers three questions:

1. What does it return?  “Returns open opportunities with line items and computed business intelligence (risk levels, weighted pipeline, health summary)”
2. What input does it need?  “For a given account name”
3. Any behavioral nuances?  “Supports fuzzy matching”

Anti-patterns to avoid:

1. Too vague: A description like “Gets pipeline data” gives the agent no signal about what makes this tool different from a generic query tool. The agent is unlikely to select it when multiple tools are available
2. Too implementation-focused: A description like “Executes SOQL against Opportunity with USER_MODE” tells the agent how the tool is built rather than what it delivers. The agent needs to know what business value the tool provides, not the internal mechanics.
3. Missing input guidance: If the description does not mention that the tool expects an account name, the agent has no way to know whether it should pass an account ID, an opportunity name, or something else entirely.

Activate the MCP Servers

After deploying, verify the server appears in Setup → MCP Servers and activate it. The server must be active before any MCP client can connect.

Setting up the External Client App

For an MCP client like Claude to authenticate, an External Client App with OAuth is required. This is configured through Setup as follows:

1. Navigate to Setup → External Client App Manager → New External Client App
2. Provide a label, description, and contact email
3. Enable OAuth with the following settings:

Once saved, the Consumer Key becomes available under Settings → Consumer Key and Secret. This is the client identifier that Claude uses to initiate the OAuth flow.

Note: External Client Apps can take up to 30 minutes to become fully active after creation. If Claude’s connection fails immediately after setup, wait and retry.

Connecting Claude

Connecting Claude to a Hosted MCP Server requires a server URL and an OAuth Client ID — nothing else.

1. In Claude.ai on the web, navigate to Settings → Connectors → Add custom connector.Note this assumes you have a Claude account and you are signed in. If you are signed in you can also directly add a connector.
2. Copy the Server URL from Salesforce Setup:

• Navigate to Setup → Integrations → MCP Servers
• Click the MCP Server name (e.g., “Pipeline Intelligence”)
• Under Authentication Details, copy the Server URL

The URL follows the pattern below:

For this project, the URL is https://api.salesforce.com/platform/mcp/v1/sandbox/Pipeline_Intelligence

Note: You can also copy this from the user interface by navigating to the following: 

1. Set the Server URL in Claude by pasting the URL from Step 2
2. Paste the OAuth Consumer Key from the External Client App settings
3. Click Connect and authenticate with the Salesforce org credentials

Once connected, Claude can invoke the tool naturally:

“What’s happening with Acme’s pipeline?”

The response includes the matched account, open deals with per-deal risk levels, weighted pipeline value, product line items, and an overall health assessment — all computed by the Apex running on Salesforce, all respecting the user’s security context.

Note: If you are having issues connecting to MCP servers refer to the troubleshooting section in the official docs.

The Headless 360 shift

For Apex developers, Headless 360 is a fundamental shift in how you design code. The consumer is no longer a human clicking through a UI; it’s an AI agent that reads tool descriptions, passes structured inputs, and reasons over structured outputs.

Designing for agents means returning computed insight (not raw fields), writing precise descriptions (not UI labels), and building tools that are self-contained (not steps in a wizard).

For AI developers exploring MCP, Salesforce is a uniquely deep server: a pre-modeled business graph, governed security, and computed intelligence — not just another database behind an API.

A note on tool governance

Too many MCP tools overwhelm AI agents, they struggle to pick the right one, leading to irrelevant calls or confused responses. As more teams expose Apex logic as MCP tools, governance becomes important. The Salesforce Hosted MCP Servers Best Practices guide recommends keeping tools self-contained (each returns a useful result on its own), avoiding both over-granular tools that require prescribed sequences and over-broad tools that bundle unrelated operations. Give each tool

Get started

The complete source code for this blog post, setup scripts, and sample data are available on GitHub: headless-apex-mcp-tool. 

While this post demonstrates the connection with Claude, MCP is an open protocol. Any MCP-compatible agent — Slack, ChatGPT, or your own custom agent — can connect to the same Hosted MCP Server using the same URL and OAuth flow. Check the resources below to learn more.

Resources

• Connect MCP Clients
• External Client App Setup for MCP
• Connecting Claude to Salesforce MCP
• Hosted MCP Servers Developer Guide
• GitHub: Headless Apex MCP Tool

About the author

Mohith Shrivastava is a Principal Developer Advocate at Salesforce with 15 years of experience building enterprise-scale products on the Agentforce 360 Platform. Mohith is currently among the lead contributors on Salesforce Stack Exchange, a developer forum where Salesforce Developers can ask questions and share knowledge. You can follow him on LinkedIn.

The post Expose Custom Apex as a Hosted MCP Tool for Agents appeared first on Salesforce Developers Blog.