Ambivo MCP Server

A Model Context Protocol (MCP) server for interacting with the Ambivo CRM API using natural language.

Features

• Natural language queries for entity data (leads, contacts, opportunities, etc.)

• Direct entity data access with structured parameters

• Response formatting options: table, natural language, or both

• Standards‑based error handling with clear messages

Overview

This server enables you to query your Ambivo CRM data conversationally. You can ask things like:

• "Show me leads created this week"

• "Find contacts with gmail addresses"

• "List opportunities worth more than $10,000"

• "Show me leads with attribution_source google_ads from the last 7 days"

Installation

Option 1: Install from PyPI (Recommended)

pip install ambivo-mcp-server

Option 2: Install from Source

git clone https://github.com/ambivo-corp/ambivo-mcp-server.git
cd ambivo-mcp-server
pip install -e .

Running the Server

# If installed via pip
ambivo-mcp-server

# Or using Python module
python -m ambivo_mcp_server.server

Configuration

The server uses the following default configuration:

• Base URL: https://goferapi.ambivo.com

• Timeout: 30 seconds

• Content Type: application/json

You can modify these settings in the AmbivoAPIClient class if needed.

Authentication

1. First, set your authentication token using the set_auth_token tool

2. The token will be included in all subsequent API requests as a Bearer token

3. The token should be a valid JWT token from your Ambivo API authentication

Available Tools

set_auth_token

Sets the JWT token used for authentication.

Parameters:

• token (string, required) – the JWT token

Usage:\

{
  "token": "your-jwt-token-here"
}

natural_query

Processes a natural language query.

Parameters:

• query (string, required) – the natural language query

• response_format (string, optional) – "table", "natural", or "both" (default: "both")

Example queries:

• "Show me leads created this week"

• "Find contacts with gmail addresses"

• "List opportunities worth more than $10,000"

• "Show me leads with attribution_source google_ads from the last 7 days"

Usage:\

{
  "query": "Show me leads created this week with attribution_source google_ads",
  "response_format": "both"
}

entity_data

Direct entity data access with structured parameters.

Parameters: (depends on the endpoint – typical: entity type, fields, filters, etc.)

Usage:\

{
  "tool": "entity_data",
  "arguments": {
    "entity_type": "contact",
    "filters": {"email": {"$regex": "@gmail.com$"}},
    "limit": 100,
    "sort": {"created_date": -1}
  }
}

API Endpoints

This MCP server interfaces with these Ambivo API endpoints:

/entity/natural_query

• Method: POST

• Purpose: Process natural language queries for entity data retrieval

• Authentication: Required (JWT Bearer token)

• Content-Type: application/json

/entity/data

• Method: POST

• Purpose: Direct entity data access with structured parameters

• Authentication: Required (JWT Bearer token)

• Content-Type: application/json

Error Handling

The server provides comprehensive error handling:

• Authentication errors: Clear messages when token is missing or invalid

• HTTP errors: Detailed HTTP status codes and response messages

• Validation errors: Parameter validation with helpful error messages

• Network errors: Timeout and connection error handling

Example Workflow

1. Set Authentication:\

   {
     "tool": "set_auth_token",
     "arguments": {
       "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
     }
   }

2. Natural Language Query:\

   {
     "tool": "natural_query", 
     "arguments": {
       "query": "Show me all leads created in the last 30 days with phone numbers",
       "response_format": "both"
     }
   }

3. Direct Entity Query:\

   {
     "tool": "entity_data",
     "arguments": {
       "entity_type": "contact",
       "filters": {"email": {"$regex": "@gmail.com$"}},
       "limit": 100,
       "sort": {"created_date": -1}
     }
   }

Development

To extend this MCP server:

1. Add new tools: Implement additional tools in the handle_list_tools() and handle_call_tool() functions

2. Modify API client: Extend the AmbivoAPIClient class to support additional endpoints

3. Update configuration: Modify default settings in the configuration section

Troubleshooting

Common Issues:

1. "Authentication required" error: Ensure you've called set_auth_token first

2. HTTP 401/403 errors: Verify your JWT token is valid and not expired

3. Connection timeout: Check network connectivity and API endpoint availability

4. Invalid parameters: Review the tool schemas for required and optional parameters

Logging:

The server logs important events and errors. Check the console output for debugging information.