Salesforce Agentforce Communication Hub (MCP Server)

This server instance is engineered to serve as a dedicated middleware layer for interfacing directly with the proprietary Salesforce Agentforce API suite. It abstracts away the complexities of direct API calls, offering streamlined endpoints for session management and conversational exchange with live agents.

Initial Deployment Sequence

For rapid deployment following repository cloning, utilize the provided automated setup utility:

chmod +x setup.sh
./setup.sh

The setup process automates: 1. Python environment verification (targeting 3.10+). 2. Installation of requisite software packages. 3. Interactive prompt for securing necessary Salesforce access credentials. 4. Connectivity diagnostic against the target Salesforce instance. 5. Optional initiation of the primary server process. 6. Guidance for integrating with the Claude Desktop environment.

Manual Configuration Steps

Should automated setup be bypassed, follow this sequence:

1. Prerequisite Installation: Install required libraries from the manifest file: bash pip install -r requirements.txt

2. Credential File Generation: Duplicate the template configuration file: bash cp .env.example .env

3. Environment Variable Population: Populate the .env file using the following required parameters:

   • SALESFORCE_ORG_ID: The 18-character identifier for your Salesforce Organization.
   • SALESFORCE_AGENT_ID: The specific 18-character identifier for the target Agentforce entity.
   • SALESFORCE_CLIENT_ID: The Consumer Key obtained from your registered Salesforce Connected Application.
   • SALESFORCE_CLIENT_SECRET: The corresponding Consumer Secret for the Connected Application.
   • SALESFORCE_SERVER_URL: The Salesforce My Domain URL (e.g., mycompany.my.salesforce.com), excluding the https:// prefix.

4. Configuration File Review: Inspect and confirm accuracy within the .env file (refer to the internal documentation for sample structures).

5. Server Executability: Grant execute permissions to the main server script: bash chmod +x agentforce_mcp_server.py

6. Service Launch: Initiate the MCP server: bash python agentforce_mcp_server.py

Refer to the 'Salesforce Credential Acquisition' section for comprehensive guides on locating these required secrets.

Core Functionality Endpoints

The gateway exposes the following callable tools:

1. establish_authentication

Secures initial authorization with the Agentforce infrastructure, typically keyed by a unique client identifier (email address).

Arguments: * client_identifier: The unique email associated with the client session.

2. initiate_agent_session

Establishes a dedicated, active communication channel with the pre-configured Agentforce recipient.

Arguments: * client_identifier: The email confirming the authenticated client identity.

3. transmit_message_to_agent

Forwards a user-generated query or input to the active Agentforce session, capturing the system's responsive output.

Arguments: * client_identifier: The email confirming the active client session. * user_payload: The textual content intended for the agent.

4. query_session_state

Retrieves the current operational metadata for the active interaction, including connection status, established session ID, and message sequencing markers.

Arguments: * client_identifier: The email confirming the client context.

5. orchestrate_full_dialogue

A convenience wrapper that sequentially executes authentication, session startup, and message transmission in a single invocation for simplified end-to-end queries.

Arguments: * client_identifier: The initiating client email. * user_query: The primary message to be delivered to the agent.

Desktop Integration Configuration

To link this gateway with the local Claude Desktop application, modify your configuration file (claude_desktop_config.json) as follows:

{
  "mcpServers": {
    "agentforce_connector": {
      "command": "python",
      "args": [
        "/absolute/path/to/your/agentforce_mcp_server.py"
      ]
    }
  }
}

Note: Substitute the placeholder path with the actual absolute file system location of the server script.

Platform-Specific File Paths

• macOS: Configuration path is typically ~/Library/Application Support/Claude/claude_desktop_config.json.
• Windows: Configuration path is typically %APPDATA%\Claude\claude_desktop_config.json.

Credential Acquisition Guidance (Salesforce)

Successful operation hinges on correctly configuring three primary Salesforce artifacts:

1. Connected Application Setup

This is mandatory for OAuth authorization:

1. Access Salesforce Setup as an administrative user.
2. Navigate to the App Manager section.
3. Initiate a New Connected App.
4. Supply descriptive metadata (Name: Agentforce MCP Integration recommended).
5. Crucially, Enable OAuth Settings.
6. Set the mandatory Callback URL to https://localhost/oauth/callback.
7. In Selected OAuth Scopes, grant at minimum: api (Manage user data) and refresh_token, offline_access (Perform requests at any time).
8. Upon saving, record the resulting Consumer Key (Client ID) and reveal/record the Consumer Secret (Client Secret).

2. Retrieving the Agent Identifier

1. Access the Einstein Agent Builder within your Salesforce environment.
2. Select the desired target agent.
3. Examine the resulting browser URL. The Agent ID is the 18-character unique record identifier (0Xx...) present in the path segment defining the record view (/lightning/r/Agent__c/0Xx.../view).

3. Locating Domain and Organization IDs

• My Domain URL: Found under Setup -> My Domain. Use the format DOMAIN-NAME.my.salesforce.com (HTTPS omitted).
• Organization ID: Found under Setup -> Company Information. Look for the 'Organization ID' field (15 or 18 characters).

Operational Notes

• Session sequencing (sequence IDs) is managed internally by the gateway.
• State persistence (authentication and session context) is tied directly to the client_identifier.
• All outbound/inbound API traffic is logged for diagnostic review.

Deployment Verification

Execute the accompanying test harness to confirm end-to-end capability:

python test_agentforce.py