Connect your AI agent (MCP)

WPInsight runs a Model Context Protocol (MCP) server. Connect it once and your AI agent can read the plugin data WPInsight has been recording for you — keyword ranks and their history, downloads, active installs, reviews, alerts and directory position — and answer questions about it in plain language.

Instead of opening five dashboard pages to work out why a rank moved, you ask:

“Why did my plugin lose ranking this week?”

“Which keywords should I focus on next?”

“Did my latest release change the download trend?”

The agent reads your tracked history and explains what it finds. It recommends changes; you decide what to ship. Nothing about your WordPress.org listing is edited by WPInsight or by the agent.

Before you start

• You need a paid plan. Agent access is a paid feature and it’s checked on every call, so a free workspace can’t connect. Check under Settings → Billing; if it says Free, upgrade first.
• You need an MCP-compatible client. Claude (claude.ai, Desktop and Code), ChatGPT, Codex, Cursor, VS Code, Gemini CLI, Windsurf, Cline and Antigravity all work — so does any client that speaks MCP over HTTP.
• Every client sees the same data. Claude and ChatGPT connected to the same workspace get the same tools, the same reports and the same numbers.
• Nothing gets installed on your WordPress site. WPInsight only ever reads the public WordPress.org directory.

Two ways to connect

Which one you use is decided by your client, not by preference.

Your client	Method
Claude Code, Codex, Cursor, VS Code, Gemini CLI, Windsurf, Cline, Antigravity	API key — below
claude.ai, Claude Desktop connector directory, ChatGPT	OAuth — see the last section
Codex, if you’d rather not paste a key	OAuth — codex mcp login, see the last section

Settings → Connect AI shows a ready-to-paste snippet for each client, with your key already filled in.

---

Step 1 · Create an API key

1. Sign in to WPInsight.
2. Go to Settings → Connect AI.
3. Under New API key, give it a name that says where the key will live — “Claude Code — work laptop” is a good name, “key1” is not. When you come to revoke something months later, the name is all you’ll have to go on.
4. Choose the access level. This sets a ceiling, not a grant:
   • Read only — the default, and the right choice to start. The agent can read everything and change nothing, ever.
   • Read & write — the key is still read-only when created. It only means you’re allowed to switch individual write tools on later.
5. Click Create key.

You will see the key once. WPInsight stores only a hash of it, so there is no way to show it again — if you lose it, revoke it and create another. It has the form wpi_live_ followed by a long random string. The examples below use the placeholder YOUR_WPINSIGHT_API_KEY — replace it with your own key:

YOUR_WPINSIGHT_API_KEY

The same panel shows ready-made configuration for each client with your key already filled in. Copy from there rather than retyping.

Step 2 · Check the key works

Before editing any config files, confirm the key reaches your workspace:

curl -s https://wpinsight.com/api/workspace/me \
  -H "Authorization: Bearer YOUR_WPINSIGHT_API_KEY"

You should see your workspace’s real name, plan and plugin count. If this errors, stop here — connecting a client won’t fix it. See Troubleshooting.

Step 3 · Connect your client

The server URL is always https://wpinsight.com/mcp.

Claude Code

claude mcp add --transport http wpinsight https://wpinsight.com/mcp \
  --header "Authorization: Bearer YOUR_WPINSIGHT_API_KEY"

Then confirm it registered with claude mcp list.

Codex — ~/.codex/config.toml

The Codex CLI, the Codex IDE extension and the ChatGPT desktop app all read this one file.

[mcp_servers.wpinsight]
url = "https://wpinsight.com/mcp"
http_headers = { "Authorization" = "Bearer YOUR_WPINSIGHT_API_KEY" }

To keep the key out of the file, use bearer_token_env_var = "WPINSIGHT_API_KEY" instead of http_headers and export WPINSIGHT_API_KEY in your shell. Check it with codex mcp list.

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "wpinsight": {
      "url": "https://wpinsight.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_WPINSIGHT_API_KEY" }
    }
  }
}

VS Code — .vscode/mcp.json

{
  "servers": {
    "wpinsight": {
      "type": "http",
      "url": "https://wpinsight.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_WPINSIGHT_API_KEY" }
    }
  }
}

Gemini CLI — ~/.gemini/settings.json

{
  "mcpServers": {
    "wpinsight": {
      "httpUrl": "https://wpinsight.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_WPINSIGHT_API_KEY" }
    }
  }
}

Note the key is httpUrl, not url — url means the older SSE transport.

Windsurf — ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "wpinsight": {
      "serverUrl": "https://wpinsight.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_WPINSIGHT_API_KEY" }
    }
  }
}

Windsurf calls it serverUrl. Press Refresh in its MCP panel afterwards.

Cline — cline_mcp_settings.json

Open it from Cline → MCP Servers → Configure.

{
  "mcpServers": {
    "wpinsight": {
      "type": "streamableHttp",
      "url": "https://wpinsight.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_WPINSIGHT_API_KEY" }
    }
  }
}

Claude Desktop (manual config) or any stdio-only client

Clients that can only launch local stdio servers need the standard mcp-remote shim in front:

{
  "mcpServers": {
    "wpinsight": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://wpinsight.com/mcp",
        "--header", "Authorization: Bearer YOUR_WPINSIGHT_API_KEY"
      ]
    }
  }
}

Step 4 · Ask something

Restart your client so it picks up the new server, then try:

“Which of my plugins needs attention first?”

“Compare my plugin with the top 3 for my main keyword.”

“Show me the biggest growth opportunities for this plugin.”

If the agent says it has no WPInsight tools available, it hasn’t loaded the server — restart the client fully rather than reloading the window.

---

What the agent can and can’t do

Every new key starts read-only, whichever access level you picked. The agent can read your plugins, keywords and their rank history, downloads, reviews, alerts and directory rankings, and generate reports.

It cannot:

• see any workspace other than yours
• touch billing, users, invites or workspace settings
• edit your WordPress.org listing, readme, or anything on wordpress.org
• change your data at all, unless you explicitly switch on a write tool

Turning on a write tool

Skip this unless you actually want an agent changing your data. In Settings → Connect AI, click Permissions on the key. You get one switch per write tool:

Tool	What it does	Reversible?
Track a plugin	Adds a plugin to the workspace	Yes — untrack it
Untrack a plugin	Deletes the plugin and all its rank and review history	No
Add / remove keywords	Adds keywords, or deletes them with their rank history	Removal: no
Manage alert rules	Creates, edits and deletes rules; a sweep emails the workspace owner	Rules yes, the email no
Refresh data now	Re-checks a plugin on demand	n/a

Each switch is independent, and changes take effect on the key’s next call. The two marked no discard history that cannot be recovered from anywhere — WordPress.org does not serve past ranks, so a deleted rank series is gone for good.

---

Connect Claude or ChatGPT (OAuth)

claude.ai, the Claude Desktop connector directory and ChatGPT won’t accept a pasted API key, so they use OAuth instead. There is nothing to copy — you sign in to WPInsight and approve.

Claude

1. Open Settings → Connectors → Add custom connector and enter https://wpinsight.com/mcp.
2. Claude sends you to WPInsight to sign in.
3. Approve the connection on the consent screen.

ChatGPT

1. Open Plugins → + → Add custom MCP server. On a Business or Enterprise workspace, an admin may need to allow custom MCP servers first.
2. Name it WPInsight, enter https://wpinsight.com/mcp as the server URL and pick OAuth for authentication. Leave the client ID and secret empty — ChatGPT registers itself.
3. Approve the connection on the WPInsight consent screen.

ChatGPT can then use WPInsight in a normal chat and in Deep Research, which reads your workspace through WPInsight’s search and fetch tools.

Codex (instead of a key)

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

The login opens your browser on the same consent screen.

You’ll see exactly which workspace is being connected before you approve. Connections made this way are reports only: they read and generate reports and can’t change anything. Revoke access any time from Settings → Connect AI.

---

Troubleshooting

What you see	What it means
401 Unauthorized	The key is wrong, revoked, or the header is malformed. It must be Authorization: Bearer wpi_live_….
403 or “feature not available”	The workspace is on the free plan. Agent access needs a paid plan.
Agent lists no WPInsight tools	The client hasn’t loaded the server. Restart it completely.
Only read tools appear	Expected — every key starts read-only. Enable specific write tools under Permissions.
ChatGPT or Claude asks you to reconnect	The connection was revoked, or WPInsight was disconnected from the workspace. Reconnect and approve again.
ChatGPT says the server has no usable tools	Your ChatGPT workspace limits custom servers to search-style connectors. WPInsight provides search and fetch for exactly this; if it still refuses, ask your ChatGPT admin to allow custom MCP servers.
A write tool is refused	The tool is off for that key, or the key was created as Read only and can never write.

Still stuck? Contact support with the name of the key and the client you’re connecting — never the key itself.