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 – 7,992 indexed chunks across 1,245 Convert documentation URLs
• 🛡️ Configurable permissions – Three access levels from reporting-only to full read/write
• 🧩 Namespaced tools – Clean interface with 15 generated API namespaces plus one computed operator namespace
• 🧠 MCP prompts – 20 curated Convert experience workflows 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.

Hosted Remote MCP

If your MCP client supports remote connectors, you can connect to Convert without managing local API keys:

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

Your client will open Convert for sign-in and permission approval. You can authorize selected projects, or explicitly choose Entire account, including future projects with a maximum role when your Convert role permits it. Runtime privilege is always capped by both that approved role and your live Convert role. The hosted endpoint exposes only the actions authorized by that grant, with separate read, write, and delete tools for clear safety classification, plus optional interactive views for portfolios, experience details, draft QA, engine-aware results, and privacy-reduced investigations in MCP Apps-capable clients. Existing selected-project OAuth connections remain valid and retain their current scope. Reconnect only when you intentionally want to upgrade a grant to entire-account access. Convert MCP advertises MCP catalog-change notifications so compatible clients can discover updated tools, prompts, and resources; host-managed app snapshots may still require an administrator refresh or app republishing. Catalog changes do not rotate or invalidate OAuth. The local npx setup below remains the default for stdio-based clients and existing installations.

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 experience 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 knowledge – OpenAI-compatible search/fetch spans the support library, exact API/SDK developer docs, and selected Convert website material with source-aware authority
• 🧠 Use curated MCP prompts – Portfolio summaries, account-grounded opportunity discovery, project audits, QA checks, docs search, and experience-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
• 🧪 Interpret experience evidence carefully – Hosted MCP Apps can render engine-aware results without treating MAB allocation as inference, MDE as observed lift, or deploy traffic as missing tracking
• 🩺 Investigate safely – The hosted investigation view summarizes source status, confirmed facts, hypotheses, limitations, and safe next checks without exposing raw visitor-level debug data
• ✅ Work with approvals – Inspect governed experience actions, submit approval requests only after explicit instruction, and let eligible human reviewers approve or reject exact requests
• 📈 Access account analytics – Review live data, history, and visitor tracking
• ⚙️ Manage experiences – 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.

MCP prompts are selected from the client's prompt or connector picker; mentioning a prompt name in ordinary chat does not guarantee that the client attaches it. In Claude, use Add files, connectors, and more → Connectors → Add from Convert, then choose the workflow and fill its arguments. See Prompt Intelligence for protocol-level verification details.

For plan, entitlement, quota, or usage questions, the assistant should use accounts.list to discover the account ID and then call accounts.get with query.include: ["stats"]. Plan capabilities and limits are returned under limitsAndCapabilities. Exact subscription details under billing.products are permission-sensitive and appear only when the authenticated Convert principal has billing-plan management and account-wide access.

| Namespace | Reporting & readOnly actions | Extra actions in all | | --- | --- | --- | | accounts | list, get, get_billing_portal, get_live_data, get_history, list_users_accesses, list_sdk_keys | create_sdk_key | | projects | list, get, get_live_data, get_history, debug_logs | 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, report_integrity, 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 | | approval_requests | list, get, get_settings | request, approve, reject, update_settings | | operator | project_audit, experiment_portfolio, experiment_velocity, draft_qa, active_health, implementation_health, investigate, failed_test_analysis, hypothesis_quality_audit, audience_segment_comparison, cleanup_candidates, get_defaults, prepare_feedback* | submit_feedback*, create_custom_code_ab_test, create_split_url_test, enable_split_url_regex, safe_update_variation_code |

* Feedback actions are advertised only when that runtime has feedback storage configured.

projects.create requires access to the selected account, project.add, and owner, account manager, or admin access across the entire account. It remains available to local TOOLS_FOR_CLIENT=all API-key sessions that satisfy all three gates. Hosted connectors advertise it only for an explicit entire-account OAuth grant, represented by projects: null, and enforce that grant again for the exact target account before dispatch. Selecting every currently visible project is still a selected-project grant and does not imply future-project access.

The same grant-aware catalog rule applies to account-wide billing portal, live-data, change-history, collaborator-list, and approval-setting actions. They remain absent for selected-project sessions and appear only for explicit entire-account sessions. The backend applies the lower privilege of the consent-time account role and the user's live role on every call. Local API-key sessions retain the generated account-wide actions subject to their Convert permissions. API-key listing is omitted everywhere because Convert intentionally returns no key records to API-authenticated callers; this avoids turning an empty API response into a false claim that the account has no keys.

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.

For implementation troubleshooting, start with the read-only operator.investigate action. It returns a sanitized convert.investigation.v1 evidence packet. Use projects.debug_logs and experiences.report_integrity only for authorized drill-down when the packet identifies an evidence gap; raw debug logs can contain visitor-level data and must not be copied into public support or escalation notes. Browser-capable MCP clients can load convert://playbooks/implementation-investigation/v1 for the matching page, network, DOM, and source-code workflow.

For governed experience actions, call the requested experience action first. If Convert returns ApprovalRequired, use approval_requests to inspect or submit the request only after explicit user instruction. Request creation can notify reviewers; approve/reject decisions are target-bound human governance actions, and the server never retries the original experience action automatically. Hosted OAuth exposes the project-scoped lifecycle for selected-project grants and adds account-wide approval settings only for an explicit entire-account grant.

Notification queries are not enabled in this release. They will become available after the corresponding backend feature rollout; existing notification settings in the Convert web application are unaffected.

🧪 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 experiences in my account

Use High-Impact Experience Opportunities on my project for the last 90 days in quick_wins mode. Ground the ranking in my Convert data, separate documentation inspiration, and do not create anything.

How many experiences do I have running right now?

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

Analyze Experience Performance

Get me the latest conversion data for my homepage A/B experience

Compare the performance of mobile vs desktop segments this month

Show me which audience segments differ across active tracked experiences

Manage Experiences (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. Support guidance is authoritative for product behavior and troubleshooting, developer docs for exact API/SDK contracts, and website pages for commercial/compliance questions. At runtime the server opens a temporary copy of the committed index so installed packages are not mutated.

When a user explicitly asks to send product feedback, call operator.prepare_feedback first. It sanitizes arbitrary structured context and returns a summary, bounded context outline, byte count, and digest without storing anything. Show those exact fields to the user and ask for approval; only then may a write-capable profile call operator.submit_feedback with the exact prepared summary and digest. The server stores at most 256 KiB and returns only an idempotent receipt. It never submits automatically after errors. Browse-only staff impersonation may prepare a sanitized preview, but it cannot store or attribute feedback through the impersonated customer.

🔐 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