Ambivo MCP Server

This MCP (Model Context Protocol) server provides access to Ambivo API endpoints for natural language querying of entity data.

Features

• Natural Language Queries: Execute natural language queries against entity data using the /entity/natural_query endpoint
• JWT Authentication: Secure access using Bearer token authentication
• Rate Limiting: Built-in rate limiting to prevent API abuse
• Token Caching: Efficient token validation with caching
• Error Handling: Comprehensive error handling with detailed error messages
• Retry Logic: Automatic retry with exponential backoff for failed requests
• Remote Hosting Support: Can be hosted in the cloud for multi-user access via HTTP/SSE transport

Tools

1. set_auth_token

Set the JWT Bearer token for authentication with the Ambivo API.

Parameters:

• token (string, required): JWT Bearer token

Usage:

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

2. natural_query

Execute natural language queries against Ambivo entity data.

Parameters:

• query (string, required): Natural language query describing what data you want
• response_format (string, optional): Response format - "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"
}

Installation

Option 1: Install from PyPI (Recommended)

pip install ambivo-mcp-server

# For remote server support (optional)
pip install "ambivo-mcp-server[remote]"

Option 2: Install from Source

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

# For remote server support (optional)
pip install -e ".[remote]"

Running the Server

Local Mode (Default)

# If installed via pip
ambivo-mcp-server

# Or using Python module
python -m ambivo_mcp_server.server

Remote Mode (Cloud Hosting)

Host the server in the cloud for multiple users:

1. Start the HTTP/SSE server (on your cloud server):

python http_sse_server.py

2. Configure Claude Desktop (on user's machine):

{
  "mcpServers": {
    "ambivo": {
      "command": "python",
      "args": ["-m", "http_sse_client_bridge"],
      "env": {
        "MCP_SERVER_URL": "https://your-server.com",
        "AMBIVO_AUTH_TOKEN": "user-jwt-token"
      }
    }
  }
}

See INSTALL_HTTP_SSE.md for detailed cloud deployment instructions.

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

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

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

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.