Convert MCP Server

Connect Claude, Cursor, and other AI assistants to your Convert account

🌟 Overview

The Convert MCP server lets AI assistants explore your Convert account without custom integrations. Once connected, the assistant can answer questions, surface insights, and (if you permit) manage entities such as experiences, audiences, and goals.

What is MCP?

MCP (Model Context Protocol) is an open standard that allows AI models to interact with applications through a consistent interface. It acts as a bridge, letting AI assistants access your Convert data without needing to understand specific API protocols.

Key Benefits:

• 🔌 Zero-config integration – Works with Claude Desktop, Cursor, and any MCP-compatible client
• 🔍 Full API access – Comprehensive coverage of Convert's REST API v2
• 📚 Built-in knowledge – 5,776 indexed chunks across 500 Convert support article URLs
• 🛡️ Configurable permissions – Three access levels from reporting-only to full read/write
• 🧩 Namespaced tools – Clean interface with 13 generated API namespaces plus one computed operator namespace
• 🧠 MCP prompts – 19 curated Convert experimentation prompts exposed through prompts/list and prompts/get

📚 Table of Contents

• 🚀 Quick Start
• 🔗 Client Integration
• 🛠 What You Can Do
• 📊 Example Prompts
• 🔐 Security
• ❓ Troubleshooting

🚀 Quick Start

What you need

1. Convert API credentials – In Convert, go to Settings → Integrations → API and copy your Application ID and Secret Key.
2. Node.js 20+ – Only required if you run the server from source.
3. Access level – Set TOOLS_FOR_CLIENT to control what the assistant can do:
   • reporting (default) – basic analytics and read-only summaries
   • readOnly – detailed configuration data without modifying anything
   • all – read/write access (only use when you explicitly want the assistant to make changes)

🔗 Client Integration

The server implements the Model Context Protocol and works with Claude Desktop, Cursor, and any MCP-compatible client.

Recommended Models

For the best experience, use models with strong agentic capabilities:

• Claude Sonnet 4.5 or newer
• GPT-5 or newer
• Other frontier models with multi-step reasoning abilities

Enable extended thinking – Extended thinking is a special reasoning mode that significantly improves MCP tool calling, multi-step workflows, and complex API interactions. Enable it in your client settings if available.

Configuration

Add this configuration to your MCP settings file:

{
  "mcpServers": {
    "convert": {
      "command": "npx",
      "args": ["-y", "@convertcom/mcp-server@latest"],
      "env": {
        "CONVERT_API_KEY": "your_application_id",
        "CONVERT_API_SECRET": "your_secret_key",
        "TOOLS_FOR_CLIENT": "reporting"
      }
    }
  }
}

Configuration file locations:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
• Cursor: .cursor/mcp.json in your project directory
• Other clients: Refer to your client's documentation for MCP server configuration

Save the file and restart your client to activate the Convert tools.

Environment Variables

| Variable | Required | Description | Default | | -------------------- | -------- | ----------------------------------------------- | ----------- | | CONVERT_API_KEY | ✅ | Your Convert Application ID | - | | CONVERT_API_SECRET | ✅ | Your Convert Secret Key | - | | TOOLS_FOR_CLIENT | | Access level: reporting, readOnly, or all | reporting | | CONVERT_ACCOUNT_ID | | Optional live-test target account | - | | CONVERT_PROJECT_ID | | Optional live-test target project | - | | CONVERT_HTTP_HEADER_* | | Optional extra API headers, e.g. CONVERT_HTTP_HEADER_X_CONVERT_ENVIRONMENT=staging; auth/signing headers cannot be overridden | - | | CONVERT_API_MAX_RETRIES | | Max bounded retries for 429/503 idempotent requests | 2 |

🛠 What You Can Do

Once connected, your AI assistant can:

• 📊 View experiment performance – Get real-time stats on your A/B tests and experiences
• 🎯 Analyze goals and conversions – See which goals are tracking and how they're performing
• 👥 Explore audience segments – Understand your targeting rules and segmentation
• 🔍 Search Convert documentation – The assistant has instant access to Convert's full support library, including OpenAI-compatible search/fetch docs tools
• 🧠 Use curated MCP prompts – Portfolio summaries, project audits, QA checks, split URL setup, docs search, and experiment-builder workflows are available via MCP prompts
• 🧭 Run operator workflows – The operator namespace performs audits, health checks, defaults inference, and safe verified creation/update flows without adding many tools
• 📈 Access account analytics – Review live data, history, and visitor tracking
• ⚙️ Manage experiments – Create, update, or pause experiences (requires TOOLS_FOR_CLIENT=all)

The assistant doesn't need to know technical details—just ask questions in plain English.

| Namespace | Reporting & readOnly actions | Extra actions in all | | --- | --- | --- | | accounts | list, get, get_billing_portal, get_live_data, get_history, list_users_accesses, list_api_keys, list_sdk_keys | create_sdk_key | | projects | list, get, get_live_data, get_history | create, update | | domains | list, get, get_by_url, check_code | create, update, delete | | experiences | list, get, get_by_key, get_live_data, get_history, aggregated_report, daily_report, daily_traffic_allocation, get_variation_screenshot, get_heatmap_background, get_heatmap_overlay, get_change | create, clone, update, update_variation, upload_variation_screenshot, convert_variation, update_change | | sections | list | create, update, update_experience_sections, add_version, update_version | | goals | list, get, get_by_key | create, update, delete, clone | | tags | list, get | create, update, delete | | hypotheses | list, get | create, update, update_status, convert, delete | | knowledgebases | list, get | create, update, delete | | observations | list, get | create, update, delete | | locations | list, get, presets | create, update, delete, clone | | audiences | list, get, presets | create, update, delete, clone | | features | list, get, get_by_key | create, update, delete | | operator | project_audit, experiment_portfolio, experiment_velocity, draft_qa, active_health, implementation_health, failed_test_analysis, hypothesis_quality_audit, audience_segment_comparison, cleanup_candidates, get_defaults | create_custom_code_ab_test, create_split_url_test, enable_split_url_regex, safe_update_variation_code |

Access Control: With TOOLS_FOR_CLIENT=all, additional write actions (create/update/delete) become available. Keep permissions as narrow as possible and escalate only when necessary.

🧪 Experience Authoring Notes

For custom JavaScript or CSS in an A/B test, use experiences.create or experiences.update_variation with changes[].type: "customCode" and data: { "js": "...", "css": "" }. defaultCode is for Visual Editor payloads and requires Convert's generated fields.

Split URL regex support is an experience-level setting. Use experiences.update without variation_id:

{
  "action": "update",
  "path": { "account_id": 123, "project_id": 456, "experience_id": 789 },
  "body": {
    "settings": {
      "split_url_settings": { "split_regex_support": true }
    }
  }
}

If a client sends those settings to experiences.update_variation, the server returns a structured retry call instead of silently letting the wrong endpoint no-op.

📊 Example Prompts

Once set up, try these prompts with your AI assistant:

Get Insights from Your Data

Show me the performance of all active experiments in my account

How many experiences do I have running right now?

Summarize all A/B tests with conversion rates above 5% from the last 30 days

Analyze Experiment Performance

Get me the latest conversion data for my homepage experiment

Compare the performance of mobile vs desktop experiments this month

Show me which audience segments are performing best across all active tests

Manage Tests (Requires TOOLS_FOR_CLIENT=all)

Create a new A/B test for the pricing page targeting returning visitors

Update the traffic split on experience 789 to 50/50

Pause any experiences that have been running for more than 30 days with negative lift

🔎 Documentation Search Tools

The server exposes two read-only documentation tools using OpenAI's MCP search/fetch connector format:

| Tool | Best for | | ---- | -------- | | search | Finding Convert docs and returning results[].id, title, and canonical url values. | | fetch | Full-text retrieval for an ID returned by search. |

Search is hybrid. Keyword search is always available; semantic vector search starts from the packaged vector store. At runtime the server opens a temporary copy of the committed index so installed packages are not mutated and docs search stays hybrid instead of falling back to keyword-only mode.

🔐 Security

The server uses your Convert API credentials to authenticate requests. Your credentials are stored only in environment variables and never exposed in code.

Best practices:

• Start with TOOLS_FOR_CLIENT=reporting and escalate only when needed
• Keep your API credentials secure and never commit them to version control

❓ Troubleshooting

| Problem | How to fix | | ------- | ---------- | | Tools not visible after install | Restart the client and confirm the JSON config points to the correct command/env vars. | | 401 Unauthorized | Re-check API key/secret and your account permissions. | | Requests blocked or failing | Use a smart model like Claude Sonnet 4.5, GPT-5, or newer with strong agentic capabilities. Enable extended thinking if available. The model needs to handle multi-step API workflows and parse response alerts. | | Documentation search feels off | Refine the query with specific terms (product codes, URLs, field names). The package includes the semantic vector index; if needed, restart the MCP client so the runtime copy is rebuilt from the packaged store. |

Need more help? Visit the Convert Help Center.

📦 API Coverage

The server provides comprehensive coverage of Convert's REST API v2:

• Account Operations: User management, billing, and settings
• Project Management: Configuration, domains, and collaborators
• Experience Control: A/B tests, MVT, Split URL, and deployments
• Analytics & Reporting: Real-time data, conversion tracking, and statistical analysis
• Goal Tracking: Conversion goals, revenue tracking, and custom events
• Audience Management: Segmentation rules and targeting
• Feature Flags: Feature management and rollout control

Made with ❤️ by the Convert Team

© 2026 Convert Insights, Inc. Built for the automation-minded optimizer.

Website • Documentation • API Reference