@ingeniux/ctnp-mcp

CTnP MCP Server

Model Context Protocol server that exposes CTnP API endpoints as structured tools for AI agents (VS Code Copilot, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client).

Prerequisites

• Node.js 18+ (required for native fetch and AbortSignal.timeout)
• The CTnP API running (locally or remote)
• Your CMS license checksum (see Getting your token below)

Install & Build

npm install
npm run build

The compiled server is output to dist/index.js. Re-run npm run build after any code changes.

Getting Your Bearer Token

The CTNP_BEARER_TOKEN — the value the CMS sends in Authorization: Bearer ` when it calls the CTnP API. You can find it in:

• Network traffic when your CMS calls the CTnP API (look for the Authorization header)
• Your CTnP account administrator

Configuration

All config is passed as environment variables when launching the MCP server:

Variable	Required	Description
CTNP_API_URL	Yes	CTnP API base URL e.g. http://localhost:3030
CTNP_CMS_URL	Yes	Your CMS installation URL e.g. https://mycms.example.com
CTNP_BEARER_TOKEN	Yes	CMS license checksum (Bearer token + HMAC signing secret)
CTNP_CMS_USER_ID	Yes	CMS user ID (attached to request headers)
CTNP_CMS_USER_NAME	No	CMS user name (attached to request headers)
CTNP_TIMEOUT_MS	No	HTTP timeout for non-SSE requests in ms (default: 30000)

SSE requests (list/stream endpoints) always use a fixed 150-second timeout.

Client Setup

VS Code

A starter .vscode/mcp.json is already created in this project. Edit it to fill in your real values:

{
  "servers": {
    "ctnp": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "env": {
        "CTNP_API_URL": "http://localhost:3030",
        "CTNP_CMS_URL": "https://your-cms-url.example.com",
        "CTNP_BEARER_TOKEN": "your-cms-license-checksum-here"
      }
    }
  }
}

${workspaceFolder} is supported by VS Code and resolves to the open folder — no need to hardcode absolute paths.

Steps:

• Run npm run build to produce dist/index.js
• Open this project folder in VS Code
• Edit .vscode/mcp.json — replace the three env values with your real credentials
• VS Code will auto-detect and start the server

To use this server from a different VS Code workspace, copy the config to that workspace's .vscode/mcp.json and change args to the absolute path d:/dev/ai/ctnp-mcp/dist/index.js.

Claude Desktop

Edit ~/AppData/Roaming/Claude/claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "ctnp": {
      "command": "node",
      "args": ["d:/dev/ai/ctnp-mcp/dist/index.js"],
      "env": {
        "CTNP_API_URL": "http://localhost:3030",
        "CTNP_CMS_URL": "https://your-cms-url.example.com",
        "CTNP_BEARER_TOKEN": "your-cms-license-checksum-here"
      }
    }
  }
}

Cursor

Create or update .cursor/mcp.json — same structure as Claude Desktop above.

Note: Cursor also does not support ${workspaceFolder} in mcp.json — use absolute paths.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json — same structure as Claude Desktop above.

Available Tools (88 total)

AB Tests (23 tools)

abtest_list · abtest_get · abtest_create · abtest_update · abtest_patch · abtest_patch_metadata · abtest_patch_mde · abtest_patch_pushed_variation · abtest_launch · abtest_stop · abtest_reset · abtest_schedule · abtest_delete · abtest_get_exposure_counts · abtest_get_goals · abtest_get_results · abtest_get_goal_timeseries · abtest_get_page_actions · abtest_get_actions_performance · abtest_get_overrides · abtest_save_variation · abtest_duplicate_variant · abtest_delete_variant

Audiences (22 tools)

audience_get_summary · audience_list · audience_list_stream · audience_get · audience_create · audience_update · audience_patch_basic · audience_patch_group_name · audience_delete · audience_update_priority · audience_get_dependencies · audience_get_insights · audience_get_personalizations · audience_get_targeting · audience_get_visits · audience_get_visit_count · audience_get_conversions · audience_get_conversion_goals · audience_ai_generate · audience_breakdown · audience_conversions_stream · audience_visits_stream

Personalization (21 tools)

personalization_list · personalization_get · personalization_create · personalization_update · personalization_delete · personalization_duplicate · personalization_launch · personalization_stop · personalization_reset · personalization_relaunch · personalization_schedule · personalization_push · personalization_get_page_actions · personalization_get_actions_performance · personalization_get_all_actions_performance · personalization_get_goal_timeseries · personalization_get_audience_page_traffic · personalization_get_overrides · personalization_save_variation · personalization_launch_override · personalization_delete_overrides

Actions (8 tools)

action_get_redirect_url · action_get · action_search · action_get_trends · action_add · action_list · action_edit · action_usage

Events (8 tools)

event_list · event_get · event_create · event_update · event_delete · event_get_definitions · event_get_definition · event_get_property_definitions

Experiments (3 tools)

experiment_list · experiment_goal_conversions · experiment_page_visitors

Dashboard (2 tools)

dashboard_overview · dashboard_projects

Auth (1 tool)

auth_get_privileges

Troubleshooting

"invalid configuration" on startup Check that CTNP_API_URL, CTNP_CMS_URL, and CTNP_BEARER_TOKEN are all set in the MCP client's env block with real values (not placeholders).

Server not appearing in VS Code Make sure you ran npm run build and that dist/index.js exists. The path in args must be the absolute path to this file.

401 Unauthorized from API Your CTNP_BEARER_TOKEN is wrong or expired. Obtain a fresh checksum from the CMS configuration panel.

Tool returns { error: true, status: 0 } Network error — verify CTNP_API_URL is reachable from the machine running the MCP server.

SSE tools time out List/stream tools use a 150-second timeout. If your dataset is very large, the API may exceed this. Contact your CTnP administrator to optimize the query.

Building fails with TypeScript errors Ensure Node.js 18+ is installed (node --version) — fetch and AbortSignal.timeout require Node 18+. Run npm install to ensure all type packages are present.