Salesforce Connector

The Salesforce connector enables AxonFlow agents to execute SOQL queries, create and update records, and access CRM data with full policy enforcement, field-level security, and audit logging.

Overview

Property	Value
Type	salesforce
Edition	Enterprise
Auth Methods	OAuth 2.0 (JWT Bearer, Client Credentials), Username-Password
Capabilities	query, execute, soql, crud, bulk_operations, sandbox_support

Use Cases

• Execute SOQL queries for customer support context retrieval
• Create and update leads, contacts, and opportunities in sales workflows
• Build account management agents with CRM data access
• Generate sales reports and pipeline summaries

Prerequisites

• AxonFlow Enterprise license (requires Enterprise Edition)
• Salesforce org (any edition with API access)
• One of the following authentication methods:
  • OAuth 2.0 JWT Bearer (recommended for server-to-server)
  • OAuth 2.0 Client Credentials (for service integrations)
  • Username-Password (for development/testing only)
• Connected App configured in Salesforce with appropriate OAuth scopes

Salesforce Connected App Setup

1. In Salesforce Setup, navigate to App Manager > New Connected App
2. Enable OAuth Settings
3. Set callback URL (e.g., https://login.salesforce.com/services/oauth2/callback)
4. Select OAuth scopes: api, refresh_token, offline_access
5. For JWT Bearer flow: upload the X.509 certificate
6. Copy the Consumer Key (Client ID) and Consumer Secret (Client Secret)

Configuration

Environment Variables

# Required
MCP_salesforce_INSTANCE_URL="https://your-org.my.salesforce.com"
MCP_salesforce_CLIENT_ID="3MVG9xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
MCP_salesforce_CLIENT_SECRET="xxxxxxxxxxxxxxxxxxxxxxxx"

# Authentication - Username-Password (simplest, for dev/test)
MCP_salesforce_AUTH_TYPE="password"
MCP_salesforce_USERNAME="[email protected]"
MCP_salesforce_PASSWORD="password+security_token"

# Authentication - JWT Bearer (recommended for production)
# MCP_salesforce_AUTH_TYPE="jwt"
# MCP_salesforce_USERNAME="[email protected]"
# MCP_salesforce_PRIVATE_KEY_FILE="/secrets/salesforce/private.pem"

# Optional
MCP_salesforce_API_VERSION="v59.0"
MCP_salesforce_TIMEOUT="30s"
MCP_salesforce_MAX_RETRIES="3"
MCP_salesforce_SANDBOX="false"  # Set to "true" for sandbox orgs

Configuration Options

Option	Type	Required	Default	Description
instance_url	string	Yes	-	Salesforce instance URL
client_id	string	Yes	-	Connected App Consumer Key
client_secret	string	Yes*	-	Connected App Consumer Secret (not needed for JWT)
auth_type	string	No	password	Auth type (password, jwt, client_credentials)
username	string	Yes*	-	Salesforce username (for password and JWT flows)
password	string	No*	-	Password + security token (for password flow only)
private_key_file	string	No*	-	Path to private key PEM file (for JWT flow)
api_version	string	No	v59.0	Salesforce REST API version
sandbox	boolean	No	false	Use sandbox login endpoint
timeout	string	No	30s	Request timeout
max_retries	integer	No	3	Maximum retry attempts

Connector Config (Customer Portal)

{
  "name": "salesforce-crm",
  "type": "salesforce",
  "options": {
    "instance_url": "https://your-org.my.salesforce.com",
    "auth_type": "password",
    "api_version": "v59.0",
    "sandbox": false,
    "timeout": 30,
    "max_retries": 3
  },
  "credentials": {
    "client_id": "3MVG9xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "username": "[email protected]",
    "password": "password+security_token"
  }
}

Installation

Install the Salesforce connector via the connector marketplace API:

curl -X POST http://localhost:8081/api/v1/connectors/salesforce/install \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "salesforce-crm",
    "config": {
      "instance_url": "https://your-org.my.salesforce.com",
      "client_id": "3MVG9xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "username": "[email protected]",
      "password": "password+security_token"
    }
  }'

Operations

SOQL Query

curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "connector": "salesforce-crm",
    "statement": "query",
    "parameters": {
      "soql": "SELECT Id, Name, Email, Account.Name, Phone FROM Contact WHERE Account.Industry = '\''Technology'\'' AND CreatedDate = THIS_YEAR ORDER BY CreatedDate DESC LIMIT 20"
    }
  }'

Response:

{
  "success": true,
  "rows": [
    {
      "Id": "003xx000004TmDXAA0",
      "Name": "Alice Johnson",
      "Email": "[email protected]",
      "Account": {"Name": "TechCorp Inc."},
      "Phone": "+1-555-0100"
    }
  ],
  "row_count": 1,
  "duration_ms": 180,
  "connector": "salesforce-crm"
}

Create a Record

curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -H "Content-Type: application/json" \
  -d '{
    "connector": "salesforce-crm",
    "action": "create",
    "parameters": {
      "object": "Lead",
      "fields": {
        "FirstName": "Bob",
        "LastName": "Smith",
        "Company": "Widget Co",
        "Email": "[email protected]",
        "LeadSource": "Web",
        "Status": "Open - Not Contacted"
      }
    }
  }'

Response:

{
  "success": true,
  "rows_affected": 1,
  "message": "Lead created (id=00Qxx000004TmDXAA0)",
  "duration_ms": 120,
  "connector": "salesforce-crm"
}

Update a Record

curl -X POST https://your-axonflow.example.com/mcp/tools/execute \
  -d '{
    "connector": "salesforce-crm",
    "action": "update",
    "parameters": {
      "object": "Opportunity",
      "id": "006xx000004TmDXAA0",
      "fields": {
        "StageName": "Closed Won",
        "Amount": 75000,
        "CloseDate": "2025-12-15"
      }
    }
  }'

Query Opportunities Pipeline

curl -X POST https://your-axonflow.example.com/mcp/resources/query \
  -d '{
    "connector": "salesforce-crm",
    "statement": "query",
    "parameters": {
      "soql": "SELECT StageName, COUNT(Id) numDeals, SUM(Amount) totalAmount FROM Opportunity WHERE IsClosed = false GROUP BY StageName ORDER BY SUM(Amount) DESC"
    }
  }'

Supported Operations

Operation	Description
query	Execute SOQL queries against any Salesforce object
create	Create a new record on any standard or custom object
update	Update fields on an existing record
delete	Delete a record by ID
describe	Get metadata for a Salesforce object (fields, types, picklists)

Limitations

• SOQL limits: Queries are subject to Salesforce governor limits (50,000 records per query, 100 SOQL queries per transaction).
• API daily limits: Salesforce enforces daily API request limits based on edition (e.g., Enterprise Edition: 100,000/day).
• Field-level security: Fields the integration user cannot access are excluded from results. Use a profile with appropriate field permissions.
• Bulk operations: For large data volumes (> 2,000 records), use the Salesforce Bulk API through dedicated ETL tools instead of this connector.
• Sandbox vs. Production: Sandbox credentials are separate from production. Set sandbox: true when connecting to sandbox orgs.

Troubleshooting

Authentication Failed (INVALID_LOGIN)

• Verify username, password, and security token are correct
• For password flow: the password must include the security token appended (e.g., mypasswordABCDEF123456)
• Check that the Connected App allows the selected OAuth flow
• Ensure the integration user's profile allows API access

Insufficient Access (INSUFFICIENT_ACCESS)

• Verify the integration user has the correct profile and permission sets
• Check object-level permissions (CRUD) on the target object
• Verify field-level security allows access to the requested fields
• For custom objects: ensure the user has access to the custom object's tab

SOQL Syntax Error (MALFORMED_QUERY)

• Validate SOQL syntax in Salesforce Developer Console first
• Check that object and field API names are correct (not labels)
• Ensure date literals use Salesforce format (e.g., THIS_YEAR, LAST_N_DAYS:30)

Health Check

curl https://your-axonflow.example.com/mcp/connectors/salesforce-crm/health

Response:

{
  "healthy": true,
  "latency_ms": 150,
  "details": {
    "instance_url": "https://your-org.my.salesforce.com",
    "api_version": "v59.0",
    "org_id": "00Dxx0000001gER",
    "auth_type": "password"
  }
}

Related

• HubSpot Connector
• Snowflake Connector
• MCP Overview
• Connector SDK