Convert MCP Server

What is MCP?

MCP (Model Context Protocol) is an emerging standard that allows AI models to interact with applications through a consistent interface. It acts as an abstraction layer, letting AI agents 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 articles, with hybrid semantic search.
• Configurable permissions – Three access levels from reporting-only to full read/write
• Namespaced tools – A compact tool interface with 16 top-level MCP tools and 113 callable action slots when TOOLS_FOR_CLIENT=all is enabled.
• MCP-native prompts – 19 curated workflows for common optimization, QA, setup, audit, and maintenance tasks.
• OpenAI-compatible search and fetch – Search Convert support content and retrieve relevant article content through MCP-compatible retrieval methods.
• Operational guardrails – Validation and safety checks help prevent unsupported payloads, invalid update paths, and silent API failures.

Quick Start

Prerequisites

Get your Convert API credentials:

1. Log into your Convert account
2. Go to Account Settings → API-Keys
   
   
3. Generate or copy your Application ID and Secret Key
   
   
   
4. Note your Account ID (found in account settings)
   

Consider starting with read-only access (TOOLS_FOR_CLIENT=reporting - see configuration below)

Installation & Setup

Option 1: NPX (Recommended)

# No installation needed - run directly

npx @convertcom/mcp-server@latest

Option 2: Global Installation

# Install globally

npm install -g @convertcom/mcp-server


# Run the server

mcp-server-convert

Client Configuration

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

Claude Desktop

1. Download Claude Desktop from claude.ai
2. Add server configuration to your Claude Desktop config file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json

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

Save the file and restart Claude Desktop. You should now see Convert tools available!

Cursor

1. Create a .cursor/mcp.json file in your project:

   mkdir -p .cursor && touch .cursor/mcp.json

2. Add the following configuration:

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

3. Save the file and restart Cursor. Convert tools will now be available!

Other MCP-Compatible Clients

Refer to your client's documentation for MCP server configuration file locations and format.

Example Usage

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

Get Insights from Your Convert 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 with a 70/30 traffic split" 
• "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"

Use Curated Workflows

MCP-native prompts are available for common Convert workflows, including audits, portfolio summaries, velocity checks, QA drafts, active health checks, implementation health checks, cleanup candidates, project defaults, custom-code A/B creation, split URL creation, regex enablement, and safe variation code updates.

Example prompts:

• "Run an active health check for my current experiments."

• "Draft a QA plan for this A/B test before launch."

• "Create a split URL experiment and make sure query parameters are handled safely."

• "Review this variation code and apply a safe update."

Configuration

Access Levels

Choose the appropriate access level based on your needs:

reporting (Default - Recommended)

Perfect for analytics and insights

• Account data and project information
• Real-time experiment tracking and performance reports
• Goals, audiences, and conversion analytics
• Live visitor data and traffic allocation

readOnly

All reporting tools plus detailed configuration access

• Everything in reporting mode
• Detailed project and experience configurations
• Historical data and change logs
• Advanced analytics and forecasting data

all (Use with caution)

Complete access including write operations

• Everything in readOnly mode
• Create, edit, and delete experiments
• Manage audiences, goals, and project settings
• Full account administration capabilities

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
• Access account analytics – Review live data, history, and visitor tracking
• Manage experiments – Create, update, or pause experiences (requires TOOLS_FOR_CLIENT=all)
• Create and update goals using the full supported goal type set, including clicks_element, code_trigger, dom_interaction, scroll_percentage, advanced, ga_import, and triggering_rule.
• Create and update audiences and locations while preserving targeting rules.
• Create and update feature flags with typed default_value validation for boolean and numeric values.
• Access backend operations including billing portal actions and heatmap background or overlay operations where permissions allow.
• Run higher-level operator workflows for audits, summaries, QA, implementation health, cleanup, and experiment creation.

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

Available Tools

The server provides comprehensive coverage of Convert’s REST API v2, organized into a compact MCP interface. The server uses 16 top-level MCP tools with 113 callable action slots when TOOLS_FOR_CLIENT=all is enabled.

• 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 *
  And more...
• Knowledge search and fetch: OpenAI-compatible retrieval over Convert support documentation.
• Operator workflows: Higher-level actions for audits, summaries, QA, health checks, cleanup, project defaults, A/B creation, split URL creation, regex enablement, and safe code updates.
• Heatmap operations: Heatmap background and overlay capabilities where supported by the backend.
• Billing portal operations: Billing portal access where supported by account permissions.

Search and Knowledge Retrieval

Convert MCP uses OpenAI-compatible search and fetch methods backed by a refreshed Convert knowledge base. The knowledge base contains 5,776 chunks across 500 support articles and uses a rebuilt semantic Zvec vector store for hybrid retrieval instead of keyword-only search.

The runtime uses a temporary vector copy, so packaged vector data is not mutated during use.

Prompts and Workflows

The MCP server includes curated prompts for recurring Convert workflows.

Available workflow areas include:

• Audits
• Portfolio summaries
• Velocity analysis
• Draft QA
• Active health checks
• Implementation health checks
• Cleanup candidates
• Project defaults
• Custom-code A/B creation
• Split URL creation
• Regex enablement
• Safe variation code updates

Use these workflows when you want the assistant to complete a guided process rather than call individual tools one by one.

Data Correctness and Validation

The MCP server includes schema and validation behavior designed to keep Convert data consistent.

Supported correctness checks include:

• Audience create and update operations preserve non-null rules.
• Location create and update operations preserve targeting rules.
• Goal create and update operations support the full goal type set.
• Feature create and update operations validate typed default values for boolean and numeric defaults.

Guardrails

The MCP server includes guardrails to prevent common invalid requests and silent failures.

Guardrails include:

• Unsupported inline site_area payloads are blocked.
• Invalid clicks_link.settings.href match objects are blocked.
• Split URL updates are enforced through experiences.update rather than update_variation.
• Multipart variation screenshot uploads use real FormData.
• Readback recovery is used for post-persistence 500 responses.
• Bounded retry and backoff are applied for 429 and 503 responses, without unsafe write retries.

Security & Authentication

API Security

• HMAC-SHA256 signing: Every request is cryptographically signed
• Automatic expiration: Requests expire after 60 seconds
• No credential exposure: API keys never leave your local environment
• Least privilege: Choose the minimum access level needed for your use case
• HMAC-safe signing is used for resilient request authentication.
• Custom HTTP header passthrough is supported through CONVERT_HTTP_HEADER_*, with authentication and signing protections.

Best Practices

• Start with reporting access level and escalate only when needed
• Regularly rotate your API credentials
• Monitor API usage in your Convert dashboard
• Keep your credentials secure and never share them
• Use TOOLS_FOR_CLIENT=all only when your workflow requires write operations.
• Review AI-generated changes before applying them to live experiments.
• Use curated prompts for structured workflows such as QA, audits, and implementation health checks.

Troubleshooting

Common Issues

Getting Help

• Documentation: Convert API Documentation
• Convert Support: Convert Help Center
• NPM Developer Documentation: Convert MCP Server 

Updates

The MCP server is automatically updated when you restart your AI assistant. For manual updates:

 # Update to latest version
npm update -g @convertcom/mcp-server