Connect Your CRM to Claude via MCP: Step-by-Step Tutorial

Imagine asking Claude: "Which clients haven't been followed up with in 30 days?" and getting an accurate answer pulled from your CRM in real time. That's exactly what the MCP protocol, or Model Context Protocol, developed by Anthropic, enables. In 2026, integrating AI tools with business systems is no longer a luxury reserved for large structures. SMEs and web agencies are massively adopting these connections to automate their business workflows, reduce manual data entry, and finally exploit dormant customer data in their CRM. At Akolads, we guide our clients through this type of integration on a daily basis. In this tutorial, we break down each step: understanding MCP, preparing your environment, writing the MCP server, and connecting Claude to your CRM. Whether you use HubSpot, Salesforce, Pipedrive, or a custom CRM developed in Ruby on Rails, this guide adapts to your stack.

Understanding the MCP protocol and how it works

The Model Context Protocol (MCP) is an open standard published by Anthropic in 2024. It defines how a language model like Claude can interact with external data sources. Think of it as a USB-C for AI: a standardized interface that connects any tool to any model.

MCP: the abstraction layer between Claude and your data

Concretely, your CRM becomes a toolbox that Claude explores. It can read a contact record, create an opportunity, update a status, or trigger a workflow — all in natural language.

The three key components of MCP

• MCP Host: the application that hosts Claude (Claude Desktop, your in-house app, etc.).
• MCP Client: the part of the host that manages the connection with the MCP server.
• MCP Server: your server that exposes your CRM's capabilities to Claude.

MCP vs traditional API: what really changes

Why Claude is particularly suited for MCP

Claude 3.5 Sonnet and later versions natively handle MCP tool calls with above-average precision. In our internal tests at Akolads, Claude correctly identifies which tool to call in 94% of cases without additional instruction. This is a decisive advantage for complex CRM integrations.

« MCP transforms Claude into a true business collaborator: it no longer responds, it acts. »

Prepare your environment and your CRM

Before writing a single line of code, properly preparing your environment will save you 80% of common errors. This phase takes 15 to 30 minutes depending on your CRM.

Essential technical requirements

• Node.js 20+ or Python 3.11+ installed on your machine or server.
• Anthropic API key with Claude 3.5 Sonnet minimum access.
• Your CRM API access (OAuth2 token or API key).
• Claude Desktop (version 0.10+) or an MCP-compatible application.
• A code editor like VS Code with the MCP Inspector extension (optional but recommended).

Get your CRM credentials

Each CRM has its own authentication workflow. Here are the fastest paths:

• HubSpot: Settings → Integrations → Private Apps → Create. Check the CRM scopes (contacts, deals, companies).
• Salesforce: Setup → App Manager → New Connected App. Enable OAuth and retrieve client_id + client_secret.
• Pipedrive: Settings → Personal Preferences → API → Generate Token.
• Custom CRM (Rails): create a dedicated API endpoint with Bearer token authentication.

Store these credentials in a local .env file. Never commit them to your Git repository.

Define the scope of authorized CRM actions

This is the step most developers forget. Before coding, list precisely what Claude can do on your CRM. For example:

• Read: contacts, deals, activities, notes, reports.
• Write: create a note, update a deal status, add a tag.
• Forbidden: delete records, bulk export, access billing data.

This principle of least privilege is fundamental to integration security.

Install the official MCP SDK

Anthropic provides official SDKs in TypeScript and Python. For a CRM integration, we recommend TypeScript for its robustness:

npm install @modelcontextprotocol/sdk

For Python: pip install mcp

These SDKs automatically handle the communication protocol, JSON serialization, and error handling. You focus only on business logic.

Create and configure your MCP server

The MCP server is the heart of the integration. It translates Claude's requests into API calls to your CRM. Here's how to build it from A to Z.

Basic structure of an MCP server

Create a crm-server.ts file and initialize your server:

The minimal structure includes three elements: the server declaration with its name and version, the list of available tools with their JSON schema, and the execution handler that actually calls your CRM. Each tool must have an explicit name, a natural language description, and a precise parameter schema. Claude will rely on these descriptions to know when and how to use each tool.

Define essential CRM tools

For effective CRM integration, start with these 5 fundamental tools:

• search_contacts: searches for a contact by name, eMayl, or company.
• get_contact_details: retrieves the complete contact record (history, deals, notes).
• create_note: adds a note to a contact or deal.
• update_deal_stage: updates the stage of a sales opportunity.
• list_overdue_tasks: lists overdue tasks for a salesperson or team.

Each tool must return structured and readable JSON. Claude will then reformat this data for the user.

Handle errors and timeouts

CRMs can be slow or unavailable. Systematically integrate:

• 10-second timeout on each CRM API call.
• Explicit error messages returned to Claude (no raw throws).
• Automatic retry (2 attempts maximum) on 5xx errors.
• Structured logging of each call to facilitate debugging.

« A poorly managed MCP server in terms of errors turns Claude into a frustrating assistant. Robustness is not optional. »

Test your server with MCP Inspector

Before connecting Claude, validate your server with the official tool:

npx @modelcontextprotocol/inspector node crm-server.js

The MCP Inspector web interface opens on port 5173. You can call each tool manually, inspect requests/responses, and validate JSON schemas. Test each tool with real data before moving to the next step. An untested tool is a bug waiting to happen.

Connect Claude to your CRM: production deployment

Your MCP server is ready. It's time to connect it to Claude and put the integration in the hands of your teams.

Configuration in Claude Desktop

Claude Desktop is the fastest solution to test in real conditions. Edit the configuration file:

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

Add your server in the mcpServers section with the startup command and your environment variables. Restart Claude Desktop. A plug-shaped icon appears in the interface: your CRM is connected.

First tests in natural language

Start with simple queries to validate the integration:

• "Find the contact Jean Dupont in the CRM and tell me where his deal stands."
• "List my 5 deals in negotiation that haven't changed in 2 weeks."
• "Add a note to the Acme Corp account: follow-up meeting scheduled for April 15."

Observe how Claude automatically selects the right tool, structures his request, and reformats the CRM response in natural language.

Integrate MCP into a custom web application

For production deployment, you will likely integrate MCP into your own interface. At Akolads, we build custom applications, often in Ruby on Rails for robustness and development speed. The Anthropic API supports MCP via the tools parameter in /messages requests. You can thus create an internal interface where your sales teams access Claude-CRM directly in their daily workflow.

Deploying the MCP server in production

For team use, deploy your MCP server on a dedicated server:

• SSE transport (Server-Sent Events) for remote connections: preferable to stdio transport for production.
• HTTPS mandatory with a valid certificate.
• Authentication: add a token verification middleware before each MCP request.
• Monitoring: integrate metrics (response time, errors, usage per user).

Best practices, security, and optimizations

An MCP integration that works in demo can quickly become a problem in production if best practices are not followed. Here is what we systematically apply at Akolads.

Secure CRM data access

Security must be considered at every layer:

• Principle of least privilege: each Claude user only accesses data within their scope.
• Audit log: track each action executed by Claude with the user identifier and timestamp.
• Credential encryption: use a secrets manager (HashiCorp Vault, AWS Secrets Manager).
• Rate limiting: limit the number of CRM API calls per minute to prevent abuse.

These measures are particularly important if you manage GDPR data. To learn more about managing your digital visibility, consult our guide on SEO GEO and ChatGPT in 2026.

Optimize integration performance

A few simple optimizations multiply perceived fluidity:

• Redis cache for low-volatility CRM data (contact cards, pipeline stages).
• Intelligent pagination: never return more than 20 results to Claude at once.
• Concise tool descriptions: overly long descriptions slow down inference.
• MCP server warm-up at startup to avoid cold starts.

Maintain and evolve your integration

The MCP protocol evolves rapidly. Plan for maintenance from the start:

• Version your MCP server (v1.0, v1.1…) and document tool changes.
• Subscribe to MCP SDK GitHub releases to follow developments.
• Budget for annual maintenance: consult our guide on website maintenance rates in 2026 to calibrate your budget.

Measure the ROI of your CRM-Claude integration

How do you know if the integration truly creates value? Measure these KPIs from the start:

• Average CRM information search time (before / after).
• Number of CRM notes and updates per sales representative per week.
• Adoption rate of the Claude-CRM interface in sales teams.
• Reduction in data entry errors thanks to automatic validation.

Our clients who have deployed this integration report an average of 2.5 hours saved per sales representative per week. For a team of 10 people, that's a productivity gain equivalent to 1 FTE. To discuss your integration project, contact the Akolads team.

FAQ