# 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:**
```json
{
"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:**
```json
{
"query": "Show me leads created this week with attribution_source google_ads",
"response_format": "both"
}
```
## Installation
### Option 1: Install from PyPI (Recommended)
```bash
pip install ambivo-mcp-server
# For remote server support (optional)
pip install "ambivo-mcp-server[remote]"
```
### Option 2: Install from Source
```bash
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)
```bash
# 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):**
```bash
python http_sse_server.py
```
2. **Configure Claude Desktop (on user's machine):**
```json
{
"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](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**:
```json
{
"tool": "set_auth_token",
"arguments": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}
```
2. **Natural Language Query**:
```json
{
"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**:
```json
{
"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.
Raw data
{
"_id": null,
"home_page": "https://github.com/ambivo-corp/ambivo-mcp-server",
"name": "ambivo-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "mcp, server, ambivo, api, natural, language, query, entity, data, crm",
"author": "Ambivo Development Team",
"author_email": "Ambivo Development Team <dev@ambivo.com>",
"download_url": "https://files.pythonhosted.org/packages/58/6d/e4a71022f4b8b630557666ef2021734943f7bdd803491639ad154473d41c/ambivo_mcp_server-1.0.4.tar.gz",
"platform": null,
"description": "# Ambivo MCP Server\n\nThis MCP (Model Context Protocol) server provides access to Ambivo API endpoints for natural language querying of entity data.\n\n## Features\n\n- **Natural Language Queries**: Execute natural language queries against entity data using the `/entity/natural_query` endpoint\n- **JWT Authentication**: Secure access using Bearer token authentication\n- **Rate Limiting**: Built-in rate limiting to prevent API abuse\n- **Token Caching**: Efficient token validation with caching\n- **Error Handling**: Comprehensive error handling with detailed error messages\n- **Retry Logic**: Automatic retry with exponential backoff for failed requests\n- **Remote Hosting Support**: Can be hosted in the cloud for multi-user access via HTTP/SSE transport\n\n## Tools\n\n### 1. `set_auth_token`\nSet the JWT Bearer token for authentication with the Ambivo API.\n\n**Parameters:**\n- `token` (string, required): JWT Bearer token\n\n**Usage:**\n```json\n{\n \"token\": \"your-jwt-token-here\"\n}\n```\n\n### 2. `natural_query`\nExecute natural language queries against Ambivo entity data.\n\n**Parameters:**\n- `query` (string, required): Natural language query describing what data you want\n- `response_format` (string, optional): Response format - \"table\", \"natural\", or \"both\" (default: \"both\")\n\n**Example queries:**\n- \"Show me leads created this week\"\n- \"Find contacts with gmail addresses\"\n- \"List opportunities worth more than $10,000\"\n- \"Show me leads with attribution_source google_ads from the last 7 days\"\n\n**Usage:**\n```json\n{\n \"query\": \"Show me leads created this week with attribution_source google_ads\",\n \"response_format\": \"both\"\n}\n```\n\n\n## Installation\n\n### Option 1: Install from PyPI (Recommended)\n```bash\npip install ambivo-mcp-server\n\n# For remote server support (optional)\npip install \"ambivo-mcp-server[remote]\"\n```\n\n### Option 2: Install from Source\n```bash\ngit clone https://github.com/ambivo-corp/ambivo-mcp-server.git\ncd ambivo-mcp-server\npip install -e .\n\n# For remote server support (optional)\npip install -e \".[remote]\"\n```\n\n## Running the Server\n\n### Local Mode (Default)\n```bash\n# If installed via pip\nambivo-mcp-server\n\n# Or using Python module\npython -m ambivo_mcp_server.server\n```\n\n### Remote Mode (Cloud Hosting)\nHost the server in the cloud for multiple users:\n\n1. **Start the HTTP/SSE server (on your cloud server):**\n```bash\npython http_sse_server.py\n```\n\n2. **Configure Claude Desktop (on user's machine):**\n```json\n{\n \"mcpServers\": {\n \"ambivo\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"http_sse_client_bridge\"],\n \"env\": {\n \"MCP_SERVER_URL\": \"https://your-server.com\",\n \"AMBIVO_AUTH_TOKEN\": \"user-jwt-token\"\n }\n }\n }\n}\n```\n\nSee [INSTALL_HTTP_SSE.md](INSTALL_HTTP_SSE.md) for detailed cloud deployment instructions.\n\n## Configuration\n\nThe server uses the following default configuration:\n- **Base URL**: `https://goferapi.ambivo.com`\n- **Timeout**: 30 seconds\n- **Content Type**: `application/json`\n\nYou can modify these settings in the `AmbivoAPIClient` class if needed.\n\n## Authentication\n\n1. First, set your authentication token using the `set_auth_token` tool\n2. The token will be included in all subsequent API requests as a Bearer token\n3. The token should be a valid JWT token from your Ambivo API authentication\n\n## Error Handling\n\nThe server provides comprehensive error handling:\n- **Authentication errors**: Clear messages when token is missing or invalid\n- **HTTP errors**: Detailed HTTP status codes and response messages\n- **Validation errors**: Parameter validation with helpful error messages\n- **Network errors**: Timeout and connection error handling\n\n## API Endpoints\n\nThis MCP server interfaces with these Ambivo API endpoints:\n\n### `/entity/natural_query`\n- **Method**: POST\n- **Purpose**: Process natural language queries for entity data retrieval\n- **Authentication**: Required (JWT Bearer token)\n- **Content-Type**: application/json\n\n### `/entity/data`\n- **Method**: POST \n- **Purpose**: Direct entity data access with structured parameters\n- **Authentication**: Required (JWT Bearer token)\n- **Content-Type**: application/json\n\n## Example Workflow\n\n1. **Set Authentication**:\n ```json\n {\n \"tool\": \"set_auth_token\",\n \"arguments\": {\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\"\n }\n }\n ```\n\n2. **Natural Language Query**:\n ```json\n {\n \"tool\": \"natural_query\", \n \"arguments\": {\n \"query\": \"Show me all leads created in the last 30 days with phone numbers\",\n \"response_format\": \"both\"\n }\n }\n ```\n\n3. **Direct Entity Query**:\n ```json\n {\n \"tool\": \"entity_data\",\n \"arguments\": {\n \"entity_type\": \"contact\",\n \"filters\": {\"email\": {\"$regex\": \"@gmail.com$\"}},\n \"limit\": 100,\n \"sort\": {\"created_date\": -1}\n }\n }\n ```\n\n## Development\n\nTo extend this MCP server:\n\n1. **Add new tools**: Implement additional tools in the `handle_list_tools()` and `handle_call_tool()` functions\n2. **Modify API client**: Extend the `AmbivoAPIClient` class to support additional endpoints\n3. **Update configuration**: Modify default settings in the configuration section\n\n## Troubleshooting\n\n**Common Issues:**\n\n1. **\"Authentication required\" error**: Ensure you've called `set_auth_token` first\n2. **HTTP 401/403 errors**: Verify your JWT token is valid and not expired\n3. **Connection timeout**: Check network connectivity and API endpoint availability\n4. **Invalid parameters**: Review the tool schemas for required and optional parameters\n\n**Logging:**\n\nThe server logs important events and errors. Check the console output for debugging information.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP Server for Ambivo API endpoints - Natural language queries and direct entity data access",
"version": "1.0.4",
"project_urls": {
"Bug Tracker": "https://github.com/ambivo-corp/ambivo-mcp-server/issues",
"Documentation": "https://github.com/ambivo-corp/ambivo-mcp-server#readme",
"Homepage": "https://github.com/ambivo-corp/ambivo-mcp-server",
"Source Code": "https://github.com/ambivo-corp/ambivo-mcp-server"
},
"split_keywords": [
"mcp",
" server",
" ambivo",
" api",
" natural",
" language",
" query",
" entity",
" data",
" crm"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a8c2a44658f0561fe4531407a3ee66d4c63bb03daca87d79bc7dec62a32ab283",
"md5": "18ff129cd62eea7cc50eb43ef41a0230",
"sha256": "2bcc7844bdf45b2e16f6e0525c9ef5ef1f08a86e065c854d1d3c3edd9acf8413"
},
"downloads": -1,
"filename": "ambivo_mcp_server-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "18ff129cd62eea7cc50eb43ef41a0230",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 14834,
"upload_time": "2025-07-30T19:14:29",
"upload_time_iso_8601": "2025-07-30T19:14:29.256102Z",
"url": "https://files.pythonhosted.org/packages/a8/c2/a44658f0561fe4531407a3ee66d4c63bb03daca87d79bc7dec62a32ab283/ambivo_mcp_server-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "586de4a71022f4b8b630557666ef2021734943f7bdd803491639ad154473d41c",
"md5": "08f2cd562fc52d1e4e7745e999283185",
"sha256": "0788dda150b5a50f5e6560200ceb893996470f052fc6825de55d2ce21400e005"
},
"downloads": -1,
"filename": "ambivo_mcp_server-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "08f2cd562fc52d1e4e7745e999283185",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 19788,
"upload_time": "2025-07-30T19:14:30",
"upload_time_iso_8601": "2025-07-30T19:14:30.159738Z",
"url": "https://files.pythonhosted.org/packages/58/6d/e4a71022f4b8b630557666ef2021734943f7bdd803491639ad154473d41c/ambivo_mcp_server-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 19:14:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ambivo-corp",
"github_project": "ambivo-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "mcp",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "httpx",
"specs": [
[
">=",
"0.25.0"
]
]
},
{
"name": "pytest-asyncio",
"specs": [
[
">=",
"0.21.0"
]
]
},
{
"name": "setuptools",
"specs": []
},
{
"name": "pytest",
"specs": [
[
">=",
"8.4.1"
]
]
}
],
"lcname": "ambivo-mcp-server"
}
JSON
