Agentforce MCP Server

# Agentforce MCP Server This MCP server provides tools to interact with the Salesforce Agentforce API. It allows authentication, session creation, and message exchange with Agentforce agents. ## Getting Started After Cloning If you've just cloned this repository, you can use the interactive setup script to quickly configure and run the server: ```bash chmod +x setup.sh ./setup.sh ``` The setup script will: 1. Check your Python version 2. Install required dependencies 3. Guide you through entering your Salesforce credentials 4. Test your connection to Salesforce 5. Offer to start the server 6. Provide instructions for configuring Claude Desktop Alternatively, you can follow these manual steps: 1. **Install dependencies**: ```bash pip install -r requirements.txt ``` 2. **Set up your environment variables**: ```bash cp .env.example .env ``` 3. **Collect your Salesforce credentials**: - **SALESFORCE_ORG_ID**: Your 18-character Salesforce Org ID - **SALESFORCE_AGENT_ID**: The 18-character Agent ID from your Agentforce agent - **SALESFORCE_CLIENT_ID**: The Consumer Key from your Connected App - **SALESFORCE_CLIENT_SECRET**: The Consumer Secret from your Connected App - **SALESFORCE_SERVER_URL**: Your Salesforce My Domain URL without https:// prefix 4. **Edit your .env file** with the collected credentials: ``` 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: These are fictional example values. Replace with your actual credentials.) 5. **Make the server script executable**: ```bash chmod +x agentforce_mcp_server.py ``` 6. **Run the server**: ```bash python agentforce_mcp_server.py ``` For detailed instructions on finding your Salesforce credentials, see the [Setting Up Salesforce](#setting-up-salesforce) section below. ## Setup 1. Ensure you have Python 3.10 or higher installed. 2. Install the required dependencies: ```bash pip install -r requirements.txt ``` 3. Make the server script executable: ```bash chmod +x agentforce_mcp_server.py ``` ## Configuration The server uses environment variables for configuration. These are loaded from the `.env` file. 1. Copy the example environment file to create your own: ```bash cp .env.example .env ``` 2. Edit the `.env` file and fill in your values: ``` SALESFORCE_ORG_ID="your_org_id_here" SALESFORCE_AGENT_ID="your_agent_id_here" # The 18-character Agent ID you found in Salesforce SALESFORCE_CLIENT_ID="your_client_id_here" # The Consumer Key from your Connected App SALESFORCE_CLIENT_SECRET="your_client_secret_here" # The Consumer Secret from your Connected App SALESFORCE_SERVER_URL="your_server_url_here" # Your My Domain URL (e.g., example.my.salesforce.com) ``` ## Salesforce Configuration To use the Agentforce API, you need to: 1. Create a Connected App in your Salesforce org 2. Find your Agentforce Agent ID 3. Note your Salesforce My Domain URL For detailed instructions on these steps, see the [Setting Up Salesforce](#setting-up-salesforce) section below. ## Running the Server Run the server using: ```bash python agentforce_mcp_server.py ``` ## Available Tools The MCP server exposes the following tools: ### 1. `authenticate` Authenticates with the Agentforce API using a client email. Parameters: - `client_email`: Email of the client for authentication ### 2. `create_agent_session` Creates a session with the configured Agentforce agent. Parameters: - `client_email`: Email of the authenticated client ### 3. `send_message_to_agent` Sends a message to the Agentforce agent and returns the response. Parameters: - `client_email`: Email of the authenticated client - `message`: Message to send to the agent ### 4. `get_session_status` Gets the status of the current session, including authentication status, session ID, and sequence ID. Parameters: - `client_email`: Email of the authenticated client ### 5. `complete_agentforce_conversation` Convenience method that handles the complete flow - authentication, session creation, and message sending. Parameters: - `client_email`: Email of the client for authentication - `user_query`: Message to send to the agent ## Using with Claude for Desktop To use this server with Claude for Desktop, update your `claude_desktop_config.json` file: ```json { "mcpServers": { "agentforce": { "command": "python", "args": [ "/path/to/your/agentforce_mcp_server.py" ] } } } ``` Replace the path with the absolute path to the server script on your machine. ### Path Locations by Platform #### macOS - Configuration file: `~/Library/Application Support/Claude/claude_desktop_config.json` - Example path: `/Users/yourusername/Projects/agentforce-mcp-server/agentforce_mcp_server.py` #### Windows - Configuration file: `%APPDATA%\Claude\claude_desktop_config.json` - Example path: `C:\Users\yourusername\Projects\agentforce-mcp-server\agentforce_mcp_server.py` ## Setting Up Salesforce ### Creating a Connected App To use the Agentforce API, you need to create a Connected App in your Salesforce org: 1. Log in to your Salesforce org as an administrator 2. Go to **Setup** 3. In the Quick Find box, search for "App Manager" and click on it 4. Click the **New Connected App** button 5. Fill in the basic information: - **Connected App Name**: Agentforce MCP Integration (or any name you prefer) - **API Name**: Agentforce_MCP_Integration (this will be auto-filled) - **Contact Email**: Your email address 6. Check **Enable OAuth Settings** 7. Set the **Callback URL** to `https://localhost/oauth/callback` (this is not used but required) 8. Under **Selected OAuth Scopes**, add: - Manage user data via APIs (api) - Perform requests at any time (refresh_token, offline_access) 9. Click **Save** 10. After saving, you'll be redirected to the Connected App detail page 11. Note the **Consumer Key** (this is your client ID) and click **Click to reveal** next to **Consumer Secret** to get your client secret ### Finding Your Agent ID To find your Agentforce Agent ID: 1. Log in to your Salesforce org 2. Navigate to **Einstein Agent Builder** 3. Select the agent you want to use 4. Look at the URL in your browser - it will contain the Agent ID in the format: `https://your-salesforce-instance.lightning.force.com/lightning/r/Agent__c/0XxXXXXXXXXXXXXX/view` 5. The Agent ID is that 18-character ID (`0XxXXXXXXXXXXXXX`) in the URL ### Finding Your Salesforce My Domain URL To find your Salesforce My Domain URL: 1. Log in to your Salesforce org 2. Go to **Setup** 3. In the Quick Find box, search for "My Domain" and click on it 4. You'll see your domain in the format `DOMAIN-NAME.my.salesforce.com` 5. Use this URL without the "https://" prefix in your .env file ### Finding Your Org ID To find your Salesforce Org ID: 1. Log in to your Salesforce org 2. Go to **Setup** 3. In the Quick Find box, search for "Company Information" and click on it 4. Look for the "Organization ID" field - this is your Salesforce Org ID 5. It will be a 15 or 18-character alphanumeric string ## Notes - The server automatically manages sequence IDs for message exchanges - Authentication and session state are maintained for each client email - All API interactions are logged for debugging purposes ## Troubleshooting If you encounter issues: 1. **Authentication failures**: Verify your Connected App settings and ensure the client ID and secret are correct 2. **Session creation errors**: Check your Agent ID and make sure it's the 18-character version 3. **Connection issues**: Verify your Salesforce My Domain URL is correct (without "https://" prefix) 4. **Permission errors**: Make sure your Connected App has the proper OAuth scopes enabled ## Testing the Setup You can test your setup using the included test script: ```bash python test_agentforce.py ``` This will attempt to authenticate, create a session, and exchange messages with your Agentforce agent. ## Contributing and GitHub Push This repository includes a helpful script that simplifies the process of pushing your changes to GitHub: ```bash chmod +x github_push.sh ./github_push.sh ``` The `github_push.sh` script will: 1. Check if git is installed on your system 2. Verify that sensitive files like `.env` won't be pushed (they're in `.gitignore`) 3. Prompt you for your GitHub repository URL 4. Initialize a git repository if needed, or update the remote URL 5. Add all files and display them for your review 6. Commit the changes with a descriptive message 7. Push the changes to GitHub This makes it easy to share your customizations or contribute back to the project while ensuring that sensitive information stays secure.