Integrations

Connect your AI agent (MCP)

6 min read

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. Verified: Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Codex, Antigravity, and claude.ai.
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, Cursor, VS Code, Windsurf, Codex, Antigravity	API key — below
claude.ai, Claude Desktop connector directory	OAuth — see the last section

Step 1 · Create an API key

Sign in to WPInsight.
Go to Settings → Connect AI.
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.
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.
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 looks like:

wpi_live_18O815xiRWIZIwWebKX_Cua6wjvoq_ReXHwn5pC0BoE

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

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

Then confirm it registered with claude mcp list.

Cursor — `~/.cursor/mcp.json`

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

VS Code — `.vscode/mcp.json`

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

Claude Desktop, Codex, or any stdio-only client

These speak stdio rather than HTTP, so they need the standard mcp-remote shim in front:

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

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.ai or Claude Desktop (OAuth)

claude.ai and the Claude Desktop connector directory won’t accept a pasted API key, so they use OAuth instead.

In Claude, add a custom connector with the URL https://wpinsight.com/mcp.
Claude sends you to WPInsight to sign in.
Approve the connection on the consent screen.

You’ll see exactly which workspace is being connected before you approve. 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.
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.