mcp-interaction-studio

MCP (Model Context Protocol) server for Salesforce Interaction Studio / Marketing Cloud Personalization admin APIs.

Connect Cursor, Claude Desktop, or any MCP client to your Interaction Studio instance to list datasets, campaigns, segments, templates, recipes, and campaign performance stats through natural language.

How it works

Interaction Studio’s admin UI uses undocumented internal APIs under /internal/.... This server authenticates the same way your browser does: with a session cookie (JSESSIONID) from an active UI login.

Auth method	Used for
JSESSIONID session cookie	All tools in this package (/internal/*)
API token (Basic auth)	Public /api/* endpoints only — not used by this MCP yet

---

Prerequisites

• Node.js 18+
• Access to Interaction Studio admin UI (Gears) for your org
• An MCP host (e.g. Cursor, Claude Desktop)

---

Step 1 — Find your IS_BASE_URL

Log into Interaction Studio. The URL in your browser looks like:

https://{accountName}.{instance}.evergage.com/ui/...

Your base URL is everything before /ui:

https://{accountName}.{instance}.evergage.com

Example: if you see
https://demo.us-1.evergage.com/ui/
then:

IS_BASE_URL=https://demo.us-1.evergage.com

Do not include a trailing slash.

You can also find this from any Network request to *.evergage.com — use the scheme + host only.

---

Step 2 — Get your IS_SESSION_ID (JSESSIONID)

The session ID is a cookie set when you log into the admin UI. It expires when you log out or after idle timeout.

Chrome / Edge

1. Log into Interaction Studio at {IS_BASE_URL}/ui/
2. Open DevTools → Network tab
3. Reload the page (or click any screen that loads data)
4. Click any request to your *.evergage.com host
5. Under Request Headers, find the Cookie header
6. Copy the value after JSESSIONID= up to the next ;

Example cookie header:

Cookie: JSESSIONID=274fb681-ebf1-4dbb-8e4d-5b03bb8a1752; AWSALBTG=...

Copy only:

274fb681-ebf1-4dbb-8e4d-5b03bb8a1752

Firefox

1. Log into the UI
2. DevTools → Network → select a request → Headers → Cookie
3. Copy the JSESSIONID value the same way

Verify with curl

curl -k "https://YOUR_ACCOUNT.us-4.evergage.com/internal/datasetSummaries/" \
  -H "Cookie: JSESSIONID=YOUR_SESSION_ID_HERE" \
  -H "X-Requested-With: XMLHttpRequest"

If you get a JSON array of datasets, the session is valid. If you get 401 or "Bad Credentials", log in again and copy a fresh JSESSIONID.

Security: Treat JSESSIONID like a password. Do not commit it to git or share it in chat. Refresh it when it expires.

---

Step 3 — Install the MCP server

Option A — Run with npx (recommended)

No global install needed:

npx mcp-interaction-studio

Option B — Global install

npm install -g mcp-interaction-studio
mcp-interaction-studio

Option C — Clone and run locally

git clone <your-repo-url>
cd mcp-interaction-studio
npm install
npm start

---

Step 4 — Configure your MCP host

Cursor

Open Cursor Settings → MCP (or edit ~/.cursor/mcp.json):

{
  "mcpServers": {
    "interaction-studio": {
      "command": "npx",
      "args": ["-y", "mcp-interaction-studio"],
      "env": {
        "IS_BASE_URL": "https://YOUR_ACCOUNT.us-4.evergage.com",
        "IS_SESSION_ID": "paste-your-JSESSIONID-here",
        "IS_DEFAULT_DATASET": "my-dataset",
        "IS_TLS_INSECURE": "true"
      }
    }
  }
}

If installed globally:

{
  "mcpServers": {
    "interaction-studio": {
      "command": "mcp-interaction-studio",
      "env": {
        "IS_BASE_URL": "https://YOUR_ACCOUNT.us-4.evergage.com",
        "IS_SESSION_ID": "paste-your-JSESSIONID-here",
        "IS_DEFAULT_DATASET": "my-dataset",
        "IS_TLS_INSECURE": "true"
      }
    }
  }
}

Restart MCP in Cursor Settings after changing config.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "interaction-studio": {
      "command": "npx",
      "args": ["-y", "mcp-interaction-studio"],
      "env": {
        "IS_BASE_URL": "https://YOUR_ACCOUNT.us-4.evergage.com",
        "IS_SESSION_ID": "paste-your-JSESSIONID-here",
        "IS_DEFAULT_DATASET": "my-dataset",
        "IS_TLS_INSECURE": "true"
      }
    }
  }
}

---

Environment variables

Variable	Required	Description
IS_BASE_URL	Yes	Interaction Studio host, e.g. https://demo.us-1.evergage.com (no trailing slash)
IS_SESSION_ID	Yes	JSESSIONID cookie value from an active UI session
IS_DEFAULT_DATASET	No	Default dataset name when a tool omits the dataset parameter
IS_TLS_INSECURE	No	Set to true if curl/Node fails with SSL certificate errors (common behind Zscaler/corporate proxies). Equivalent to curl -k.
IS_WRITES_ENABLED	No	Set to true to enable write tools (set_campaign_state, set_segment_enabled). Off by default.
NODE_EXTRA_CA_CERTS	No	Path to your corporate root CA .pem file — preferred over IS_TLS_INSECURE for production use

Copy .env.example to .env when running locally:

cp .env.example .env
# edit .env, then:
npm start

---

Corporate SSL (Zscaler / proxy)

If you see:

SSL certificate problem: unable to get local issuer certificate

Quick fix (dev): set IS_TLS_INSECURE=true

Proper fix: export your org’s Zscaler/corporate root CA and set:

export NODE_EXTRA_CA_CERTS=/path/to/corporate-root.pem

Then remove IS_TLS_INSECURE.

---

Session expiration

When JSESSIONID expires, tools return:

Session expired or invalid (401). Log into Interaction Studio, copy a fresh JSESSIONID...

Fix: log into the UI again → copy new JSESSIONID → update IS_SESSION_ID in MCP config → restart MCP.

There is no API token alternative for /internal/* admin routes today.

---

Available tools

Tool	Description
check_session	Validate JSESSIONID and list datasets (use when you get 401 errors)
list_datasets	All datasets in the account
get_dataset	Dataset metadata and content zones
list_campaigns	Campaigns in a dataset
get_campaign	Campaign details: state, targeting, experiences
get_campaign_stats	Impressions, clicks, goals, orders, revenue
list_segments	Segments in a dataset
get_segment	Segment details and targeting rules
list_all_segments	Segments across all datasets (or filter one)
list_templates	Item/message templates
list_recipes	Recommendation recipes
get_campaign_context	Campaign experiences, messages, and runtime context
list_surveys	Surveys in a dataset
list_content_zone_logs	Content zone activity logs
get_segment_details	Extended segment info including membership counts
audit_dataset	Dataset audit report (markdown or JSON); optional file output
audit_mcp_dataset	Executive-ready orchestrated audit: narrative, health score, governance, consumption, settings; markdown + DOCX
compare_datasets	Side-by-side comparison of two datasets
get_recipe_usage	Map recipes to campaigns (resolves inUse vs actual linkage)
list_segment_stats	Batch segment membership counts and calc status
set_campaign_state	Publish or disable a campaign (write; gated)
set_segment_enabled	Enable or disable a segment (write; gated)

Set IS_DEFAULT_DATASET to skip passing dataset on every call.

Write tools (v1.0)

Write operations are disabled by default. To enable:

1. Set IS_WRITES_ENABLED=true in MCP config
2. Call with dry_run=false and confirm=true

Always preview first with dry_run=true (default):

• "Dry run: publish campaign Q07yv in eharper"
• "Disable segment uvoSx in eharper — dry run only"

Execute only when intentional:

• "Set campaign qDArI to Disabled in eharper with dry_run false and confirm true"

Endpoint	Method	Operation
/internal/dataset/{ds}/campaign/{id}/	PUT	Publish / disable campaign (full object, state field)
/internal/dataset/{ds}/segments/disableOrEnable/	POST	Enable / disable segment (segmentIds query param)

Executive audit (audit_mcp_dataset)

Board-ready assessment with health rating, strengths/gaps narrative, domain assessments, and prioritized recommendations. Writes markdown and DOCX when output_path is set.

Parameter	Description
report_style	executive (default) or technical
output_format	markdown, json, or docx
export_docx	When saving .md, also write .docx (default: true)
sections	governance, consumption, settings (default: all)

Example:

• "Full MCP audit of eharper — save to audit/eharper-audit.md"
• "audit_mcp_dataset dataset=eharper report_style=executive output_path=audit/report.md"

Example prompts

• "Check my Interaction Studio session"
• "List my Interaction Studio datasets"
• "Audit the eharper dataset and save to audit/eharper-audit.md"
• "Full executive MCP audit of eharper with markdown and docx"
• "Compare mathes and eharper datasets"
• "Which campaigns use recipe 4RhQk in eharper?"
• "List segment stats for all segments in eharper"
• "Get stats for campaign ABC123 in my-dataset"
• "List all segments across every dataset"
• "Get segment XYZ789 from my-dataset"

Campaign stats time ranges

For get_campaign_stats and list_campaigns, use time_range:

• pastDay, pastWeek (default), pastMonth, pastQuarter, Today
• Custom: YYYY-MM-DD..YYYY-MM-DD (max range limits apply per IS API)

CLI audit script

After building locally, run a full audit from the command line:

npm run build
node dist/scripts/audit-dataset.js eharper --output ../audit/eharper-audit.md

Or use the npm script:

npm run audit -- eharper --output ../audit/eharper-audit.md

---

Troubleshooting

Problem	Solution
401 / Bad Credentials	Refresh IS_SESSION_ID from DevTools
SSL certificate error	IS_TLS_INSECURE=true or NODE_EXTRA_CA_CERTS
Tool not found in Cursor	Restart MCP after upgrading the package
Missing IS_BASE_URL	Set env in MCP config env block
Zero campaign stats	Campaign may have no traffic in the selected time window; try a wider custom range
Query param [timeRange] is required	Use a valid time_range value (see above)

---

License

MIT