# MCP (Model Context Protocol) for UTMGrabber Reports

## Overview

The MCP feature allows you to connect your WordPress site to AI assistants like **Claude Desktop**, **Cursor**, and **Codex** using the [Model Context Protocol](https://modelcontextprotocol.io/). Once connected, you can query your UTMGrabber reports using natural language directly from any MCP-compatible client.

> **Disclaimer:** AI-generated results may be inaccurate or incomplete. Always review before acting on them.

For example, you can ask questions like:

- "What are the top UTM sources in my submissions?"
- "How many leads came from organic traffic?"
- "Which campaigns drove the most form submissions?"

## Requirements

- HandL UTM Grabber V3 (premium) with an active license key
- Starter plus or premium utmgrabber subscription

## Setup

### Step 1: Navigate to the MCP Tab

1. Go to **WordPress Admin > UTM > MCP**

You will see the MCP setup screen:

[![mcp-setup-screen.png](https://docs.utmgrabber.com/uploads/images/gallery/2026-03/scaled-1680-/mcp-setup-screen.png)](https://docs.utmgrabber.com/uploads/images/gallery/2026-03/mcp-setup-screen.png)

### Step 2: Connect to MCP

1. Click the **Connect to MCP** button
2. The plugin will automatically register your site using your license key
3. Once connected, you will see your unique MCP URL

[![mcp-connected.png](https://docs.utmgrabber.com/uploads/images/gallery/2026-03/scaled-1680-/mcp-connected.png)](https://docs.utmgrabber.com/uploads/images/gallery/2026-03/mcp-connected.png)

### Step 3: Copy Your MCP URL

1. Your unique MCP URL will be displayed on screen (partially truncated for security)
2. Click the **copy icon** next to the URL to copy the full URL to your clipboard
3. You will see a confirmation toast when the URL is copied

> **Important:** This URL contains your secret access code. Treat it like a password. Do not share it publicly or commit it to version control.

### Step 4: Add to Your MCP Client

Use the copied URL in your preferred MCP-compatible client:

#### Claude Desktop

Add to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "utmgrabber": {
      "url": "YOUR_MCP_URL_HERE"
    }
  }
}
```

#### Cursor

Add to your Cursor MCP settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "utmgrabber": {
      "url": "YOUR_MCP_URL_HERE"
    }
  }
}
```

## Features

### Query UTM Reports with Natural Language

Once connected, you can ask your AI assistant questions about your UTMGrabber data. The MCP server exposes the following capabilities:

- **Available form plugins** - See which form plugins are detected on your site (e.g. Gravity Forms, WPForms, Fluent Forms)
- **List forms** - Browse all forms from a specific plugin
- **Get entries** - Fetch form submission entries with UTM data, filtered by date range, form, and plugin

### Secure Communication

All communication between the MCP server and your WordPress site is secured using HMAC-SHA256 signed requests. Your site secret is never transmitted after the initial setup. Only the MCP server and your WordPress plugin know the shared secret.

## Managing Your Connection

### Reconnecting

If you need to regenerate your MCP credentials (e.g. you suspect the URL was compromised):

1. Click the **Reconnect** button
2. A confirmation dialog will appear warning that this will invalidate your current URL

[![mcp-reconnect-confirm.png](https://docs.utmgrabber.com/uploads/images/gallery/2026-03/scaled-1680-/mcp-reconnect-confirm.png)](https://docs.utmgrabber.com/uploads/images/gallery/2026-03/mcp-reconnect-confirm.png)

3. Click **Reconnect** to confirm
4. A new MCP URL will be generated
5. Update all your MCP clients with the new URL

### Disconnecting

To completely revoke MCP access for your site:

1. Click the **Disconnect** button (shown in red)
2. A confirmation dialog will appear

[![mcp-disconnect-confirm.png](https://docs.utmgrabber.com/uploads/images/gallery/2026-03/scaled-1680-/mcp-disconnect-confirm.png)](https://docs.utmgrabber.com/uploads/images/gallery/2026-03/mcp-disconnect-confirm.png)

3. Click **Disconnect** to confirm
4. Your MCP credentials will be revoked immediately
5. Any MCP clients using the old URL will stop working
6. You can reconnect later, but a new URL will be generated

## Troubleshooting

### "Failed to connect to MCP server"

- Verify your license key is active and valid
- Check that your site URL is accessible from the internet
- Ensure your WordPress site is not behind a firewall that blocks outgoing requests

### MCP client can't connect after setup

- Make sure you copied the **full** MCP URL (click the copy button, don't copy the truncated text)
- Verify the URL is correctly pasted in your MCP client configuration
- Restart your MCP client after adding the configuration

### Data is not showing in AI responses

- Ensure you have form plugins installed and active (e.g. Gravity Forms, WPForms)
- Verify that form submissions exist in the date range you're querying
- Check that the form plugin is supported by UTMGrabber

### Connection was working but stopped

- Your MCP credentials may have been invalidated. Try clicking **Reconnect** to generate new credentials
- Check that your WordPress site is still accessible and the plugin is active

## Best Practices

- **Keep your MCP URL secret** - treat it like a password
- **Do not share the URL publicly** or commit it to version control
- **Reconnect if compromised** - if you suspect your URL has been exposed, click Reconnect immediately to invalidate the old credentials