Setting Up and Using the CRM MCP Server

What is the CRM MCP Server?

The CRM MCP Server provides a secure, standardized way for AI agents and other compatible applications to connect with your CRM data and services. It uses the Model Context Protocol (MCP) as a bridge, allowing an AI client to discover available tools, retrieve information, and perform authorized actions within your account. Through this server, AI assistants can work with data from services like Contacts, Conversations, Calendars, Opportunities, Payments, and Locations.

Key Benefits

• Centralized Access: Connect AI tools to multiple CRM services through a single endpoint.
• Secure Authentication: Control access using Private Integration Tokens with specific, scoped permissions.
• Natural Language Automation: Enable AI assistants to execute tasks based on plain-language instructions.
• Broad Compatibility: Connect with various MCP-compatible clients like Cursor, Windsurf, OpenAI Playground, and Claude-compatible applications.
• Simplified Integration: Use a standard HTTP-based connection without needing to build a custom integration from scratch.

Prerequisites

Before you begin, ensure you have the following:

• Access to the specific sub-account or location in your CRM you wish to connect to.
• A Private Integration Token for that location.
• The necessary scopes enabled for that token.
• The ID of the sub-account or location.
• An MCP-compatible client application.

How to Set Up the CRM MCP Server

Step 1: Create a Private Integration Token

This token allows your MCP client to authenticate with your CRM account.

1. Log in to your CRM and navigate to the desired sub-account or location.
2. Go to Settings.
3. Select Private Integrations.
4. Click Create New Integration.
5. Choose the required permission scopes for your workflow.
6. Click Create Integration.
7. Copy the generated token securely.

Step 2: Add the MCP Server to Your Client

Configure your MCP-compatible client to connect to the CRM MCP endpoint. You will typically add a server configuration that includes the endpoint URL and authentication headers.

Your configuration will need to include the following details:

• URL: The CRM MCP endpoint (e.g., ).
• Headers: An Authorization header set to Bearer <your-token> and a locationId header set to your location's ID.

Replace <your-token> with the Private Integration Token you copied and <your-location-id> with your location's ID.

Step 3: Select the Required Tools

Once connected, your client will display the available tools based on the scopes granted to your token. You can then select which specific tools your AI agent needs to use for its tasks.

Recommended Permission Scopes

Scopes define what your MCP client can read or modify. It is a security best practice to grant only the permissions necessary for your intended use. Commonly used scopes include:

• Contacts: View Contacts, Edit Contacts
• Conversations: View Conversations, Edit Conversations
• Conversation Messages: View Conversation Messages, Edit Conversation Messages
• Opportunities: View Opportunities, Edit Opportunities
• Calendars: View Calendars, Edit Calendars
• Calendar Events: View Calendar Events, Edit Calendar Events
• Payments: View Payment Orders, View Payment Transactions
• Other: View Custom Fields, View Forms, View Locations

Example Available Tools

The specific tools available to your client depend on the scopes you assigned. Examples of tools across different CRM services include:

• Get Calendar Events: Retrieve events using a user, group, or calendar ID.
• Get Contact / Update Contact / Create Contact: Fetch, modify, or create new contact records.
• Search Conversation: Search, filter, and sort conversations.
• Send a New Message: Post a message to a conversation thread.
• Get Custom Fields: Retrieve the custom field definitions for a location.

Security and Authentication Best Practices

• Principle of Least Privilege: Always assign the minimum set of scopes required for the AI agent's function.
• Secure Token Storage: Treat your Private Integration Token like a password. Store it securely and never expose it in public code repositories or client-side applications.
• Regular Audits: Periodically review your active Private Integrations and revoke any tokens that are no longer needed.