OpenLens

OpenLens MCP + Windsurf: Integration Guide

Add the OpenLens Model Context Protocol server to Windsurf via its mcp_config.json file. Windsurf does not yet speak remote HTTP MCP natively, so we route the connection through the mcp-remote stdio shim. From there, Windsurf can run visibility scans, fetch citations, and manage OpenLens projects alongside your code.

TL;DR

Server URLhttps://openlens.com/mcp
Transportstdio via mcp-remote shim
AuthOAuth 2.1 (browser flow)
Config file~/.codeium/windsurf/mcp_config.json

Add the server entry

Open ~/.codeium/windsurf/mcp_config.json (create it if missing) and paste:

{
  "mcpServers": {
    "openlens": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://openlens.com/mcp"]
    }
  }
}

The mcp-remote package bridges Windsurf's stdio transport to the remote HTTP server and handles the OAuth flow. It runs on demand via npx, so there is nothing to install ahead of time.

Restart Windsurf

Quit Windsurf and reopen it. Windsurf reads mcp_config.json on startup, so config changes only take effect after a restart.

Complete OAuth

The first time Windsurf invokes an OpenLens tool, the mcp-remote shim opens a browser tab for the Clerk OAuth handshake. Sign in with your OpenLens account and approve. The token is cached under ~/.mcp-auth/ and reused on every subsequent call.

Verify it works

In any Windsurf chat or Cascade workflow, ask:

“List my OpenLens projects.”

The agent should call list_projects and return at least one row. If the call stalls, see Troubleshooting below.

What you can do once connected

The OpenLens MCP server exposes ~40 tools across project setup, brands, topics, prompts, runs, visibility analytics, citations, workstreams, and scheduling. Useful prompts from Windsurf:

  • “Kick off a fresh scan for project Aurora across every active platform, then summarize the biggest changes versus last week.”
  • “Show me the top 20 cited sources for Aurora this month and tell me which deserve a guest post pitch.”
  • “Add three new topics under Aurora focused on integration questions and generate 4 prompts each.”
  • “Build a weekly Markdown report for Aurora I can drop into the team Slack.”

Troubleshooting

  • “Command not found: npx”: install Node.js (LTS) so that npx is on the path that Windsurf inherits. Restart Windsurf after installing.
  • OAuth tab does not open: kill the cached auth with rm -rf ~/.mcp-auth/ and trigger any OpenLens tool again.
  • Server shows as failed to start: open the Windsurf logs and look for the npx output. Outbound network egress to npm registry and openlens.com is required.
  • Anything else: email [email protected] with your Windsurf version and the exact error.

Related