Convert MCP Server

THIS ARTICLE WILL HELP YOU:

• What is MCP?

   

• Quick Start - Remote MCP Connector Setup

• Local MCP Server Alternative

• Example Usage

• Security & Authentication

• Troubleshooting

• Example Workflows

---

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:

• Hosted remote connector – Connect Claude, ChatGPT, Cursor, and other supported MCP clients through secure Convert OAuth.
• 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.
• Scoped authorization – Hosted connector users choose which Convert accounts and projects they authorize. Local npm users can continue to use reporting, readOnly, or all access levels.
• 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

Recommended: Remote MCP Connector

Use Convert’s hosted connector URL:

https://mcp.ai.app.convert.com/mcp

Your AI assistant will open Convert, ask you to sign in, and let you choose the accounts and projects the connector can access. You do not need to copy Convert API credentials into the assistant.

Claude, Claude Desktop, and Claude Code

1. Open Claude settings and go to Connectors.
2. Add a custom connector.
3. Paste the following connector URL:https://mcp.ai.app.convert.com/mcp
4. Connect, sign in to Convert, and approve the account or project access.

Cursor and Other Remote MCP Clients

1. Create a new remote MCP server entry.
2. Use Streamable HTTP as the transport when your client asks for a transport type.
3. Set the server URL to:https://mcp.ai.app.convert.com/mcp
4. Complete the Convert OAuth flow and return to your client.

Once connected, the remote MCP connector can list, inspect, and summarize experiences, variations, goals, audiences, locations, and live data. It can also create safe draft A/B and Split URL tests, update variation code, search Convert documentation, run curated workflows and operator audits, and read back results before reporting success.

Local MCP Server Alternative

Use the npm package when you specifically need a local stdio server instead of the hosted OAuth connector. The local server continues to work and is kept up to date, but it requires Convert API credentials and client-side configuration.

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

For clients that support remote MCP servers, prefer the hosted connector and Streamable HTTP. Use the local configuration only when the client or your security requirements call for a local stdio server.

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."

Local API-Key Configuration

Local Server Access Levels

This section applies only to the local API-key setup. For the hosted connector, users approve account and project access during the Convert OAuth flow.

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 through approved OAuth access on the hosted connector, or with TOOLS_FOR_CLIENT=all on the local server.
• 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

Hosted Connector Security

The hosted connector uses Convert OAuth. Convert opens a sign-in and authorization flow where users choose the accounts and projects the connector can access. API credentials do not need to be copied into the MCP client.

Local API-Key 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 when using the local npm server.
• 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

• For the hosted connector, authorize only the accounts and projects required for the workflow.
• Start with reporting access level and escalate only when needed when using the local npm server.
• 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

Problem	How to fix
Tools not visible after connection	For the hosted connector, confirm that the custom connector URL is https://mcp.ai.app.convert.com/mcp, reconnect, and complete the Convert OAuth approval flow.
401 Unauthorized	For the hosted connector, reconnect and confirm that the intended Convert account or project was approved.
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.
Search results feel incomplete	For the hosted connector, confirm that the OAuth authorization includes the relevant account or project and that the requested workflow is permitted.
Write action does not apply	Confirm TOOLS_FOR_CLIENT=all is enabled and that your Convert API credentials have permission for the requested action.
Split URL update fails	Use the experience update workflow rather than updating the variation directly.
Screenshot upload fails	Confirm the client supports multipart uploads and that the image file is accessible to the MCP runtime.
Rate limit or service unavailable response	The server uses bounded retry and backoff for 429 and 503 responses. Unsafe write retries are avoided.

Getting Help

• Remote MCP connector and setup: https://mcp.ai.app.convert.com/
• Documentation: Convert API Documentation
• Convert Support: Convert Help Center
• NPM Developer Documentation: Convert MCP Server 

Updates

The hosted MCP connector is maintained by Convert and does not require users to install or manually update an npm package.

When the local client configuration uses npx -y @convertcom/mcp-server@latest, it retrieves the current npm package version when the process starts.