Set Up Insider One MCP

This guide explains how to set up Insider One MCP and connect it to an MCP-compatible AI client. By completing the steps below, you can securely enable read-only access to Insider One analytics data through the Model Context Protocol.

Prerequisites

Before setting up Insider One MCP, ensure you have:

An MCP-compatible client is installed.
Node.js is installed on your machine.
Authorization method (choose one):
- Insider One API Key (analytics access): Navigate to InOne > Settings > Integration Settings > API Keys to use an e existing Analytics API key or create a new key. For more information, refer to API Authentication Tokens.
  Only users with Administrator permission can generate tokens. If your account is not allowed to complete this operation, you can consult the Insider One team.
  We recommend not to reuse an existing API key or credentials. Create a dedicated key set specifically for your MCP client, to reduce risk if an agent attempts unintended actions.
- OAuth 2.0 Credentials: Navigate to InOne > Settings > Integration Settings > OAuth2.0 Credentials to use an existing credential or create a new one. For more information, refer to OAuth 2.0 Credentials.
Your Insider One Partner ID: Navigate to InOne > Settings > Account Settings. The number displayed under the panel name is your Partner ID.

MCP-Compatible Clients
Insider One MCP works with any client that supports the Model Context Protocol, including:
Claude Desktop
Cursor
Other MCP-compatible tools
The setup logic is the same across clients. Differences are noted where relevant.

MCP Server Configuration

To connect your AI client to Insider One MCP, you need to register Insider One as a remote MCP server.

Set up without OAuth 2.0

In this configuration, the MCP server itself does not implement authentication. All authorization and access control are enforced by Insider One APIs using header-based credentials.

When to use this option

You want full access to Insider One MCP–supported GET functions
You are querying multiple channels (Email, SMS, Web Push, App Push)
You prefer API key–based authentication
You want parity with existing Insider One API usage

To connect an MCP-compatible client to Insider One MCP, you need to edit the client’s local configuration file and register Insider One as a remote MCP server.

The exact file name and location may vary by client, but the overall structure and required fields are the same.

Required fields

mcpServers: Defines all MCP servers available to the client.
mcp-name: A custom name for the Insider One MCP server. You can rename it as suitable.
command: Uses npx to run the MCP remote connector.
mcp-remote: Connects the client to a remote MCP endpoint.
<INSIDER_MCP_ENDPOINT>: The Insider One MCP server endpoint provided by Insider One. (http://mcp.insiderone.com/mcp)
headers: Used for authentication and scoping:
- Channel-specific API keys
- Partner ID for analytics context

Your MCP client configuration contains sensitive secrets (API keys). Treat the configuration file as a secret:
Do not commit it to source control (Git)
Do not share screenshots that include keys
Restrict file access permissions on your machine
Rotate keys immediately if you suspect exposure
Use dedicated, least-privilege keys for MCP only

To configure the MCP Server,

Locate the client’s MCP configuration file.
Add a new MCP server entry for Insider One.

Example MCP Server Configuration (without OAuth 2.0)

{
        "mcpServers": {
        "insiderone-mcp": {
        "command": "npx",
        "args": [
        "-y",
        "mcp-remote",
        "<http://mcp.insiderone.com/mcp>",
        "--allow-http",
        "--debug",
        "--header",
        "X-Email-API-Key:<your-email-api-key>",
        "--header",
        "X-SMS-API-Key:<your-sms-api-key>",
        "--header",
        "X-App-Push-API-Key:<your-app-push-api-key>",
        "--header",
        "X-Web-Push-API-Key:<your-web-push-api-key>",
        "--header",
        "X-Partner-Id:<your-partner-id>"
        ]
        }
        }

Replace <your-api-key> with the actual key values from the API Keys page in Settings.
Save the configuration file.
Restart the client.
After the restart, you should locate the Insider One MCP on your client tools.

Rate limits apply based on existing Insider One API policies.

Set up with OAuth 2.0

This configuration uses OAuth 2.0–style bearer token authentication instead of channel-specific API keys.

The MCP server forwards the authentication token to Insider One APIs via an Authentication: Bearer header.

When to use this option

You prefer token-based authentication
Your organization requires OAuth-style credentials

When using OAuth 2.0 authentication, only Email-related MCP tools are currently available.
Other channel tools (SMS, Web Push, App Push) are not supported in this configuration yet.

Required fields

mcpServers: Defines all MCP servers available to the client.
mcp-name: A custom name for the Insider One MCP server. You can rename this value as suitable for your setup (for example, insiderone-mcp).
command: Uses npx to run the MCP remote connector.
mcp-remote: Connects the client to a remote MCP endpoint.
<INSIDER_MCP_ENDPOINT>: The Insider One MCP server endpoint provided by Insider One: (http://mcp.insiderone.com/mcp)
headers: Used for authentication. For an OAuth 2.0–based configuration, the following header is required:
- Authentication: Bearer <your-authentication-token>
This token is used to authorize requests against Insider One APIs.

Do not hardcode real authentication tokens in shared files or repositories.
Treat the configuration file as sensitive.
Rotate tokens if they are exposed.

To configure the MCP Server for OAuth 2.0 Authentication,

Locate the Claude Desktop configuration file on your machine.
Add the Insider One MCP server configuration using OAuth 2.0 authentication.

Example MCP Server Configuration (with OAuth 2.0)

{
        "mcpServers": {
        "insiderone-mcp": {
        "command": "npx",
        "args": [
        "-y",
        "mcp-remote",
        "<http://mcp.insiderone.com/mcp>",
        "--allow-http",
        "--debug",
        "--header",
        "Authentication: Bearer <your-authentication-token>"
        ]
        }
        }
        }

Replace your authentication token: Bearer <your-authentication-token> header as shown in the example. After updating the file, save your changes.
Restart the client.
Confirm that Insider One MCP appears in the available tools.

Rate limits apply based on existing Insider One API policies.

Setup Troubleshooting

This section covers common setup, configuration, and client-side issues you may encounter when using Insider One MCP, along with recommended resolution steps.

Insider One MCP does not appear as an available tool

Possible causes

The MCP configuration file was edited incorrectly.
The client was not restarted after configuration.
The MCP server definition contains a syntax error.

How to resolve

Double-check that the configuration file contains valid JSON.
Ensure the mcpServers object is correctly defined.
Restart the MCP-compatible client completely.
Confirm that the Insider One MCP server name is not duplicated.

The permission prompt does not appear

Possible causes

The client did not detect a valid MCP server.
The question does not require Insider One data.
The MCP server failed to initialize.

How to resolve

Ask a clear analytics question, define the channel, and time.
Example: “Revenue by channel last week”.
Verify that Insider One MCP is listed as an available tool.
Check that the MCP endpoint and headers are correctly defined.

Authentication or Authorization Errors

Possible causes

Missing or incorrect API keys.
Incorrect Partner ID.
The API key does not have analytics access.

How to resolve

Verify all required headers are included.
Confirm API keys belong to the correct Insider One account and are valid.
Ensure the Partner ID matches your Insider One environment.
Regenerate API keys if necessary.

Requests are rejected after approval

Possible causes

The request exceeds the allowed scope.
The requested data is not available for the account.
Rate limits are applied.

How to resolve

Ensure the request is analytics-only and read-only.
Try a smaller time range.
Check existing Insider One permissions for the account.

Client Shows Connection or Network Errors

Possible causes

The MCP endpoint is unreachable.
Network restrictions or firewall rules.
Node.js is not properly installed.

How to resolve

Verify the MCP endpoint URL.
Ensure Node.js is installed and accessible via npx.
Check network and firewall settings.
Retry after restarting the client.

Cursor-Specific Issues

Insider One MCP is not selectable in the Cursor

Ensure the MCP server is added under external tools
Restart the Cursor after saving the configuration

Requests do not execute

Confirm that you approved the permission prompt
Check that the MCP server is selected for the request

Unexpected or Incomplete Results

Possible causes

Ambiguous or incomplete questions
Missing time ranges
Unsupported metrics

How to resolve

Be explicit about time ranges and metrics
Use Insider One terminology where possible, and define channel type
Ask one analytical question at a time

Debugging Tips

Enable debug mode in the MCP server configuration
Review logs provided by the MCP client
Start with simple queries before complex analysis

When to contact the Insider One team?

Contact Insider One team if:

The MCP endpoint is accessible but consistently fails.
Authentication succeeds, but no data is returned.
Errors persist after following the troubleshooting steps.
Include the following when contacting support:
- Client type (e.g., Cursor, Claude Desktop)
- Error messages or logs
- Time of the request
- MCP server configuration (with API keys removed)

Disclaimer: Model Context Protocol (MCP) is a newly introduced open protocol and may be susceptible to security issues or vulnerabilities. Follow your organization’s security policies and review configurations carefully.