# nova-mcp-server (`sambehnke/nova-integrations-mcp-server`) Actor

Transform AI agents with tools that enhance real-world functionality. Dynamic MCP server loads YOUR chosen Apify actors from key-value stores. Perfect for Retell.ai, Claude & any agent needing business automation & workflow integration.

- **URL**: https://apify.com/sambehnke/nova-integrations-mcp-server.md
- **Developed by:** [Nova Integrations](https://apify.com/sambehnke) (community)
- **Categories:** AI, Agents, MCP servers
- **Stats:** 4 total users, 2 monthly users, 0.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $50.00 / 1,000 get\_data

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Nova MCP Server

<p align="center">
  <img alt="Nova Integrations MCP Server" src="docs/nova_integrations_banner.png" width="600">
</p>

<p align="center">
  <strong>Transform your Retell.ai voice agents with 5,000+ Apify tools</strong>
</p>

<p align="center">
  <a href="https://apify.com/store"><img src="https://img.shields.io/badge/Apify-Store-brightgreen" alt="Apify Store"></a>
  <a href="https://docs.retellai.com/"><img src="https://img.shields.io/badge/Retell.ai-Compatible-blue" alt="Retell.ai Compatible"></a>
  <a href="https://modelcontextprotocol.org/"><img src="https://img.shields.io/badge/MCP-Enabled-orange" alt="MCP Enabled"></a>
</p>

The **Nova Integrations MCP Server** is a production-ready Model Context Protocol server that seamlessly connects your Retell.ai voice agents to thousands of Apify Actors. Unlike static MCP servers, Nova Integrations dynamically loads your personalized actor configurations from your own Apify key-value stores, ensuring you only see the tools you actually need.

### 🎯 Perfect for Retell.ai Voice Agents

Transform your voice agents with powerful capabilities:

- **Web Scraping**: Extract data from any website during voice calls
- **API Integrations**: Connect to Google Calendar, CRMs, and business tools
- **Data Processing**: Analyze and transform data in real-time
- **Automation**: Trigger complex workflows from voice interactions

### 🚀 Quick Start for Retell.ai

#### Step 1: Get Your MCP Server URL

Your Nova Integrations MCP Server will be available at:

```
https://YOUR_USERNAME--nova-integrations-mcp-server.apify.actor
```

Replace `YOUR_USERNAME` with your Apify username.

#### Step 2: Configure Your Actors

1. Go to [Apify Console Storage](https://console.apify.com/storage)
2. Create a key-value store named: `my-mcp-configs`
3. Add a record with key: `my-actors`
4. Set the value as a JSON array of actor names:

```json
[
  "sambehnke/google-calendar-create-event",
  "apify/web-scraper",
  "apify/google-search-scraper"
]
```

**Actor Format Requirements:**

- Must use `username/actor-name` format
- Actors must exist in the [Apify Store](https://apify.com/store)
- Use proper JSON array formatting

#### Step 3: Integrate with Retell.ai

1. **Open your Retell.ai agent settings**

2. **Navigate to MCP/Functions section**

3. **Click "+ Add MCP"**

4. **Configure the connection:**

   **Option A: Token in URL (Simplest)**

   ```
   MCP Server URL: https://YOUR_USERNAME--nova-integrations-mcp-server.apify.actor?token=YOUR_APIFY_TOKEN
   ```

   **Option B: Using Headers (Recommended)**

   ```
   MCP Server URL: https://YOUR_USERNAME--nova-integrations-mcp-server.apify.actor
   Custom Headers: Authorization: Bearer YOUR_APIFY_TOKEN
   ```

5. **Get your Apify API token** from [Apify Console → Settings → Integrations](https://console.apify.com/settings/integrations)

#### Step 4: Test Your Integration

Your configured actors will now be available as tools in your Retell.ai voice agent. Test by asking your agent to perform tasks like:

- "Create a calendar event for tomorrow at 2 PM"
- "Search Google for the latest AI news"
- "Extract contact information from this website"

### 🛠️ Managing Your Actor Configuration

#### Adding New Actors

1. Browse the [Apify Store](https://apify.com/store) to find actors
2. Note the actor name in `username/actor-name` format
3. Edit your `my-actors` record in your `my-mcp-configs` key-value store
4. Add the new actor to your JSON array:

```json
[
  "sambehnke/google-calendar-create-event",
  "apify/web-scraper",
  "apify/instagram-scraper",
  "new-username/new-actor-name"
]
```

5. Reconnect your Retell.ai agent to load the new configuration

#### Popular Actors for Voice Agents

Here are some popular actors that work great with voice agents:

**Calendar & Scheduling:**

- `sambehnke/google-calendar-create-event` - Create Google Calendar events
- `apify/calendar-scheduler` - Advanced scheduling automation

**Data Extraction:**

- `apify/web-scraper` - Extract data from any website
- `apify/google-search-scraper` - Search Google and return results
- `apify/instagram-scraper` - Extract Instagram data
- `apify/linkedin-scraper` - LinkedIn profile and company data

**Business Automation:**

- `apify/email-sender` - Send automated emails
- `apify/pdf-generator` - Generate PDF documents
- `apify/google-maps-scraper` - Extract business listings

**Communication:**

- `apify/slack-sender` - Send Slack messages
- `apify/whatsapp-sender` - WhatsApp automation

### 🔧 Advanced Configuration

#### Custom Headers and Parameters

You can configure additional settings in Retell.ai:

**Custom Headers:**

```
Authorization: Bearer YOUR_APIFY_TOKEN
Content-Type: application/json
X-Custom-Header: your-value
```

**Query Parameters:**

```
token: YOUR_APIFY_TOKEN
custom_param: your_value
```

#### Error Handling

The server provides clear error messages for common issues:

- **Invalid JSON**: Check your `my-actors` record formatting
- **Actor not found**: Verify actor names exist in Apify Store
- **Authentication failed**: Check your Apify API token
- **Network issues**: Ensure your server is accessible

#### Validation

All actors are validated when you connect:

- ✅ Proper `username/actor-name` format
- ✅ Actor exists in Apify Store
- ✅ Actor is accessible with your token
- ❌ Clear error messages for any issues

### 🎙️ Retell.ai Agent Prompt Examples

Configure your Retell.ai agent prompts to effectively use your tools:

```
When the user wants to:
- Schedule something: Use the sambehnke/google-calendar-create-event tool
- Find information online: Use the apify/google-search-scraper tool
- Get website data: Use the apify/web-scraper tool
- Extract business info: Use the apify/google-maps-scraper tool

Always confirm details with the user before executing any tool.
```

### 🔒 Security & Authentication

- **OAuth Support**: Full OAuth integration with Apify
- **Token Authentication**: Secure API token-based access
- **User Isolation**: Each user's configuration is completely separate
- **Validation**: All actors verified before registration
- **No Data Mixing**: Your configuration stays in your own key-value stores

### 📊 Benefits Over Static MCP Servers

**Traditional MCP Servers:**

- ❌ Fixed tool sets
- ❌ One-size-fits-all approach
- ❌ Admin overhead for changes
- ❌ Cluttered tool lists

**Nova Integrations:**

- ✅ Personalized tool configurations
- ✅ Dynamic actor loading
- ✅ User-controlled via Apify Console
- ✅ Clean, focused tool lists
- ✅ No defaults or bloat

### 🆘 Troubleshooting

#### Common Issues

**"No tools available"**

- Check that your `my-mcp-configs` key-value store exists
- Verify the `my-actors` record contains valid JSON
- Ensure actor names are in correct format

**"Actor validation failed"**

- Verify actor exists in [Apify Store](https://apify.com/store)
- Check spelling and format: `username/actor-name`
- Ensure you have access to the actor

**"Authentication error"**

- Verify your Apify API token is correct
- Check token is included in URL or headers
- Ensure token has necessary permissions

#### Getting Help

1. Check the [Apify Documentation](https://docs.apify.com)
2. Verify your configuration in [Apify Console](https://console.apify.com/storage)
3. Test actors individually in Apify before adding to MCP
4. Contact support with specific error messages

### 🔄 Updates and Maintenance

#### Adding New Actors

Simply edit your `my-actors` record and reconnect your Retell.ai agent.

#### Removing Actors

Remove from your JSON array and reconnect.

#### Updating Actor Versions

Actors automatically use the latest version when called.

### 📚 Learn More

- [Model Context Protocol](https://modelcontextprotocol.org/)
- [Retell.ai MCP Documentation](https://docs.retellai.com/build/single-multi-prompt/mcp)
- [Apify Store](https://apify.com/store)
- [Apify API Documentation](https://docs.apify.com/api/v2)
- [Building Voice Agents with Retell.ai](https://docs.retellai.com/)

### 🤝 Contributing

This is an open-source project. Contributions welcome:

- Report issues with specific actor integrations
- Share successful Retell.ai + actor combinations
- Contribute documentation improvements
- Submit feature requests

### 📄 License

MIT License - see LICENSE file for details.

***

**Ready to supercharge your voice agents?** Deploy Nova Integrations MCP Server and start building more powerful, dynamic voice interactions with Retell.ai today!

# Actor input Schema

## `debugMode` (type: `boolean`):

Enable debug logging for troubleshooting and monitoring

## `serverPort` (type: `integer`):

Port for the HTTP server (only used in local mode)

## `enableMetrics` (type: `boolean`):

Enable performance and usage metrics collection

## `maxConnections` (type: `integer`):

Maximum number of concurrent MCP connections

## `sessionTimeout` (type: `integer`):

How long to keep inactive sessions alive

## Actor input object example

```json
{
  "debugMode": false,
  "serverPort": 3000,
  "enableMetrics": true,
  "maxConnections": 100,
  "sessionTimeout": 60
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("sambehnke/nova-integrations-mcp-server").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("sambehnke/nova-integrations-mcp-server").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call sambehnke/nova-integrations-mcp-server --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=sambehnke/nova-integrations-mcp-server",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/bDVXeawDcLO2PZcxB/builds/Z1Ltp6ZYQUXfmXaof/openapi.json