sfka-invocableMCP

Generic, object-agnostic invocable Apex actions (27 MCP tools) covering discovery (describe, picklists, list flows, access check, record summary), reads (read, find, count, aggregate, search, related), writes (create, upsert, update, clone, delete, undelete, validate dry-run, assign owner, change record type), intent shortcuts (log activity, close case, convert lead, post to Chatter, add note, attach file) and run flow, exposed as tools on a hosted Salesforce MCP server (McpServerDefinition = SObjectActions). The same actions are callable from Flow, Agentforce agent actions, and REST (/services/data/vXX.X/actions/custom/apex/<ClassName>).

Every action takes an objectApiName string plus records or Ids, so one deployment covers any standard or custom object without further code.

Quick start (repeatable)

scripts/setup.sh <org-alias> [--no-fixtures] [--no-eca] [--no-tests] [--no-smoke] [--assign user@example.com]

Deploys test fixtures, the 27 actions + echo flow + permission set, the MCP server definition and the External Client App; assigns SObjectActions_User; runs all 45 unit tests and the 45-check REST smoke test; prints the consumer key and the two remaining manual steps (activate the server in Setup, grant object CRUD/FLS). Idempotent; verified on orgs with and without Enhanced Notes / record types.

Alternative: unlocked package SObject Actions MCP (Apex + flow + permission set; scripts/package.sh install <org> <04t> also deploys mcp/ and eca/, which Salesforce does not allow in packages). Also scripts/scratch.sh (fresh scratch org, full install) and .github/workflows/validate.yml (check-only deploy + tests + doc drift on PRs; needs secret SF_AUTH_URL).

Repo layout: force-app/ (packageable: classes, flows, permissionsets), mcp/ (McpServerDefinition), eca/ (External Client App), test-fixtures/ (optional).

Related MCP server: Salesforce-Hosted-Custom-Mcp-Server

Documentation map

Contents

1. Components

2. Deploy

3. Enable the MCP server

4. Common conventions

5. Tool reference

   • createRecords

   • readRecords

   • updateRecords

   • deleteRecords

   • upsertRecords

   • findRecords

   • describeObject

   • searchRecords

   • relatedRecords

   • countRecords

   • undeleteRecords

   • checkAccess

   • cloneRecords

   • validateRecords

   • aggregateRecords

   • runFlow

   • assignOwner

   • changeRecordType

   • picklistValues

   • logActivity

   • closeCase

   • convertLead

   • postChatter

   • addNote

   • attachFile

   • listFlows

   • recordSummary

6. Calling from Flow

7. Calling from REST

8. Security model

9. Limits and bulk behavior

10. Error catalog

11. Testing

12. Extending

Tool families

Full input/output reference for each: docs/TOOLS.md.

Components

All source lives under force-app/main/default/.

API version: 67.0 (sfdx-project.json). Requires an org where hosted MCP servers and McpServerDefinition metadata are available (Summer '26 or later; verify in current release notes).

Deploy

# deploy everything and run the test class
sf project deploy start -o <alias> -d force-app/main/default \
  -l RunSpecifiedTests -t SObjectActionsTest -t SObjectActionsExtTest -t SObjectActionsExt2Test -t SObjectActionsExt3Test -t SObjectActionsExt4Test

# Test fixtures (record types + dependent picklist used by two tests; deploy first for full per-class coverage)
sf project deploy start -o <alias> -d test-fixtures && sf org assign permset -n SObjectActions_Fixture -o <alias>
# MCP server definition and External Client App (separate dirs)
sf project deploy start -o <alias> -d mcp -d eca

# Apex only (skip the MCP definition)
sf project deploy start -o <alias> -d force-app/main/default/classes \
  -l RunSpecifiedTests -t SObjectActionsTest -t SObjectActionsExtTest -t SObjectActionsExt2Test -t SObjectActionsExt3Test -t SObjectActionsExt4Test

Notes:

• The McpServerDefinition developer name must be alphanumeric, start with a letter, 2-40 chars (underscores are rejected). It is SObjectActions.

• apiIdentifier values are aa:apex-<ClassName> and resolve automatically from the API Catalog once the class is deployed. Deploy classes and the definition together or classes first.

Enable the MCP server

1. Setup > MCP Servers > SObject Actions > link External Client App SObject Actions MCP Client (deployed by this repo) > Activate.

2. Client authentication details: docs/CLIENT_AUTH.md.

3. Assign users a permission set with access to the Apex classes plus CRUD/FLS on the objects they will operate on. The tools run as the authenticated user.

4. Point your MCP client (Claude, Agentforce, Cursor, etc.) at the server URL shown in Setup. tools/list returns checkAccess, describeObject, searchRecords, findRecords, countRecords, aggregateRecords, readRecords, relatedRecords, recordSummary, picklistValues, validateRecords, createRecords, upsertRecords, updateRecords, cloneRecords, assignOwner, changeRecordType, deleteRecords, undeleteRecords, logActivity, closeCase, convertLead, postChatter, addNote, attachFile, listFlows, runFlow.

Tool annotations set in the definition:

Typical agent sequence: describeObject (get exact API names) -> findRecords / readRecords -> createRecords / upsertRecords / updateRecords -> deleteRecords.

Common conventions

objectApiName

Required on every action. Case-insensitive API name: Account, Case, Task, My_Object__c, ...

Activity (polymorphic Task/Event) Activity is not creatable/queryable directly, so it is treated as an alias for "Task or Event":

A single request may therefore mix Tasks and Events when objectApiName = "Activity".

Record inputs (create / update)

Provide any combination; they are merged in this order:

recordsJson rules:

• Field names must exist on the object (direct field API names or relationship names such as Account for external-Id upserts). Unknown names cause the whole request to fail with Unknown field(s) on <Object>: <names> rather than being silently dropped.

• Values are coerced by the platform JSON deserializer: dates as YYYY-MM-DD, datetimes as ISO-8601 (2030-01-01T10:00:00.000Z), booleans as true/false, numbers unquoted.

• attributes.type, if present, must equal objectApiName (or Task/Event for Activity).

Id inputs (read / delete)

• recordId (read only) and/or recordIds (read + delete). Blank entries are skipped.

• 15- or 18-character Ids accepted; invalid strings fail the request (Invalid record Id: ...).

• Each Id's type must match objectApiName (Task/Event when Activity).

allOrNone (create / update / delete)

• Default false: partial success; each failed row is reported in errors as row <n>: <message>.

• true: the entire request rolls back on any failure; failureCount = number of rows, errors holds the DML exception message.

Labels

recordLabels is aligned index-for-index with recordIds. Label source:

Create/update labels are re-queried after DML (so auto-numbers like CaseNumber are populated). Delete captures labels before deleting.

Common outputs

Request-level validation errors (bad object name, malformed JSON, ...) set isSuccess=false, failureCount=1 and one entry in errors; no DML is performed for that request. Other requests in the same call are unaffected.

Tool reference

createRecords / SObjectCreateAction

Invocable label: Create Records (Generic), category SObject Actions.

Inputs: objectApiName (req), record, records, recordsJson, allOrNone. Outputs: isSuccess, successCount, failureCount, recordIds, recordLabels, errors, message.

MCP call examples:

{ "objectApiName": "Account",
  "recordsJson": "[{\"Name\":\"Acme\",\"Industry\":\"Energy\"},{\"Name\":\"Globex\"}]" }

{ "objectApiName": "Case",
  "recordsJson": "{\"Subject\":\"Printer on fire\",\"Status\":\"New\",\"Origin\":\"Web\",\"AccountId\":\"001...\"}" }

-> recordLabels: ["00001234 - Printer on fire"]

{ "objectApiName": "Activity",
  "recordsJson": "[{\"attributes\":{\"type\":\"Task\"},\"Subject\":\"Call\",\"WhatId\":\"001...\"},{\"attributes\":{\"type\":\"Event\"},\"Subject\":\"Meet\",\"DurationInMinutes\":30,\"ActivityDateTime\":\"2030-01-01T10:00:00.000Z\"}]" }

Sample result:

{ "isSuccess": true, "successCount": 2, "failureCount": 0,
  "recordIds": ["00T...", "00U..."], "recordLabels": ["Call", "Meet"],
  "errors": [], "message": "2 created, 0 failed." }

Partial failure (allOrNone=false):

{ "isSuccess": false, "successCount": 1, "failureCount": 1,
  "recordIds": ["003..."], "recordLabels": ["Good"],
  "errors": ["row 2: Required fields are missing: [LastName] [LastName]"],
  "message": "1 created, 1 failed." }

readRecords / SObjectReadAction

Invocable label: Read Records (Generic).

Inputs:

Outputs:

Examples:

{ "objectApiName": "Account", "recordId": "001..." }

{ "objectApiName": "Case", "recordIds": ["500...","500..."], "fields": ["Status","Priority","Account.Name"] }

{ "objectApiName": "Activity", "recordIds": ["00T...","00U..."], "fields": ["Subject","ActivityDate"] }

Sample result:

{ "isSuccess": true, "foundCount": 1, "notFoundCount": 0,
  "recordIds": ["500..."], "recordLabels": ["00001234 - Printer on fire"],
  "recordsJson": "[{\"attributes\":{\"type\":\"Case\"},\"Id\":\"500...\",\"CaseNumber\":\"00001234\",\"Subject\":\"Printer on fire\",\"Status\":\"New\",\"Account\":{\"attributes\":{\"type\":\"Account\"},\"Name\":\"Acme\"}}]",
  "notFoundIds": [], "errors": [], "message": "1 found, 0 not found." }

Direct field names are validated before the query (Unknown field on Account: Foo__c). Relationship paths are validated by SOQL itself; a bad path surfaces as a QueryException in errors. Records the user cannot see are simply reported in notFoundIds (no error).

updateRecords / SObjectUpdateAction

Invocable label: Update Records (Generic).

Inputs: objectApiName (req), record, records, recordsJson, allOrNone. Every row must include Id; a row without one fails the whole request (row <n>: Id is required for update.).

Outputs: same shape as create (successCount, recordIds, recordLabels, ...). Labels reflect the record's state after all updates in the call are applied.

Examples:

{ "objectApiName": "Account",
  "recordsJson": "[{\"Id\":\"001...\",\"Name\":\"Acme Corp\",\"Phone\":\"555-0100\"}]" }

{ "objectApiName": "Case", "recordsJson": "{\"Id\":\"500...\",\"Status\":\"Closed\"}" }

{ "objectApiName": "Activity",
  "recordsJson": "[{\"attributes\":{\"type\":\"Task\"},\"Id\":\"00T...\",\"Status\":\"Completed\"}]" }

To clear a field pass null: {"Id":"001...","Description":null}.

deleteRecords / SObjectDeleteAction

Invocable label: Delete Records (Generic). Tool is flagged destructive.

Inputs: objectApiName (req), recordIds, record, records, allOrNone. Records passed as SObjects must include Id.

Outputs: isSuccess, successCount, failureCount, recordIds, recordLabels (captured before deletion), errors, message.

Examples:

{ "objectApiName": "Account", "recordIds": ["001...", "001..."] }

{ "objectApiName": "Activity", "recordIds": ["00T...", "00U..."] }

Deleted records go to the Recycle Bin (standard Database.delete semantics). Cascade deletes follow the platform's master-detail / lookup rules.

upsertRecords / SObjectUpsertAction

Invocable label: Upsert Records (Generic).

Inputs: objectApiName (req), externalIdField (optional, default Id), record, records, recordsJson, allOrNone. externalIdField must be an external Id / idLookup field on the object. Activity is supported (Task/Event via attributes.type); the external Id field must exist on the concrete type.

Outputs: isSuccess, successCount, failureCount, createdCount, updatedCount, recordIds, recordLabels, wasCreated[] (aligned with recordIds), errors, message.

Examples:

{ "objectApiName": "Account", "externalIdField": "External_Key__c",
  "recordsJson": "[{\"External_Key__c\":\"ERP-1001\",\"Name\":\"Acme\"},{\"External_Key__c\":\"ERP-1002\",\"Name\":\"Globex\"}]" }

{ "objectApiName": "Contact",
  "recordsJson": "[{\"Id\":\"003...\",\"Email\":\"a@b.com\"},{\"LastName\":\"New Person\"}]" }

-> wasCreated: [false, true], message: "1 created, 1 updated, 0 failed."

Rows are grouped per concrete object type; each group is one Database.upsert. allOrNone=true uses a savepoint so a failure in any group rolls back the whole request.

findRecords / SObjectFindAction

Invocable label: Find Records (Generic). Structured filters only; no raw SOQL/WHERE is accepted.

Inputs:

Values are coerced to the field type before binding (dates YYYY-MM-DD, datetimes ISO-8601, numbers, booleans, Ids). All values go through bind variables (Database.queryWithBinds, USER_MODE).

Outputs: isSuccess, resultCount, recordIds, recordLabels, recordsJson, records (Flow), soql (the query that ran, values redacted as :b0, :b1...), errors, message ("... (limit reached)" when resultCount == limitCount).

Examples:

{ "objectApiName": "Case",
  "filtersJson": "[{\"field\":\"Status\",\"op\":\"IN\",\"value\":[\"New\",\"Working\"]},{\"field\":\"CreatedDate\",\"op\":\">=\",\"value\":\"2026-08-01T00:00:00Z\"}]",
  "fields": ["Status","Priority","Account.Name"], "orderBy": "CreatedDate DESC", "limitCount": 25 }

{ "objectApiName": "Account",
  "filtersJson": "[{\"field\":\"Name\",\"op\":\"LIKE\",\"value\":\"Acme%\"},{\"field\":\"Industry\",\"op\":\"=\",\"value\":\"Energy\"}]",
  "filterLogic": "OR" }

{ "objectApiName": "Task",
  "filtersJson": "[{\"field\":\"WhatId\",\"op\":\"=\",\"value\":\"001...\"},{\"field\":\"IsClosed\",\"op\":\"=\",\"value\":false}]" }

describeObject / SObjectDescribeAction

Invocable label: Describe Object (Generic). Two modes in one tool.

Describe mode (objectApiName set):

Outputs: objectApiName, objectLabel, keyPrefix, isCustom, isCreateable/Updateable/Deletable/Queryable, labelFields (e.g. ["CaseNumber","Subject"] for Case), requiredFields (createable, non-nillable, no default), fieldsJson (accessible fields only: apiName, label, type, required, createable, updateable, externalId, nameField, length, referenceTo[], relationshipName, picklistValues[]), recordTypesJson (active, available, non-master: id, developerName, name, isDefault), childRelationshipsJson (relationshipName, childObject, field), resultCount (fields returned).

List mode (objectApiName blank):

Outputs: objectsJson (apiName, label, keyPrefix, isCustom, createable, queryable for accessible objects; custom settings and prefix-less system objects excluded), resultCount.

Examples:

{ "objectApiName": "Case", "fieldNameContains": "status" }

{ "objectApiName": "My_Object__c" }

{ "objectNameContains": "invoice", "customOnly": true }

searchRecords / SObjectSearchAction

Invocable label: Search Records (Generic). SOSL free-text search; the term is bound (FIND :term).

Outputs: resultCount, recordIds, recordLabels, recordObjectNames (aligned), recordsJson, records.

{ "searchTerm": "acme*", "objectApiNames": ["Account","Contact"], "searchIn": "NAME", "fields": ["Phone","Email"] }

relatedRecords / SObjectRelatedAction

Invocable label: Get Related Records (Generic).

Outputs: parentObjectApiName, childObjectApiName, resultCount, recordIds, recordLabels, recordsJson, records.

{ "parentRecordId": "001...", "relationshipName": "Cases", "fields": ["Status","Priority"], "orderBy": "CreatedDate DESC", "limitCount": 10 }

countRecords / SObjectCountAction

Invocable label: Count Records (Generic).

Outputs: totalCount, groupValues[], groupCounts[] (aligned), groupsJson ([{value,count}]), soql.

{ "objectApiName": "Case", "filtersJson": "[{\"field\":\"IsClosed\",\"op\":\"=\",\"value\":false}]", "groupByField": "Priority" }

undeleteRecords / SObjectUndeleteAction

Invocable label: Undelete Records (Generic). Restores from the Recycle Bin.

Inputs: objectApiName (req; Activity for Task/Event mix), recordIds (req), allOrNone. Outputs: successCount, failureCount, recordIds, recordLabels (post-restore), errors, message. Duplicate Ids in one request are collapsed. Records already restored or purged fail per row.

{ "objectApiName": "Account", "recordIds": ["001..."] }

checkAccess / SObjectAccessAction

Invocable label: Check Access (Generic). All inputs optional; with none it is a "who am I".

Outputs: userId, userName, loginUsername, profileId, profileName, userType, organizationId, timeZone, objectApiName, canCreate/canRead/canUpdate/canDelete, fieldAccessJson, recordAccessJson, message.

{ "objectApiName": "Opportunity", "fields": ["Amount","StageName"], "recordIds": ["006..."] }

cloneRecords / SObjectCloneAction

Invocable label: Clone Records (Generic).

Copies every field that is createable, readable, not auto-number and not a formula. Child records are not cloned. Outputs: sourceRecordIds (aligned), recordIds, recordLabels, recordUrls, counts, errors.

{ "objectApiName": "Opportunity", "recordIds": ["006..."], "overridesJson": "{\"Name\":\"Renewal 2027\",\"StageName\":\"Prospecting\"}", "excludeFields": ["OwnerId"] }

validateRecords / SObjectValidateAction

Invocable label: Validate Records (Generic, dry run). Performs the insert/update inside a savepoint and always rolls back; triggers, validation rules, required fields, FLS and sharing all run for real.

Inputs: objectApiName (req), operation (CREATE default | UPDATE), record, records, recordsJson. Outputs: isSuccess (would all rows save), successCount, failureCount, rowResultsJson ([{row, valid, errors[]}]), errors, message (... Nothing was saved.).

Note: the DML still counts toward governor limits and any auto-numbers consumed in the transaction are not reused.

{ "objectApiName": "Contact", "recordsJson": "[{\"LastName\":\"Ok\"},{\"FirstName\":\"No last name\"}]" }

aggregateRecords / SObjectAggregateAction

Invocable label: Aggregate Records (Generic).

Outputs: resultCount, rowsJson (each row: group field values + FUNCTION_Field keys, e.g. SUM_Amount), soql.

{ "objectApiName": "Opportunity",
  "aggregationsJson": "[{\"function\":\"SUM\",\"field\":\"Amount\"},{\"function\":\"COUNT\",\"field\":\"Id\"}]",
  "filtersJson": "[{\"field\":\"IsClosed\",\"op\":\"=\",\"value\":false}]",
  "groupByFields": ["StageName"] }

runFlow / SObjectRunFlowAction

Invocable label: Run Flow (Generic).

Outputs: interviewId, outputsJson, errors (flow faults surface as Could not start flow ... or the fault message), message. The flow runs in the same transaction, in the flow's declared run mode.

{ "flowApiName": "SObjectActions_EchoFlow", "inputsJson": "{\"inputText\":\"hi\",\"inputNumber\":1}", "outputVariableNames": ["outputText","outputNumber"] }

assignOwner / SObjectAssignOwnerAction

Inputs: objectApiName, recordIds, newOwnerId (005/00G) or newOwnerName (exact user full name / username, or queue name / developer name; ambiguous names are rejected), allOrNone. Outputs: resolved ownerId/ownerName, per-record counts, recordIds, recordLabels, errors.

{ "objectApiName": "Case", "recordIds": ["500..."], "newOwnerName": "Tier 2 Support" }

changeRecordType / SObjectRecordTypeAction

Inputs: objectApiName, recordIds, recordType (Id, DeveloperName or Name), allOrNone. Errors list the available developer names. Outputs: resolved recordTypeId/recordTypeName, per-record outcomes.

picklistValues / SObjectPicklistAction

Inputs: objectApiName, fieldApiName, includeInactive. Outputs: values[], labels[], valuesJson ({value,label,active,default,validFor[]}), isRestricted, isDependent, controllingField, defaultValue. Values reflect the org-wide field definition (record-type value sets are not applied).

logActivity / SObjectLogActivityAction

Logs a completed Task. Inputs: subject (req), relatedRecordId (WhatId), personRecordId (Contact/Lead WhoId), description, activityDate (default today), activityType, status (default first closed status), priority, ownerId, extraFieldsJson. Outputs: recordId, recordUrl, status.

{ "subject": "Call with CFO", "relatedRecordId": "001...", "personRecordId": "003...", "description": "Discussed renewal", "activityType": "Call" }

closeCase / SObjectCloseCaseAction

Inputs: caseIds, status (must be a closed status; default first closed status), comment (+ commentIsPublic), extraFieldsJson, allOrNone. Outputs: status used, per-case counts, recordLabels (CaseNumber - Subject).

convertLead / SObjectConvertLeadAction

Inputs: leadId, convertedStatus (default first converted status), accountId / contactId (merge into existing), createOpportunity (default true), opportunityName, ownerId, sendEmailToOwner. Outputs: accountId, contactId, opportunityId + URLs.

postChatter / SObjectPostChatterAction

Inputs: recordId (any feed-enabled record or User), text, mentionUserIds. Outputs: feedItemId. Fails with a clear message when the object has no feed tracking.

addNote / SObjectAddNoteAction

Inputs: title, body (plain text or simple HTML), recordIds, shareType (V default / I / C). Creates a ContentNote and ContentDocumentLinks; if Enhanced Notes is disabled in the org, stores the note as an .html file instead (storedAsFile=true). Outputs: noteId, linked recordIds, storedAsFile.

attachFile / SObjectAttachFileAction

Inputs: fileName, textContent or base64Content, title, recordIds, shareType. Outputs: contentVersionId, contentDocumentId, linked recordIds. Heap limit applies to large base64 payloads (~6 MB sync).

listFlows / SObjectListFlowsAction

List mode: nameContains, processType (default AutoLaunchedFlow; ALL), includeInactive, limitCount -> flowsJson. Detail mode: flowApiName -> variablesJson (apiName, dataType, isInput, isOutput, isCollection, objectType, description). Pair with runFlow.

recordSummary / SObjectSummaryAction

Inputs: recordId, fields (default all accessible), relationshipNames (max 10; default common ones that exist), recentActivityLimit (0-20, default 5). Outputs: objectApiName, recordLabel, recordUrl, ownerName, recordJson, relatedCountsJson ({Contacts: 3, Cases: 1, ...}), recentActivityJson ([{id,type,subject,date,status,ownerName}]). Costs 1 SOQL for the record + 1 per relationship + 2 for activity.

Calling from Flow

Add an Action element, search the SObject Actions category, pick the action.

• Set Object API Name to a literal or a text variable.

• For create/update, assign a record variable to Record or a record collection to Records. Flow's generic SObject inputs require you to pick the object type on the action element; it must match objectApiName (or be Task/Event with Activity).

• Read the outputs Created Record Ids / Record / Records / Errors into Flow variables.

• Leave All Or None empty for partial success, or set {!$GlobalConstant.True} to roll back.

Fault paths: request-level problems do not throw; check Success and Errors. Only unexpected platform exceptions (limits, etc.) reach a Flow fault connector.

Calling from REST

POST /services/data/v67.0/actions/custom/apex/SObjectCreateAction
Authorization: Bearer <token>
Content-Type: application/json

{ "inputs": [
  { "objectApiName": "Account", "recordsJson": "[{\"Name\":\"Acme\"}]" },
  { "objectApiName": "Contact", "recordsJson": "[{\"LastName\":\"Smith\",\"AccountId\":\"001...\"}]" }
] }

Same shape for SObjectReadAction, SObjectUpdateAction, SObjectDeleteAction. Each element of inputs maps to one element of the response outputValues.

Security model

• All DML and SOQL run with AccessLevel.USER_MODE: object CRUD, field-level security and sharing of the running user are enforced by the platform.

  • Create/update of a non-writable field -> row error from the platform.

  • Read of an inaccessible object/field -> not returned (default field list only includes accessible fields; explicit inaccessible fields raise a query error).

  • Records outside the user's sharing scope -> notFoundIds on read, row error on update/delete.

• The classes are global with sharing (required for MCP discovery).

• No Database.query string is built from raw caller input: object names are validated through describe, field names through the field map, Ids through Id.valueOf; relationship paths in readRecords.fields are only ever placed in the SELECT list, never in a WHERE clause.

• Because the tools are generic, gate access with permission sets: who can call the Apex classes, and CRUD/FLS on the objects. Consider excluding deleteRecords from the server for agent use cases that should never delete.

Limits and bulk behavior

• Invocable inputs are bulkified: all records across all requests in one call are combined into the fewest DML statements possible (one insert / update / delete per call in the normal case).

• Duplicate Ids across requests (same record updated or deleted twice in one call) are split into sequential DML batches instead of failing with Duplicate id in list.

• Label lookups: one SOQL per concrete object type per call (create/update/delete); read issues one SOQL per concrete type per request.

• Governor limits that apply per transaction: 100 SOQL, 150 DML statements, 10,000 rows DML, 6 MB heap (sync). Very large recordsJson payloads or readRecords with no fields on wide objects and hundreds of Ids can approach heap/CPU limits; pass an explicit fields list for bulk reads.

• Mixed object types in one call are fine, but mixing setup and non-setup objects (e.g. User + Account) in a single call is subject to the platform's mixed-DML rule.

• Records per DML chunk of differing SObject types is limited to 10 distinct types per DML statement by the platform.

Error catalog

Testing

Three layers, cheapest first:

# 1. Unit tests (Apex, ~98% coverage)
sf apex run test -o <alias> -n SObjectActionsTest -n SObjectActionsExtTest -n SObjectActionsExt2Test -n SObjectActionsExt3Test -n SObjectActionsExt4Test -r human -w 10 -c

# 2. Anonymous Apex smoke: create -> read -> update -> delete, prints every result
sf apex run -o <alias> -f scripts/apex/smoke.apex

# 3. REST smoke through the Invocable Actions API (the exact path MCP tools use).
#    45 assertions across all 27 tools incl. Case labels, Activity Task/Event mix,
#    validation errors. Creates and removes its own records. Needs jq.
scripts/smoke-test.sh <alias> [apiVersion]

To exercise the MCP layer itself, activate the server (see above), connect an MCP client with the External Client App, run tools/list and call e.g. readRecords {"objectApiName":"Account","recordId":"001..."}.

Test coverage: create (SObject + JSON inputs, Case label, Activity resolution, validation matrix, partial and all-or-none), read (all/explicit fields, relationship path, Activity mix, not-found, validation), update (JSON/SObject/Activity, missing Id, ghost Id, all-or-none rollback, duplicate Id across requests), delete (Ids/SObjects/Activity mix, labels, validation, partial, all-or-none, duplicate Id), util fallbacks.

Tests assert by record Id rather than table counts so they pass in orgs with existing triggers/automation on Account.

Extending

Everything from the original design list is implemented. Natural next additions: record-type-aware picklist values (UI API callout via Named Credential), sendEmail (single email / template), approval submit/recall, and share/unshare (manual sharing) actions.

• Custom label rules: extend SObjectActionUtil.labelFields() (Case is the current special case).

• New tool on the server: add a <tools> block to mcp/main/default/mcpServerDefinitions/SObjectActions.mcpServerDefinition-meta.xml with apiIdentifier = aa:apex-<ClassName> and redeploy; re-activate the server in Setup if needed.