Skip to main content
Glama

Ambivo MCP Server

Official
by ambivo-corp

Ambivo Claude MCP Server

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

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

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" }

About

This is a pure Claude-based MCP server implementation for the Ambivo API, designed to work seamlessly with Claude Desktop and other Claude-compatible MCP clients. It enables natural language interaction with your Ambivo CRM data through Claude's powerful language understanding capabilities.

Installation

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

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.

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Provides access to Ambivo API endpoints for natural language querying of entity data through a Model Context Protocol server with JWT authentication.

  1. Features
    1. Tools
      1. 1. set_auth_token
      2. 2. natural_query
    2. About
      1. Installation
        1. Option 1: Install from PyPI (Recommended)
        2. Option 2: Install from Source
      2. Running the Server
        1. Configuration
          1. Authentication
            1. Error Handling
              1. API Endpoints
                1. /entity/natural_query
                2. /entity/data
              2. Example Workflow
                1. Development
                  1. Troubleshooting

                    Related MCP Servers

                    • A
                      security
                      F
                      license
                      A
                      quality
                      Provides Model Context Protocol tools for interacting with eToro's public API endpoints, allowing users to fetch portfolios, look up instrument details, and search for instruments while handling CORS restrictions.
                      Last updated -
                      3
                      1
                      TypeScript
                    • -
                      security
                      F
                      license
                      -
                      quality
                      A Model Context Protocol server implementation that connects to AWS Cognito for authentication and user management, providing tools for user flows including sign-up, sign-in, and password management.
                      Last updated -
                      1
                      JavaScript
                      • Apple
                      • Linux
                    • A
                      security
                      F
                      license
                      A
                      quality
                      A Model Context Protocol server that enables AI assistants to interact with the Omi API for retrieving and creating conversations and memories for users.
                      Last updated -
                      4
                      2
                      TypeScript
                    • A
                      security
                      F
                      license
                      A
                      quality
                      A comprehensive Model Context Protocol server that enables interaction with the Klaviyo API, providing tools and resources for managing customer profiles, lists, segments, campaigns, flows, and various marketing automation features.
                      Last updated -
                      47
                      2
                      JavaScript

                    View all related MCP servers

                    MCP directory API

                    We provide all the information about MCP servers via our MCP API.

                    curl -X GET 'https://glama.ai/api/mcp/v1/servers/ambivo-corp/ambivo-mcp-server'

                    If you have feedback or need assistance with the MCP directory API, please join our Discord server