Salesforce Agentforce Communication Hub

This dedicated MCP server furnishes the necessary apparatus to interface directly with the Salesforce Agentforce remote procedure endpoints. Its primary functions encompass establishing authenticated client contexts, provisioning interaction channels (sessions), and ensuring reliable exchange of conversational data packets with Agentforce deployed agents.

Initial Repository Setup Procedures

Upon successfully cloning the repository, leverage the provided automated provisioning script for rapid configuration and deployment:

chmod +x setup.sh
./setup.sh

The execution of setup.sh will systematically perform the following: 1. Verify the operational status of the prerequisite Python runtime. 2. Install all requisite software dependencies. 3. Interactively solicit and store your necessary Salesforce access credentials. 4. Execute a connectivity validation test against the target Salesforce instance. 5. Offer to initiate the gateway server process. 6. Present configuration directives for integration with Claude Desktop environments.

Alternatively, follow these sequential manual configuration steps:

1. Dependency Installation: bash pip install -r requirements.txt

2. Environment Variable Definition: bash cp .env.example .env

3. Acquire Salesforce Credentials: Gather the following mandatory configuration parameters:

   • SALESFORCE_ORG_ID: The unique 18-character identifier for your Salesforce Organization.
   • SALESFORCE_AGENT_ID: The 18-character unique identifier associated with the target Agentforce agent.
   • SALESFORCE_CLIENT_ID: The Consumer Key provisioned via your Salesforce Connected Application.
   • SALESFORCE_CLIENT_SECRET: The corresponding Consumer Secret from the Connected Application.
   • SALESFORCE_SERVER_URL: The base URL of your Salesforce My Domain, explicitly excluding the https:// prefix.

4. Populate the .env Configuration File: Edit the .env file, substituting placeholders with your actual secrets: SALESFORCE_ORG_ID="00D5f000000J2PKEA0" SALESFORCE_AGENT_ID="0XxHn000000x9F1KAI" SALESFORCE_CLIENT_ID="3MVG9OGq41FnYVsFgnaG0AzJDWnoy37Bb18e0R.GgDJu2qB9sqppVl7ehWmJhGvPSLrrA0cBNhDJdsbZXnv52" SALESFORCE_CLIENT_SECRET="210117AC36E9E4C8AFCA02FF062B8A677BACBFFB71D2BB1162D60D316382FADE" SALESFORCE_SERVER_URL="example.my.salesforce.com" (Note: The values above are purely illustrative examples and must be replaced with live credentials.)

5. Set Executable Permission for Server Script: bash chmod +x agentforce_mcp_server.py

6. Initiate Server Execution: bash python agentforce_mcp_server.py

Refer to the subsequent section, "Salesforce Provisioning Details," for exhaustive guides on locating your required Salesforce configuration elements.

Provisioning Steps

1. Verify that Python version 3.10 or a newer iteration is installed and operational.

2. Install necessary library dependencies: bash pip install -r requirements.txt

3. Grant execution rights to the main server script: bash chmod +x agentforce_mcp_server.py

Configuration Mechanism

The server relies on environmental variables sourced from the designated .env file for its operational settings.

1. Duplicate the template environment file to establish your local configuration: bash cp .env.example .env

2. Modify the .env file, populating it with your specific values: SALESFORCE_ORG_ID="your_org_id_here" SALESFORCE_AGENT_ID="your_agent_id_here" # 18-character ID for the target Agentforce agent SALESFORCE_CLIENT_ID="your_client_id_here" # Consumer Key from the Connected App SALESFORCE_CLIENT_SECRET="your_client_secret_here" # Consumer Secret from the Connected App SALESFORCE_SERVER_URL="your_server_url_here" # My Domain URL (e.g., domain.my.salesforce.com)

Salesforce Prerequisites

To enable communication with the Agentforce API, the following setup tasks within Salesforce are mandatory:

1. Provision a suitable Connected Application within your Salesforce tenant.
2. Identify and retrieve the specific Agentforce Agent ID.
3. Record your Salesforce My Domain URL.

For comprehensive, step-by-step tutorials on these requirements, consult the "Salesforce Provisioning Details" section below.

Server Startup

Execute the gateway using the command:

python agentforce_mcp_server.py

Exposed Toolset

The MCP gateway exposes the following operational tools for external invocation:

1. authenticate

Establishes API access authorization against Agentforce using a provided client email address.

Parameters: - client_email: The electronic mail address of the client initiating authentication.

2. create_agent_session

Initializes a dedicated conversational session with the pre-configured Agentforce entity.

Parameters: - client_email: The electronic mail address of the authenticated client.

3. send_message_to_agent

Transmits a query or instruction to the Agentforce agent and awaits the subsequent response payload.

Parameters: - client_email: The electronic mail address of the authenticated client. - message: The textual content intended for transmission to the agent.

4. get_session_status

Retrieves the current operational status metrics of the active session, including authentication validity, the active session identifier, and the current sequence counter.

Parameters: - client_email: The electronic mail address of the authenticated client.

5. complete_agentforce_conversation

A streamlined utility encapsulating the entire interaction sequence: initial authentication, session establishment, and the subsequent message transmission.

Parameters: - client_email: The electronic mail address used for authentication. - user_query: The primary message content to deliver to the agent.

Integration with Claude Desktop

To integrate this server with the Claude Desktop application, modify your local configuration file, claude_desktop_config.json:

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

Replace /path/to/your/agentforce_mcp_server.py with the absolute filesystem path to the server script on your hosting machine.

Platform-Specific Path Locations

macOS

• Configuration File Location: ~/Library/Application Support/Claude/claude_desktop_config.json
• Illustrative Path Example: /Users/yourusername/Projects/agentforce-mcp-server/agentforce_mcp_server.py

Windows

• Configuration File Location: %APPDATA%\Claude\claude_desktop_config.json
• Illustrative Path Example: C:\Users\yourusername\Projects\agentforce-mcp-server\agentforce_mcp_server.py

Salesforce Provisioning Details

Connected Application Creation

To utilize the Agentforce API mechanisms, you must formally create a Connected App within your Salesforce organizational structure:

1. Log into Salesforce with administrative privileges.
2. Navigate to Setup.
3. Utilize the Quick Find search bar to locate and select "App Manager".
4. Click the button labeled New Connected App.
5. Populate the required fundamental metadata:
6. Connected App Name: e.g., Agentforce MCP Integration (or any descriptive label).
7. API Name: This field usually autocompletes (e.g., Agentforce_MCP_Integration).
8. Contact Email: Your designated contact email address.
9. Ensure the Enable OAuth Settings checkbox is selected.
10. Configure the Callback URL to be https://localhost/oauth/callback (this value is syntactically required, though often unused in this context).
11. Within the Selected OAuth Scopes section, explicitly grant:
12. Access to Manage user data via APIs (api)
13. Permission to execute requests at any time (refresh_token, offline_access)
14. Click Save.
15. Upon saving, the system will redirect you to the Connected App details view.
16. Record the displayed Consumer Key (Client ID). Then, click Click to reveal next to Consumer Secret to securely obtain the Client Secret.

Locating the Agent ID

To procure the specific Agentforce Agent ID:

1. Access your Salesforce organization.
2. Navigate to the Einstein Agent Builder interface.
3. Select the intended agent for interaction.
4. Inspect the URL displayed in your browser; the Agent ID is embedded within it, typically appearing like this: https://your-salesforce-instance.lightning.force.com/lightning/r/Agent__c/0XxXXXXXXXXXXXXX/view
5. The Agent ID is the 18-character alphanumeric string (0XxXXXXXXXXXXXXX).

Determining the Salesforce My Domain URL

To identify the necessary My Domain URL for configuration:

1. Log into Salesforce.
2. Access Setup.
3. Search for and click on "My Domain" in the Quick Find search.
4. Your domain string, formatted as DOMAIN-NAME.my.salesforce.com, will be displayed. Use this exact string, omitting https://, in your .env file.

Retrieving the Organization ID

To ascertain your Salesforce Org ID:

1. Log into Salesforce.
2. Navigate to Setup.
3. Search for and click on "Company Information".
4. Locate the field labeled "Organization ID". This is your Salesforce Org ID.
5. This identifier will be a string of 15 or 18 alphanumeric characters.

Operational Notes

• The server automatically manages the transactional sequence numbering for message exchanges.
• Authentication tokens and session persistence are maintained statefully on a per-client-email basis.
• All external API transactions are systematically logged to facilitate efficient debugging and auditing.

Troubleshooting Common Issues

Should operational difficulties arise, investigate the following:

1. Authorization Failures: Re-verify the Connected App configuration settings and confirm absolute accuracy of the Client ID and Secret.
2. Session Initialization Errors: Check the provided Agent ID, ensuring it conforms to the required 18-character standard.
3. Connectivity Problems: Confirm the Salesforce My Domain URL is accurate and free of the https:// protocol prefix.
4. Authorization Scope Errors: Validate that the Connected App has all necessary OAuth scopes explicitly enabled.

Validation Test Execution

Validate the entire provisioning process by running the integrated test harness:

python test_agentforce.py

This script will sequentially attempt authentication, session establishment, and a sample message interchange with your Agentforce agent.

Contribution and Source Code Synchronization

This repository includes a utility script to streamline the process of committing and pushing local modifications to GitHub:

chmod +x github_push.sh
./github_push.sh

The github_push.sh utility performs these actions:

1. Checks for the presence of the Git client on the system.
2. Ensures security-sensitive files (e.g., .env) are excluded from tracking (via .gitignore).
3. Prompts the user to supply the target GitHub repository URL.
4. Initializes Git tracking if necessary, or updates the existing remote origin.
5. Stages all tracked files and displays a summary for user review.
6. Creates a descriptive commit message.
7. Pushes the committed changes to the remote repository.

This automation facilitates straightforward sharing of enhancements or contributions while rigorously enforcing the security separation of sensitive configuration details.