Connect an AI to Convertlyft

Convertlyft is an MCP server. Any MCP client can read your site's numbers, sessions, errors and SEO, and propose changes that you approve.

That is the whole address: remote MCP over Streamable HTTP. Some tools work before you sign in: the free SEO scan of any public site, the agent-readiness check from that scan, and a search of these docs. Everything about your own site asks you to sign in once, in your browser.

Chat apps: paste the address

claude.ai

1. Open Customize → Connectors.
2. Press + Add, then Add custom connector.
3. Name it Convertlyft, paste https://mcp.convertlyft.com/mcp and press Continue.
4. Keep the sign-in settings Claude detects, then press Add. When Claude first needs your data, your browser opens Convertlyft: sign in, pick the site, press Allow.

On the Free plan Claude allows one custom connector. Steps from Claude's help article.

Claude Desktop

The same steps, in the app's own Customize → Connectors. A remote server like this one is added there, not in claude_desktop_config.json, which is for servers that run on your computer.

Claude on your phone

Add the connector on claude.ai or in Claude Desktop first. In Claude's words: "Once you connect to a service on Claude or Claude Desktop, it will be available to use the next time you log in to your account on Claude for iOS or Android."

ChatGPT

1. Open ChatGPT Plugins, press the plus button, then Add custom MCP server.
2. Enter a name and description, and paste https://mcp.convertlyft.com/mcp as the public endpoint.
3. Choose OAuth for authentication, review the warning, press I understand and want to continue, then Create as a plugin.

Custom MCP servers in ChatGPT depend on your plan and on developer mode, which OpenAI controls and has been renaming. Steps from OpenAI's guide; plan rules are in OpenAI's help article.

One-click install

Each button opens the app and asks you to confirm. It adds https://mcp.convertlyft.com/mcp and nothing else; the first call then opens your browser to sign in.

Or write the file yourself.

{
  "mcpServers": {
    "convertlyft": {
      "url": "https://mcp.convertlyft.com/mcp"
    }
  }
}

{
  "servers": {
    "convertlyft": {
      "type": "http",
      "url": "https://mcp.convertlyft.com/mcp"
    }
  }
}

Coding agents and editors

Claude Code

claude mcp add --transport http convertlyft https://mcp.convertlyft.com/mcp

Then run /mcp in a session to sign in.

Windsurf

{
  "mcpServers": {
    "convertlyft": {
      "serverUrl": "https://mcp.convertlyft.com/mcp"
    }
  }
}

Zed

{
  "context_servers": {
    "convertlyft": {
      "url": "https://mcp.convertlyft.com/mcp"
    }
  }
}

JetBrains AI Assistant

{
  "mcpServers": {
    "convertlyft": {
      "url": "https://mcp.convertlyft.com/mcp"
    }
  }
}

Gemini CLI

{
  "mcpServers": {
    "convertlyft": {
      "httpUrl": "https://mcp.convertlyft.com/mcp"
    }
  }
}

Or: gemini mcp add --transport http convertlyft https://mcp.convertlyft.com/mcp

Cline

{
  "mcpServers": {
    "convertlyft": {
      "type": "streamableHttp",
      "url": "https://mcp.convertlyft.com/mcp"
    }
  }
}

Codex

codex mcp add convertlyft --url https://mcp.convertlyft.com/mcp
codex mcp login convertlyft

# or in ~/.codex/config.toml
[mcp_servers.convertlyft]
url = "https://mcp.convertlyft.com/mcp"

Skills and plugins

Skills teach your AI how to read Convertlyft's evidence: which tool to call, in what order, and what the numbers can and cannot tell you. They are public at github.com/Convertlyft/skills.

Claude Code plugin

The MCP server, every skill, and a check that asks you before your AI records a change on your live site (cvl_change_apply) or starts an operator run (cvl_operator_run).

/plugin marketplace add Convertlyft/skills
/plugin install convertlyft@convertlyft

Codex and Cursor read the same repository as a plugin marketplace.

Any agent that reads skills

Codex, Cursor, Gemini CLI, GitHub Copilot and others. This adds the skills only; add the server with the steps above.

npx skills add Convertlyft/skills
# or, from this website
npx skills add https://convertlyft.com

Connected AIs can also read every skill as an MCP resource under convertlyft://skills/, without signing in.

Choose which tools load

Your AI loads every tool it is given before it reads your first message, so the address above loads a core set: the start-here reads, the no-account tools, every tool that writes anything, and two helpers. cvl_search_tools finds any other tool and cvl_call_read runs a read tool by name. To load whole groups up front, add ?features= to the address:

https://mcp.convertlyft.com/mcp?features=behaviour,seo

To give an AI reads only, use the address below. It lists no tool that writes, and refuses one if it is called anyway.

https://mcp.convertlyft.com/mcp?read_only=true

Sign-in and tokens

Most clients sign in through your browser: sign in, pick the site, and press Allow. Reads are allowed by default; starting crawls and making SEO changes stay off unless you tick them.

Clients that cannot sign in through a browser can send a personal access token as Authorization: Bearer …; create one on the Developer page in the app. Keep it in an environment variable or your client's secret store, never in a file you commit.

claude mcp add --transport http convertlyft https://mcp.convertlyft.com/mcp \
  --header "Authorization: Bearer $CONVERTLYFT_TOKEN"

# Codex, in ~/.codex/config.toml
[mcp_servers.convertlyft]
url = "https://mcp.convertlyft.com/mcp"
bearer_token_env_var = "CONVERTLYFT_TOKEN"

One token works for both: a token from signing in, or a personal access token, is accepted by the MCP server and the REST API alike, for the one site it was made for.

No-code tools

These connect as MCP clients. Use the address above and, where the tool has no browser sign-in, a personal access token as the bearer token.

• Zapier: add the MCP Client app (beta). Server URL https://mcp.convertlyft.com/mcp, Transport Streamable HTTP, then OAuth or your token in Bearer Token. Its actions include Run Tool and Run Read-Only Tool. Zapier's guide.
• n8n: the MCP Client Tool node for an AI agent, or the standalone MCP Client node. Endpoint https://mcp.convertlyft.com/mcp, Server Transport HTTP Streamable, Authentication Bearer Auth or MCP OAuth2. n8n's docs.
• Make: the MCP Client app's Call a tool module. Add the server by URL and give your token as the access token. Make's docs.

Scripts

Every read tool is also a plain HTTP call: GET https://convertlyft.com/api/tools/<name>, arguments in the query string, your token in the header. The worked examples cover dates, quotas and errors; the OpenAPI document lists every endpoint.

curl -s "https://convertlyft.com/api/tools/cvl_whoami" \
  -H "Authorization: Bearer $CONVERTLYFT_TOKEN"

import json, os, urllib.request

req = urllib.request.Request(
    "https://convertlyft.com/api/tools/cvl_whoami",
    headers={"Authorization": "Bearer " + os.environ["CONVERTLYFT_TOKEN"]},
)
print(json.load(urllib.request.urlopen(req)))

const res = await fetch("https://convertlyft.com/api/tools/cvl_whoami", {
  headers: { Authorization: `Bearer ${process.env.CONVERTLYFT_TOKEN}` },
});
console.log(await res.json());

function whoami() {
  const token = PropertiesService.getScriptProperties().getProperty("CONVERTLYFT_TOKEN");
  const res = UrlFetchApp.fetch("https://convertlyft.com/api/tools/cvl_whoami", {
    headers: { Authorization: "Bearer " + token },
  });
  Logger.log(res.getContentText());
}

curl -s https://mcp.convertlyft.com/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

CI

Create a personal access token on the Developer page with only the scopes the job needs, store it as a CI secret named CONVERTLYFT_TOKEN, and call the REST API or the MCP server with it as above.

Headless sign-in (device code, RFC 8628)

The API also has a device-code flow, for a machine that has no browser. Step 1 asks for a code:

curl -s -X POST https://convertlyft.com/api/tokens/device/code \
  -H "content-type: application/json" \
  -d '{"client_id":"my-ci-job","scopes":["reports:read","sessions:read"]}'
# → {"device_code","user_code","verification_uri","verification_uri_complete","expires_in","interval"}

Step 2: a person opens verification_uri (https://convertlyft.com/app/device, or verification_uri_complete with the code filled in), signs in, checks that the code matches user_code, picks the site and presses Allow. Codes last ten minutes and work once. Step 3 polls every interval seconds until the token arrives:

curl -s -X POST https://convertlyft.com/api/tokens/device/token \
  -H "content-type: application/json" \
  -d '{"device_code":"<device_code>","client_id":"my-ci-job"}'
# → 400 {"error":"authorization_pending"} until approved, then
# → 200 {"access_token":"cvl_pat_…","token_type":"bearer","scope":"…"}

Polling faster than interval answers slow_down with a longer interval; use it. A refusal on the page answers access_denied, and a code left too long answers expired_token. The token is read-only unless the person ticks a write on the page, and is listed under Connected apps, where it can be revoked.

Teams and companies

• Claude Team and Enterprise: an Owner adds the connector once in Organization settings → Connectors (Add → Custom → Web, then the address above). Each member then finds it under Customize → Connectors and presses Connect, which signs them in to Convertlyft as themselves. Claude's help article.
• ChatGPT Business and Enterprise: workspace admins create the app from the workspace settings and publish it to members. OpenAI's help article has the current steps for each plan.

Each person who connects signs in and picks one site, so they see only the sites they belong to.

For crawlers and registries

• /.well-known/ai-catalog.json and /.well-known/mcp/server-card.json: the MCP server card (SEP-2127).
• The capabilities list: every tool and the scopes it needs.
• /.well-known/skills/index.json: the skills, for npx skills add https://convertlyft.com.
• llms.txt and llms-full.txt: the API guide for a model.