Cirra AI Salesforce Admin MCP Server

soql_query

Read-onlyIdempotent

Run a Salesforce SOQL query to return a list of sObject records, with automatic masking of encrypted fields. For extracts of thousands of rows, or when this tool times out, use bulk_query. To read Apex debug log text, query ApexLog and include Body in fields.

Input Schema

Name	Required	Description
`limit`	No	The maximum number of records to return. The default is 200. Note: LIMIT is automatically omitted for aggregate queries without GROUP BY.
`fields`	Yes	List of fields to retrieve. May include relationship fields and aggregates. For ApexLog, include Body to retrieve the raw debug log text (Body is a blob and is fetched after the query; at most 5 logs with Body per call).
`groupBy`	No	GROUP BY clause for aggregate queries. Required when using aggregate functions with grouping, optional otherwise
`orderBy`	No	(optional) ORDER BY clause. May include fields from related objects
`sObject`	Yes	The name of the Salesforce object to query
`sf_user`	No	(optional) Salesforce username to identify the connection to use. Omit this to use the current default connection.
`pageSize`	No	(optional) Maximum number of records to return per page when the response requires pagination, including the first page. If omitted, the first page is a short preview and later pages use an automatically calculated size.
`whereClause`	Yes	WHERE clause. May include conditions on related objects. Do NOT include APEX snippets or variables: use only literal values
`havingClause`	No	HAVING clause to filter grouped results by aggregate conditions (e.g. 'COUNT(Id) > 5'). Requires groupBy to be set
`cirra_ai_team`	No	(optional) Cirra team ID or name that owns the Salesforce connection to use for this call. Must be provided together with 'sf_user'. Use it to run against a specific team's connection without changing your default team — e.g. to keep separate chats on Salesforce orgs in different teams. Omit it when this call carries the context_handle from cirra_ai_init, which names the team for the conversation. A user with more than one place to work (several teams, or a team and a personal account) must pass either the context_handle or 'cirra_ai_team' + 'sf_user'.
`context_handle`	No	(recommended) The conversation context handle returned by cirra_ai_init in this conversation. Pass the exact context_handle value from the most recent cirra_ai_init result so this call runs against the team and Salesforce connection selected for this conversation. A user with more than one place to work (several Cirra AI teams, or a team and a personal account) must pass either this handle or 'cirra_ai_team' + 'sf_user'; a call with neither is refused.

Output Schema

Name	Required	Description	Default
`message`	Yes
`records`	No
`results`	No
`success`	Yes
`warning`	No
`errorCode`	No
`errorCount`	No
`resultCount`	No
`artifactType`	No
`requestCount`	No
`skippedCount`	No
`successCount`	No
`artifactCategory`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedNov 1, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

changedInput schema / properties / cirra_ai_team / description

Previous value: -"(optional) Cirra team ID or name that owns the Salesforce connection to use for this call. Must be provided together with 'sf_user'. Use it to run against a specific team's connection without changing your default team — e.g. to keep separate chats on Salesforce orgs in different teams. Omit to use your current/default team."New value: +"(optional) Cirra team ID or name that owns the Salesforce connection to use for this call. Must be provided together with 'sf_user'. Use it to run against a specific team's connection without changing your default team — e.g. to keep separate chats on Salesforce orgs in different teams. Omit it when this call carries the context_handle from cirra_ai_init, which names the team for the conversation. A user with more than one place to work (several teams, or a team and a personal account) must pass either the context_handle or 'cirra_ai_team' + 'sf_user'."

addedInput schema / properties / context_handle

Added value: +{
+  "description": "(recommended) The conversation context handle returned by cirra_ai_init in this conversation. Pass the exact context_handle value from the most recent cirra_ai_init result so this call runs against the team and Salesforce connection selected for this conversation. A user with more than one place to work (several Cirra AI teams, or a team and a personal account) must pass either this handle or 'cirra_ai_team' + 'sf_user'; a call with neither is refused.",
+  "type": "string"
+}

changedInput schema / properties / fields / description

Previous value: -"List of fields to retrieve. May include relationship fields and aggregates"New value: +"List of fields to retrieve. May include relationship fields and aggregates. For ApexLog, include Body to retrieve the raw debug log text (Body is a blob and is fetched after the query; at most 5 logs with Body per call)."

changedInput schema / properties / pageSize / description

Previous value: -"(optional) Maximum number of records to return per page when the response requires pagination. If omitted, page size is calculated automatically."New value: +"(optional) Maximum number of records to return per page when the response requires pagination, including the first page. If omitted, the first page is a short preview and later pages use an automatically calculated size."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "artifactCategory": {
+      "type": "string"
+    },
+    "artifactType": {
+      "type": "string"
+    },
+    "errorCode": {
+      "type": "string"
+    },
+    "errorCount": {
+      "type": "number"
+    },
+    "message": {
+      "type": "string"
+    },
+    "records": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "requestCount": {
+      "type": "number"
+    },
+    "resultCount": {
+      "type": "number"
+    },
+    "results": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "skippedCount": {
+      "type": "number"
+    },
+    "success": {
+      "type": "boolean"
+    },
+    "successCount": {
+      "type": "number"
+    },
+    "warning": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "success",
+    "message"
+  ],
+  "type": "object"
+}

Changed1 schema field changedJul 27, 2026

addedInput schema / properties / cirra_ai_team

Added value: +{
+  "description": "(optional) Cirra team ID or name that owns the Salesforce connection to use for this call. Must be provided together with 'sf_user'. Use it to run against a specific team's connection without changing your default team — e.g. to keep separate chats on Salesforce orgs in different teams. Omit to use your current/default team.",
+  "type": "string"
+}

AddedMay 8, 2026
RemovedMay 8, 2026

Changed2 schema fields changedMar 18, 2026

addedInput schema / properties / havingClause

Added value: +{
+  "description": "HAVING clause to filter grouped results by aggregate conditions (e.g. 'COUNT(Id) > 5'). Requires groupBy to be set",
+  "type": "string"
+}

addedInput schema / properties / pageSize

Added value: +{
+  "description": "(optional) Maximum number of records to return per page when the response requires pagination. If omitted, page size is calculated automatically.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

Changed2 schema fields changedMar 13, 2026

changedInput schema / properties / limit / default
```
Previous value: -100New value: +200
```

changedInput schema / properties / limit / description

Previous value: -"The maximum number of records to return. The default is 100. Note: LIMIT is automatically omitted for aggregate queries without GROUP BY."New value: +"The maximum number of records to return. The default is 200. Note: LIMIT is automatically omitted for aggregate queries without GROUP BY."

AddedFeb 26, 2026
RemovedFeb 26, 2026

Changed3 schema fields changedFeb 15, 2026

changedInput schema / properties / groupBy / description

Previous value: -"GROUP BY clause for aggregate queries. Required when using aggregate functions with grouping. Example: 'StageName' or 'AccountId, StageName'"New value: +"GROUP BY clause for aggregate queries. Required when using aggregate functions with grouping, optional otherwise"

changedInput schema / properties / orderBy / description

Previous value: -"ORDER BY clause. May include fields from related objects"New value: +"(optional) ORDER BY clause. May include fields from related objects"

changedInput schema / required

Previous value: -[
-  "sObject",
-  "fields",
-  "whereClause",
-  "orderBy",
-  "groupBy"
-]New value: +[
+  "sObject",
+  "fields",
+  "whereClause"
+]

First observedJan 31, 2026

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuine non-structured context: automatic masking of encrypted fields and the behavior when the tool times out. It does not describe pagination behavior or the interaction with fetch_more, which keeps it below 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the core action, followed by the alternative-routing and the special case. Nothing repeats the annotations or restates the name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and the schema fully documents parameters. The one remaining gap is that pagination via pageSize is documented in the schema but the description never points to fetch_more, leaving an agent to infer how to continue a paged result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all 11 parameters including limit, pageSize, and context_handle are already documented at the field level. The description adds only the ApexLog/Body hint, which the schema also covers, plus the masking note. Baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run a Salesforce SOQL query to return a list of sObject records') plus a distinguishing scope detail (automatic masking of encrypted fields). Names the sibling it is not for large extracts (bulk_query), so an agent can route without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly gives the switch condition: use bulk_query for extracts of thousands of rows or on timeout. Also gives a positive routing case for ApexLog Body retrieval, which would otherwise be non-obvious. No ambiguity left.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Cirra AI Salesforce Admin MCP Server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?