Connect Cursor or Claude to 165 Typed CRM Tools With MCP

pp messages.

Core Solution

Implementing a safe AI-CRM integration requires a structured approach focusing on authentication, tool discovery, and safety enforcement. The following steps outline the architecture for connecting an agent to the FavCRM backend via MCP.

1. Authentication and Endpoint Configuration

The FavCRM MCP endpoint is hosted at https://api.favcrm.io/mcp. Authentication uses a Bearer token format. The token must be sourced from an environment variable to prevent secret leakage in version control.

Architecture Decision: Use environment variables for secrets. This ensures that credentials are never committed to repositories and can be rotated without code changes.

Configuration Example: Update your MCP client configuration (e.g., ~/.cursor/mcp.json or Claude Desktop config) with the following structure. Note the use of a distinct server name and environment variable reference.

{
  "mcpServers": {
    "crm_backend": {
      "url": "https://api.favcrm.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CRM_MCP_TOKEN}"
      }
    }
  }
}

Set the environment variable in your shell or IDE configuration:

export CRM_MCP_TOKEN=fav_mcp_your_unique_key_here

2. Tool Discovery and Inspection

Once connected, the agent can query the tool catalog. It is critical to inspect tools before invocation to understand their schemas and safety annotations.

Best Practice: Always use the tool describe command to review a tool's metadata. This reveals the input schema, output shape, and annotations such as read_only or external_service.

CLI Inspection Workflow:

# List all available tools
favcrm tool list

# Inspect a specific tool for safety and schema
favcrm tool describe create_booking
favcrm tool describe cancel_booking

3. Programmatic Safety Enforcement

For custom agent implementations, leverage the tool annotations to enforce safety programmatically. The following TypeScript example demonstrates how to check annotations before executing a tool.

import { Client } from '@modelcontextprotocol/sdk/client/index.js';

async function executeWithSafetyCheck(client: Client, toolName: string, args: Record<string, any>) {
    // Retrieve tool metadata
    const toolInfo = await client.callTool({ name: 'tool_describe', arguments: { tool: toolName } });
    
    const annotations = toolInfo.annotations || {};

    // Safety Gate 1: Read-only check
    if (annotations.readOnly) {
        console.log(`Executing safe read-only tool: ${toolName}`);
        return await client.callTool({ name: toolName, arguments: args });
    }

    // Safety Gate 2: External service warning
    if (annotations.externalService) {
        console.warn(`Warning: ${toolName} interacts with external services. Proceed with caution.`);
    }

    // Safety Gate 3: Plan verification for gated operations
    if (annotations.requiresPlanCheck) {
        const planStatus = await client.callTool({ name: 'plan_check', arguments: { tool: toolName } });
        if (!planStatus.allowed) {
            throw new Error(`Operation ${toolName} blocked by plan restrictions.`);
        }
    }

    // Execute write operation
    return await client.callTool({ name: toolName, arguments: args });
}

4. Approval-Gated Workflows

Customer-facing operations, such as WhatsApp messages, SMS, email campaigns, and inbox replies, must never be executed blindly. Implement an approval workflow where the agent drafts the message and requests user confirmation.

Pattern:

1. Agent calls draft_message to generate content.
2. Agent presents draft to user with recipient details.
3. User approves via request_send_approval.
4. Agent executes send_message only after approval.

This pattern ensures agents have operational power without the risk of silent customer communication.

5. Plan Checks Before Gated Operations

Certain operations depend on billing state, module availability, or quota limits. Before executing write operations that might be gated, the agent must verify plan eligibility.

CLI Verification:

# Check overall plan status
favcrm plan status

# Verify specific tool eligibility
favcrm plan check --tool create_account
favcrm plan check --module whatsapp

If an upgrade is required, the backend returns an upgrade action. The agent should prompt the user for confirmation before triggering any payment flows:

favcrm plan upgrade --plan-code favcrm-lite --confirm

Pitfall Guide

Avoid these common mistakes when integrating AI agents with CRM tools via MCP.

Pitfall	Explanation	Fix
Hardcoded Secrets	Embedding API keys directly in config files or code repositories.	Use environment variables (${env:VAR}) and secret managers. Never commit keys.
Ignoring Annotations	Executing tools without checking safety metadata, leading to unsafe writes.	Implement annotation checks in your agent loop. Respect read_only, external_service, and requires_approval.
Skipping Plan Checks	Attempting gated operations without verifying plan eligibility, causing runtime errors.	Call plan check before write operations. Handle upgrade prompts gracefully.
Blind Customer Sends	Allowing agents to send messages without user review.	Enforce approval-gated workflows for all customer-facing communications.
Empty List Misinterpretation	Treating empty results from list tools as errors.	Recognize that empty lists (e.g., list_services) indicate valid state, not failure.
Write Bias	Prioritizing write operations over read operations during exploration.	Adopt a "read-only first" strategy. Inspect data before modifying it.
Missing Schema Validation	Passing malformed arguments to tools due to lack of schema awareness.	Use tool describe to fetch input schemas and validate arguments before invocation.

Production Bundle

Action Checklist

• Generate API Key: Create a fav_mcp_* token in your FavCRM workspace.
• Set Environment Variable: Export CRM_MCP_TOKEN in your shell or IDE.
• Update MCP Config: Add the server URL and auth header to ~/.cursor/mcp.json or equivalent.
• Verify Connection: Restart your IDE and confirm the crm_backend server connects successfully.
• Run Smoke Tests: Execute favcrm doctor and favcrm tool list to validate the catalog.
• Inspect Safety Metadata: Use favcrm tool describe on critical tools to review annotations.
• Configure Approval Gates: Set up workflows for customer-facing tools like WhatsApp and SMS.
• Test Plan Checks: Verify plan check behavior for gated operations.

Decision Matrix

Use this matrix to select the appropriate integration strategy based on your scenario.

Scenario	Recommended Approach	Why	Cost Impact
Local Development	Environment variables + CLI	Fast setup; easy iteration	Free
Production Agent	Secret Manager + MCP Client	Secure credential handling; scalable	Low (Secret Manager cost)
High-Volume Writes	Rate Limiting + Plan Checks	Prevents quota exhaustion; ensures stability	N/A
Customer Comms	Approval-Gated Workflow	Prevents unintended messages; maintains trust	N/A
Multi-Module CRM	Module-Specific Plan Checks	Ensures feature availability; avoids errors	N/A

Configuration Template

Copy this template to configure your MCP client. Replace placeholders with your actual values.

{
  "mcpServers": {
    "crm_backend": {
      "url": "https://api.favcrm.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CRM_MCP_TOKEN}"
      },
      "env": {
        "FAVCRM_WORKSPACE_ID": "${env:FAVCRM_WORKSPACE_ID}"
      }
    }
  }
}

Quick Start Guide

Get your AI agent connected to FavCRM in under 5 minutes.

1. Obtain Token: Generate your fav_mcp_* API key from the FavCRM dashboard.
2. Export Variable: Run export CRM_MCP_TOKEN=fav_mcp_... in your terminal.
3. Update Config: Add the JSON configuration to ~/.cursor/mcp.json.
4. Restart IDE: Reload Cursor or Claude Desktop to apply changes.
5. Validate: Run favcrm doctor to confirm connectivity and favcrm tool list to view the catalog.

By following this guide, you establish a secure, metadata-driven integration that empowers your AI agent to operate safely within your CRM environment. The combination of typed tools, safety annotations, and approval workflows ensures that agents can drive business value without compromising data integrity or customer trust.