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
endpointJWT 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:
2. natural_query
Execute natural language queries against Ambivo entity data.
Parameters:
query
(string, required): Natural language query describing what data you wantresponse_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:
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
Option 1: Install from PyPI (Recommended)
Option 2: Install from Source
Running the 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
First, set your authentication token using the
set_auth_token
toolThe token will be included in all subsequent API requests as a Bearer token
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
Set Authentication:
{ "tool": "set_auth_token", "arguments": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } }Natural Language Query:
{ "tool": "natural_query", "arguments": { "query": "Show me all leads created in the last 30 days with phone numbers", "response_format": "both" } }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:
Add new tools: Implement additional tools in the
handle_list_tools()
andhandle_call_tool()
functionsModify API client: Extend the
AmbivoAPIClient
class to support additional endpointsUpdate configuration: Modify default settings in the configuration section
Troubleshooting
Common Issues:
"Authentication required" error: Ensure you've called
set_auth_token
firstHTTP 401/403 errors: Verify your JWT token is valid and not expired
Connection timeout: Check network connectivity and API endpoint availability
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.
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.
Related MCP Servers
- AsecurityFlicenseAqualityProvides 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 -31
- -securityFlicense-qualityA 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 -2
- AsecurityFlicenseAqualityA 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 -43
- AsecurityFlicenseAqualityA 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 -472