Install and configure the Apex MCP server

The Apex MCP server lets model clients read and manage Apex experiments through the Model Context Protocol. Use it when you want ChatGPT, Codex, Claude Desktop, Claude Code, Cursor, or another MCP client to list tests, inspect a draft, create a draft or pause an experiment, read goals, pull brand context, or generate QA preview URLs.

Prerequisites

• Node.js 18 or newer.
• An Apex API key with the permissions needed for the tools you plan to call.
• Either APEX_API_KEY in the MCP process environment or a saved user/shop CLI credential at ~/.drip/credentials.json. User keys minted by apex login are supported.

The server reads configuration in this order. Legacy DRIP_API_KEY and DRIP_BASE_URL names remain working fallbacks:

Install

Run the packaged server with npx:

npx -y @drip-apex/mcp-server

For local monorepo development, build the package and run the compiled server:

npm --prefix packages/mcp-server install
npm --prefix packages/mcp-server run build
node packages/mcp-server/dist/server.js

Claude Desktop

APEX_API_KEY needs @drip-apex/mcp-server 0.2.0 or newer; on 0.1.3 set DRIP_API_KEY instead.

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "drip-ab-testing": {
      "command": "npx",
      "args": ["-y", "@drip-apex/mcp-server"],
      "env": {
        "APEX_API_KEY": "apx_your_key_here",
        "APEX_BASE_URL": "https://app.drip-apex.com"
      }
    }
  }
}

If you already authenticated with apex login on the same machine, you can omit env and let the server read ~/.drip/credentials.json: Resolution is APEX_API_KEY (with DRIP_API_KEY fallback), saved user key, then saved shop key. Set DRIP_ORG/DRIP_SHOP to override saved user-key context.

{
  "mcpServers": {
    "drip-ab-testing": {
      "command": "npx",
      "args": ["-y", "@drip-apex/mcp-server"]
    }
  }
}

Claude Code

Use a project .mcp.json or user-level MCP config with the same server block:

{
  "mcpServers": {
    "drip-ab-testing": {
      "command": "npx",
      "args": ["-y", "@drip-apex/mcp-server"],
      "env": {
        "APEX_API_KEY": "apx_your_key_here",
        "APEX_BASE_URL": "https://app.drip-apex.com"
      }
    }
  }
}

For a local checkout:

{
  "mcpServers": {
    "drip-ab-testing": {
      "command": "node",
      "args": ["./packages/mcp-server/dist/server.js"],
      "env": {
        "APEX_API_KEY": "apx_your_key_here",
        "APEX_BASE_URL": "https://app.drip-apex.com"
      }
    }
  }
}

Cursor

Add this to .cursor/mcp.json or Cursor's global MCP config:

{
  "mcpServers": {
    "drip-ab-testing": {
      "command": "npx",
      "args": ["-y", "@drip-apex/mcp-server"],
      "env": {
        "APEX_API_KEY": "apx_your_key_here",
        "APEX_BASE_URL": "https://app.drip-apex.com"
      }
    }
  }
}

Verify

Restart the MCP client, then ask it to list Apex experiments. A valid setup can call list_experiments. If the server exits immediately with "No API key found", set APEX_API_KEY for that MCP client or run:

apex login

Troubleshooting

• No API key found: set APEX_API_KEY in the MCP config or create ~/.drip/credentials.json with apex login.
• HTTP 401: the key is missing, expired, revoked, or not in the apx_ key family.
• HTTP 403: the key exists but does not have permission for the requested API endpoint.
• Non-production testing: set APEX_BASE_URL to the target Apex base URL and keep production credentials out of that config.

Related pages

• MCP tool reference
• Install and authenticate the Apex CLI
• API keys and public API v1

Remote connector

Use https://app.drip-apex.com/api/mcp to connect without installing a local MCP server.

• Claude web: Open Settings, Connectors, add a custom connector, and enter the endpoint URL. Choose Connect and sign in to Apex.

ChatGPT directory plugin

Apex is preparing its listing and is not available in the directory yet. Once it is published, find Apex in the ChatGPT plugin directory, choose Connect, sign in to Apex, and review the consent page before approving. Select Apex in your chat and ask it to list your experiments. Until publication, use a custom connector.

ChatGPT custom connector

Enable Developer mode in ChatGPT Settings under Security and login, open ChatGPT Plugins, select the plus button, and name the connector Apex. Choose a public MCP connection with https://app.drip-apex.com/api/mcp and OAuth authentication. Create the connection, inspect the discovered tools, and sign in to Apex. Account and workspace policies determine whether custom plugins are available. See OpenAI's connection instructions.

Codex

Codex connects to the same MCP endpoint directly. It does not need the ChatGPT directory listing. Add the connector and authenticate through OAuth:

codex mcp add apex --url https://app.drip-apex.com/api/mcp
codex mcp login apex

Sign in to Apex, approve the selected shop and permissions, then restart your Codex session and inspect its MCP tools. Ask it to list Apex experiments. These steps work before and after directory publication. See OpenAI's MCP configuration instructions.

The Apex approval page names the connector, lists its requested scopes, and lets you choose an organization and a shop from your memberships. Review those permissions before approving. The connector receives a scoped Apex user key valid for 30 days; it never receives your Apex password. Reconnect after expiry, as refresh tokens are not issued yet.

Revoke access in Settings → Account → CLI keys. Revocation takes effect through the same key validation used by the API. Requests keep the approved organization and shop context; manually minted user keys without a saved shop can send X-Apex-Shop.

Read-only connectors should request shops:read; connectors that edit experiments also need shops:write. Your current shop role still limits what a connector can do.

Start without a shop

You can approve the remote connector for your organization before you create a shop. Choose “No shop yet, I will create one from the connector”, grant shops:write, then ask for create_shop with your shop name, domain and platform. An unbound connector accepts either shops:read or shops:write to connect and list tools. Creating the shop requires shops:write; reading shop data requires shops:read. Grant both for the full setup flow. The connector binds to that shop once. Ask for get_install_instructions, install Apex on the storefront, then use get_install_status to check incoming data. Complete human QA and launch in Apex.

create_shop reuses an unarchived shop with the same normalized domain in your organization. If the shop is created but connector binding fails, the response includes its shop id. Retry create_shop with the same domain to bind it.

For Shopify shops, installation instructions use the snippet until Apex enables the public app link. Apex operators set SHOPIFY_PUBLIC_INSTALL_CONFIRMED=1 in Vercel after confirming public distribution in the Shopify Partner Dashboard. The variable defaults off; while off, shopify_oauth_url is omitted and the instructions say “The Shopify app link follows once Apex enables it.”

Usage telemetry

Starting with MCP server 0.5.0, local tool calls send best-effort usage records to Apex. Hosted connector calls are recorded by the remote server. Records include the tool name, duration, outcome, API call count, first error status/code/request ID and redacted route, MCP server package version, argument names, and authenticated account/shop context. Argument values, variation file contents, and API keys are never included in usage records.

Set APEX_TELEMETRY=0 in the local MCP server's environment to disable usage telemetry. Local beacons are also disabled under NODE_ENV=test, have an 800 ms timeout, and cannot change tool results. The environment opt-out applies to the local server; hosted connector calls retain their server-side usage records and audit entries.

Operators can use npm run cli-usage -- --client apex-mcp for local calls or --client apex-mcp-remote for hosted calls. Hosted usage retains that fixed client label and the server package version. Add --assistant to compare remote calls by the OAuth key name (MCP - <client name>), grouped across users and keys.

On initialize messages, a separate audit entry captures the connected client's name and version, each bounded to 40 characters. The hosted server is stateless; a later tool request does not inherit that initialization metadata.

Tools declare read-only, destructive, idempotent and open-world hints so MCP clients can group approvals. Trigger/file replacement, integration recipes, builds, pause and complete retain their destructive hints. Strict reads and whole-value trigger/file replacement are idempotent; supply expected_version when replacing a file. These hints do not change API permissions.

Removing a connector in ChatGPT or running codex mcp logout apex removes the client's local connection. Revoke its key in Apex Settings → Account → CLI keys to prevent further API access.

For listing operators, the deployment environment variable OPENAI_APPS_CHALLENGE_TOKEN supplies the exact plain-text response at https://app.drip-apex.com/.well-known/openai-apps-challenge. It is uncached and returns 404 when unset. Configure its value through Bitwarden and the deployment environment; never add a value to the repository.