MCP Server: Getting Started · Developers

Connect your favourite AI assistant to your store’s data in minutes. This guide shows you how to set up the AIVA MCP Server with Claude Desktop, Cursor, Windsurf, and other AI tools.

What is the AIVA MCP Server?

The AIVA MCP Server lets AI assistants like Claude, Cursor, and Gemini access your store’s real data - customers, subscriptions, orders, affiliates, and more. Once connected, you can have natural conversations about your business:

“Show me my at-risk customers who haven’t ordered in 90 days”
“What’s my subscription churn rate this month?”
“Create a $500 prize draw for Christmas”
“Analyse my customer health and give me actionable recommendations”

The AI will query your actual data and provide strategic insights with expected ROI.

Step 1: Get Your API Credentials

You need two things to connect:

1. API Key - Your secret password to access the API
2. Merchant ID - Your unique store identifier (a GUID)

Where to Get Them

1. Click Settings in the top right
2. Go to API Keys
3. Click Generate New Key
4. Give it a name (e.g., “Claude Desktop”)
5. Copy your API Key and Merchant ID

Important: The API key is only shown once when created. Store it securely!

Step 2: Choose Your AI Tool

Tool	Best For
Claude Desktop	General conversations, analysis, reports
Cursor	AI-assisted coding with your data
Windsurf	AI development workflows
Claude Code (CLI)	Terminal-based AI workflows

Step 3: Configure Claude Desktop

This is the most popular option. Here’s how to set it up:

Find the Config File

Mac:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Add the Configuration

Open the file in a text editor (create it if it doesn’t exist) and paste:

{
  "mcpServers": {
    "aiva": {
      "command": "npx",
      "args": ["-y", "@getaiva/mcp"],
      "env": {
        "AIVA_API_KEY": "YOUR_API_KEY_HERE",
        "AIVA_MERCHANT_ID": "YOUR_MERCHANT_ID_HERE",
        "AIVA_API_BASE_URL": "https://api.getaiva.ai"
      }
    }
  }
}

Replace the placeholders with your actual credentials.

Restart Claude Desktop

Important: You must completely quit and restart Claude Desktop for the changes to take effect.

Step 4: Configure Cursor

Create a file called .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "aiva": {
      "command": "npx",
      "args": ["-y", "@getaiva/mcp"],
      "env": {
        "AIVA_API_KEY": "YOUR_API_KEY_HERE",
        "AIVA_MERCHANT_ID": "YOUR_MERCHANT_ID_HERE",
        "AIVA_API_BASE_URL": "https://api.getaiva.ai"
      }
    }
  }
}

Restart Cursor after adding the configuration.

Step 5: Test Your Connection

After restarting your AI tool, try these commands:

Basic Test

> “What AIVA tools do you have access to?”

The AI should list tools like analyze_customer_health, search_customers, get_orders, etc.

Real Data Test

> “Show me my top 10 customers by total spend”

The AI will query your actual store data and return results.

Marketing Intelligence Test

> “Analyse my customer health and give me actionable recommendations”

This uses AI-powered analysis to give you strategic insights with expected ROI.

What Can You Do With AIVA MCP?

Ask About Your Data

“How many active subscriptions do I have?”
“Who are my Champion customers?”
“What’s my average order value?”
“Show me customers who haven’t ordered in 60 days”

Get AI-Powered Insights

“Analyse my customer health”
“Give me marketing recommendations to reduce churn”
“What quick wins can I execute this week?”
“What’s my predicted revenue for next month?”

Take Actions

“Create a $500 prize draw for New Year”
“Search for at-risk customers”
“Send a win-back message to customer X”
“Sync my latest subscription data”

Available Tools

The AIVA MCP Server provides these tools:

Tool	Description
`analyze_customer_health`	AI-powered customer health analysis with RFM segmentation
`get_marketing_intelligence`	Objective-based marketing insights and campaign recommendations
`get_strategy_recommendations`	Business strategy recommendations with ROI projections
`get_customer`	Get detailed customer information
`get_subscription`	Get subscription details
`search_customers`	Search customers by RFM segment
`get_orders`	Get orders in a date range
`create_prize_draw`	Create blockchain-powered prize draws
`sync_subscriptions`	Trigger manual subscription sync
`send_aiva_message`	Send AI-powered messages to customers

Troubleshooting

“MCP server not found”

Ensure Node.js is installed: Run node --version in terminal
Try running npx -y @getaiva/mcp manually to test

“Unauthorised” or “401 Error”

Double-check your API key is correct
Ensure your Merchant ID matches your key
Check there are no extra spaces in your config

“Claude Desktop doesn’t show AIVA”

1. Quit Claude completely (Cmd+Q on Mac)
2. Verify your JSON syntax is valid (use jsonlint.com)
3. Restart Claude Desktop

Still Stuck?

Security Best Practices

1. Never share your API key - treat it like a password
2. Don’t commit keys to Git - use environment variables
3. Rotate keys regularly - every 90 days recommended
4. Revoke old keys - if a key might be compromised

Next Steps

Once connected, explore the Marketing Prompt Library for proven campaign templates:

Win-back campaigns for at-risk customers
Upsell campaigns for Champions
Prize draw optimisation strategies
Automated lifecycle journeys

Check out the full MCP Server Documentation for advanced usage and all available tools. - Need help? Contact support@aiva.nz

Built by Growth Spurt Ltd • aiva.nz • Made in New Zealand

AIVA MCP Server: Getting Started Guide for AI-Powered Marketing Intelligence