MCP Server

Overview

CalyxCRM includes a built-in Model Context Protocol (MCP) server that allows AI assistants like Claude Desktop, Cursor, and other MCP-compatible clients to interact with your CRM data directly. The MCP server exposes the same capabilities as the REST API as structured tools that AI assistants can discover and call.

With MCP, your AI assistant can:

• List and inspect your data objects and their attributes
• Query, create, update, and delete records
• Log activities linked to records
• Run reports and retrieve results
• Trigger workflow automations
• View organization members

Authentication

The MCP server uses the same API keys as the REST API. Each MCP tool enforces the scopes assigned to the key, so an API key with only records:read will only expose read-only record tools.

See API Keys for instructions on creating and managing keys.

Server URL

The MCP server endpoint is:

https://your-domain.com/api/mcp/mcp

The server uses the Streamable HTTP transport (the modern replacement for SSE-based MCP).

Connecting AI Clients

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "calyx-crm": {
      "url": "https://your-domain.com/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer caly_your_api_key_here"
      }
    }
  }
}

Cursor

Add this to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "calyx-crm": {
      "url": "https://your-domain.com/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer caly_your_api_key_here"
      }
    }
  }
}

Claude Code

Add this to your project's .mcp.json:

{
  "mcpServers": {
    "calyx-crm": {
      "type": "url",
      "url": "https://your-domain.com/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer caly_your_api_key_here"
      }
    }
  }
}

Other MCP Clients

Any MCP-compatible client that supports Streamable HTTP transport can connect by pointing to the server URL and passing the API key as a Bearer token in the Authorization header.

Available Tools

The MCP server registers the following tools, grouped by resource. Each tool requires the corresponding API key scope.

Objects

Records

Attributes

Activities

Reports

Workflows

Members

Files

Webhooks

Tool Input and Output

All tool inputs are structured JSON parameters. The AI client handles serialization automatically. Tool outputs are JSON strings containing the same response shapes as the REST API.

Example: listing objects

The AI assistant calls list_objects with no parameters. The tool returns:

{
  "objects": [
    {
      "id": "uuid",
      "type": "standard",
      "pluralName": "People",
      "singularName": "Person",
      "slug": "people",
      "isActive": true,
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Example: searching records

The assistant calls search_records with:

{
  "objectId": "uuid",
  "filters": [
    { "attributeSlug": "status", "operator": "equals", "value": "active" },
    { "attributeSlug": "email", "operator": "contains", "value": "@example.com" }
  ],
  "sort": { "field": "created_at", "order": "desc" },
  "limit": 25
}

Error Handling

If a tool encounters an error (missing scope, not found, validation failure), it returns an error object with isError: true:

{
  "error": "Object not found"
}

{
  "error": "Insufficient scope: this API key does not have the required scope \"records:write\""
}

MCP vs REST API

Both interfaces expose the same data and enforce the same security model. Use the REST API for programmatic integrations and the MCP server for AI assistant access.

Dashboard Configuration

You can find the MCP server URL and ready-to-copy client configuration snippets in:

1. Navigate to Organization Settings in the sidebar
2. Click Developers
3. Select the MCP tab

Next Steps

• API Keys - Create and manage API keys for MCP authentication
• API Reference - Detailed documentation for all available operations
• Webhooks - Subscribe to real-time CRM events