What is the MCP server?

Surfaceable ships as a Model Context Protocol (MCP) server. This means you can use all 14 Surfaceable SEO tools directly inside Claude Code, Cursor, or any other MCP-compatible AI coding environment.

Instead of switching between your editor and a browser-based audit tool, you can ask Claude to analyse any URL without leaving your workflow.

Prerequisites

Node.js 18+ installed
Claude Code (or another MCP client)

Installation

Option 1 — Clone the repo (local build)

git clone https://github.com/surfaceable-io/surfaceable
cd surfaceable
npm install
npm run build:mcp

The MCP server binary will be at dist/mcp/server.js.

Option 2 — npx (no install required)

npx surfaceable-mcp

Configure Claude Code

Add the server to your Claude Code MCP configuration. Edit ~/.claude/claude.json:

{
  "mcpServers": {
    "surfaceable": {
      "command": "node",
      "args": ["/absolute/path/to/surfaceable/dist/mcp/server.js"],
      "env": {
        "SURFACEABLE_API_KEY": "sk_live_your_key_here",
        "GOOGLE_API_KEY": "your_google_api_key_here"
      }
    }
  }
}

Then restart Claude Code. You should see "surfaceable" appear in the connected MCP servers list.

Environment variables

Variable	Required	Purpose
`SURFACEABLE_API_KEY`	Optional	Links the MCP server to your Surfaceable account. Get yours from Settings → API Keys in the dashboard.
`GOOGLE_API_KEY`	Optional	Enables Core Web Vitals data via PageSpeed Insights API. Without it, `check_vitals` returns simulated data.

Getting your Surfaceable API key

Log in to your Surfaceable dashboard
Go to Settings
Scroll to API Keys
Click Generate key — the key is shown once only, so copy it immediately
Paste it as SURFACEABLE_API_KEY in your MCP config

The MCP server works without a key in standalone mode. Providing a key connects it to your account and will enable plan-based features as they are added.

Get a free Google API key from Google Cloud Console with the PageSpeed Insights API enabled.

Verify it's working

In Claude Code, try:

"Use the surfaceable MCP server to run a page_seo check on example.com"

You should see Claude call the page_seo tool and return a structured audit result.

Updating

If you installed via the repo, pull the latest changes and rebuild:

git pull
npm run build:mcp

Restart Claude Code after rebuilding.