Overview

The Salesforce MCP Server implements the Model Context Protocol (MCP) to provide a universal integration layer for Salesforce orgs. It handles OAuth-based authentication, adaptive synchronization of records and metadata (including custom objects and fields), full CRUD operations through a consistent API, and on-demand backups. The server is intended as a middleware component that lets other services or agents work with Salesforce without needing bespoke connector code for each org.

This is useful when you need a repeatable, secure way to integrate many Salesforce orgs into your systems. It abstracts OAuth lifecycle, token refresh, metadata discovery, and incremental data sync into a single service that supports both standard and custom objects. The MCP Server is particularly helpful for building automation, analytics pipelines, or federated applications that must interact reliably with arbitrary Salesforce org schemas.

Features

OAuth 2.0 flow for Salesforce (authorization code / refresh tokens)
Adaptive sync: automatic discovery of objects, fields, and relationships
Full CRUD API mapping to Salesforce SObjects (including custom objects/fields)
Backup/export of org data and metadata (JSON/NDJSON export support)
Incremental / full sync strategies with conflict handling
Token encryption and secure storage recommendations
Lightweight REST endpoints for integration with MCP-aware clients
Extensible: plugin points for custom transforms, filters, or storage backends

Installation / Configuration

Clone the repository and install dependencies. Example assumes Node.js environment:

# Clone and install
git clone https://github.com/AiondaDotCom/mcp-salesforce.git
cd mcp-salesforce
npm install

Environment variables (example .env):

PORT=8080
SALESFORCE_CLIENT_ID=your_connected_app_client_id
SALESFORCE_CLIENT_SECRET=your_connected_app_client_secret
SALESFORCE_REDIRECT_URI=https://yourserver.example.com/oauth/callback
MCP_SECRET=long_random_secret_for_token_encryption
DATABASE_URL=postgres://user:pass@localhost:5432/mcp
BACKUP_DIR=/var/backups/mcp-salesforce

Start the server:

npm start
# or with NODE_ENV=production
NODE_ENV=production npm start

Docker (optional):

docker build -t mcp-salesforce .
docker run -p 8080:8080 \
  -e SALESFORCE_CLIENT_ID=... \
  -e SALESFORCE_CLIENT_SECRET=... \
  -e SALESFORCE_REDIRECT_URI=https://yourserver.example.com/oauth/callback \
  -e DATABASE_URL=postgres://... \
  mcp-salesforce

Salesforce Connected App setup:

Create a Connected App in your Salesforce org.
Set OAuth callback URL to SALESFORCE_REDIRECT_URI.
Enable “Use digital signatures” if you prefer JWT flows, otherwise use standard authorization code flow.
Grant scopes: api, refresh_token, offline_access (as needed).

Available Resources

API endpoints (examples)

Path	Method	Purpose
/oauth/authorize	GET	Start OAuth flow to link a Salesforce org
/oauth/callback	GET	OAuth callback—stores tokens and org metadata
/mcp/sync	POST	Trigger adaptive sync for an org (full or incremental)
/mcp/backup	POST	Create a backup export of data/metadata
/mcp/sobjects/:name	GET/POST/PUT/DELETE	CRUD proxy for SObjects (supports custom objects)
/health	GET	Server health/status

Example: start OAuth link (open in browser)

GET /oauth/authorize?org_alias=acme

Example: CRUD create (custom object example)

curl -X POST "https://yourserver.example.com/mcp/sobjects/Invoice__c" \
  -H "Authorization: Bearer <mcp-api-key-or-session>" \
  -H "Content-Type: application/json" \
  -d '{"Account__c":"001xx000003DGbY","Amount__c":1250.00,"Description__c":"Monthly subscription"}'

Example: trigger backup

curl -X POST "https://yourserver.example.com/mcp/backup" \
  -H "Authorization: Bearer <admin-key>" \
  -H "Content-Type: application/json" \
  -d '{"orgId":"00Dxx0000001gER","mode":"full","format":"ndjson"}'

Use Cases

Centralized integration layer: Expose a single API to downstream services that need to read/write data across many Salesforce orgs without implementing per-org logic.
Analytics and ETL: Use adaptive sync to discover the schema for custom objects, then export backups or stream incremental changes into a data warehouse.
CRM automation: Create or update records in multiple orgs through consistent MCP CRUD endpoints (e.g., provisioning customers in partner orgs).
Disaster recovery: Run scheduled backups of metadata and records to local storage or object storage as NDJSON/JSON for easy restores.
Multi-tenant SaaS connectors: Offer tenants automatic onboarding using OAuth and keep data synchronized with minimal maintenance.

Security and Best Practices

Always run behind HTTPS and restrict the OAuth redirect URI to your server domain.
Store client secrets and refresh tokens encrypted (MCP_SECRET in example). Use a managed secrets service if available.
Use least-privilege scopes for connected apps and rotate client secrets periodically.
Audit sync and backup operations; consider rate limiting and org-specific quotas.
Validate and sanitize data transformations when working with custom fields and types.

Getting Help and Contributing

Source code and issues are hosted on GitHub: https://github.com/AiondaDotCom/mcp-salesforce. Open an issue for bugs or feature requests, and check the repo for contribution guidelines and any plugin hooks for extending sync and storage behavior.

Salesforce MCP Server: OAuth, Adaptive Sync, Backup, CRUD