Model Context Protocol

SV MCP

A FastMCP server that exposes every SV API and CLI tool natively to AI agents — Claude Desktop, Claude Code, Cursor, and any MCP-capable host. Built directly on the sv-cli core library: no duplicated resolver, auth, or async-task logic.

Get Free API Key →

Tools exposed

FastMCP

Server framework

OAuth

2.1 auth

HTTP

Transport

One shared core, three interfaces. sv-cli, sv-mcp, and direct HTTP all resolve enums, manage auth, and handle async task polling through the same underlying library. A fix or new tool added to sv-cli is automatically available through the MCP server and the REST API.

01How it works

sv-mcp is a FastMCP server that wraps the sv-cli core library. It exposes each of the 16 SV API tools as a named MCP tool. When an AI agent calls a tool, the MCP server delegates to the same resolver, auth stack, and async-task loop used by the CLI — so behaviour is identical whether you call sv seogpt generate from a terminal or invoke the seogpt_generate MCP tool from Claude Desktop.

Async tools (GEO Audit, SEO GPT 2, SEO Strategist, SEO Mapping) return a task ID by default. If you ask the agent to wait for the result, sv-mcp polls internally until complete and returns the finished output. Once wait mode is triggered in a session, subsequent async calls in that session also wait automatically.

sv-mcp architecture

# The MCP server sits on top of sv-cli core:
#
#  Claude Desktop / Claude Code / Cursor
#       ↓  MCP protocol (SSE)
#  sv-mcp  (FastMCP server)           ←  you are here
#       ↓  sv-cli core library
#  SV REST API  (ai.seovendor.co/api)
#
# Every MCP tool call:
# 1. FastMCP receives the JSON-RPC tool call
# 2. sv-cli core resolves enums + validates fields
# 3. Async tools are polled internally until done
# 4. Result returned to the MCP host as structured JSON

02Connect to Claude.ai

URL-only setup. When registering via the Claude.ai custom connector UI, you only need the base URL. FastMCP mounts the MCP protocol endpoint there; OAuth callback and discovery routes are also served on this domain but you do not reference them directly.

claude.ai connector URL

# In Claude.ai → Settings → Integrations → Add custom integration

Connector URL:   https://mcp.seovendor.co

# That’s it. Claude handles the OAuth 2.1 flow automatically.
# Your SV API key is bound during the OAuth handshake —
# you do not pass it as a parameter on every call.

03Connect to Claude Desktop

Add sv-mcp to your Claude Desktop config file. Restart Claude Desktop after saving.

claude_desktop_config.json

{
  "mcpServers": {
    "sv-mcp": {
      "url": "https://mcp.seovendor.co",
      "transport": "http"
    }
  }
}

with env key

# ~/.config/claude/claude_desktop_config.json
# (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json)

# Or use an environment-variable key instead:
{
  "mcpServers": {
    "sv-mcp": {
      "url": "https://mcp.seovendor.co",
      "transport": "http",
      "env": {
        "SV_API_KEY": "your-key-here"
      }
    }
  }
}

04Connect to Claude Code

Add sv-mcp as a remote server from the terminal, or commit a .claude/mcp.json to your project so every collaborator gets it automatically.

claude mcp add

# Add via Claude Code CLI
claude mcp add sv-mcp --transport http https://mcp.seovendor.co

# Verify it registered
claude mcp list

# Or add to your project’s .claude/mcp.json:
{
  "servers": [
    {
      "name": "sv-mcp",
      "url": "https://mcp.seovendor.co",
      "transport": "http"
    }
  ]
}

05Other MCP hosts

Any MCP-compatible host that supports HTTP transport can connect to sv-mcp using the same base URL.

Host	Where to add	Value
Cursor	Settings → MCP Servers → Add Server → HTTP	`https://mcp.seovendor.co`
Windsurf	Settings → MCP → Add	`https://mcp.seovendor.co`
Cline / Roo	MCP Settings → Remote Server	`https://mcp.seovendor.co`, transport: http
Continue	config.json `mcpServers` array	url: `https://mcp.seovendor.co`, transport: `http`
Custom host	Any MCP 1.x SDK	HTTP transport, base URL `https://mcp.seovendor.co`

06Available tools

All 16 SV API tools are exposed as MCP tools. Async tools return a task ID by default. The agent can request to wait for completion, after which sv-mcp polls internally. Once wait mode is active in a session, subsequent async tool calls in that session also wait until finished.

MCP tool name	API endpoint	Description
seogpt_generate	SEO GPT	Generate SEO and GEO content across 300+ types.
seogpt2_create_task	SEO GPT 2	Produce long-form SEO articles. Async — returns task ID by default; waits if session is in wait mode.
content_transformer_rewrite	Content Transformer	Rewrite content to a new format, tone, or length.
seo_image_generate	SEO Image AI	Generate SEO-optimized images from a keyword.
better_keywords_research	Better Keywords AI	Keyword research with volume, CPC, and intent.
insight_igniter_entities	Insight Igniter	Extract SEO and GEO entities from a URL.
topical_authority_topics	Topical Authority	Generate topical authority article plans.
core_analysis_analyze	CORE Analysis	Analyze a page against SEO competitors.
preliminary_audit_analyze	Preliminary Audit	Run a technical SEO and GEO health check.
geo_audit_create_task	GEO Audit	Audit generative engine visibility. Async — returns task ID by default; waits if session is in wait mode.
seogpt_compare_create_task	SEO Strategist	Get strategic SEO guidance. Async — returns task ID by default; waits if session is in wait mode.
seo_mapping_create_task	SEO Mapping	Build an SEO map for a site. Async — returns task ID by default; waits if session is in wait mode.
ranklens_rank	RankLens	AI brand visibility report against competitors.
content_quality_analyze	Content Quality	Score HCU and E-E-A-T quality for a URL.
top_competitors_analyze	Top Competitors	Return the top 10 ranking competitor URLs.
marketplace_services_search	Marketplace Services	Search the SV marketplace for services and packages.

07Authentication

sv-mcp uses OAuth 2.1 for all hosted connections. You authenticate once through your SV account — no API key configuration required in the MCP host. The flow below happens automatically when you click Connect.

Step	What happens
1. Connect	You click Connect in your MCP host (Claude, Cursor, etc.). The host opens the SV OAuth endpoint.
2. Consent	SV presents an OAuth consent screen. You accept the requested permissions.
3. Login	You log in with your SV account credentials on the SV OAuth login page.
4. Redirect	On success, SV redirects back to the MCP host with a short-lived authorization code. The host is now Connected.
5. Token exchange	sv-mcp exchanges the authorization code for a short-lived session token. This token never leaves the server.
6. API key resolution	Before each API call, sv-mcp securely exchanges the session token for your SV API key server-side. The API key is never exposed to the MCP host or the AI model.
7. In-memory cache	The resolved API key is held in server memory for 5 minutes, then discarded. sv-mcp re-resolves it on demand when needed again.

Your API key is never exposed. The OAuth flow keeps your SV API key entirely server-side. The MCP host (Claude, Cursor, etc.) and the AI model see only tool results — the key is resolved in memory by sv-mcp and discarded after 5 minutes.

08sv-cli vs REST API vs sv-mcp

All three interfaces reach the same 16 tools through the same core library. Choose based on context.

Interface	sv-cli (terminal)	SV REST API (HTTP)	sv-mcp (MCP)
Who uses it	Humans, shell scripts, CI	Any HTTP client	AI agents (MCP hosts)
Auth	`SV_API_KEY` env or profile	`k` in JSON body	OAuth 2.1 or env var
Async handling	`--wait` flag or manual poll	3-step: createTask → poll → getResult	Returns task ID by default; blocks when session is in wait mode
Enum resolution	Fuzzy + strict modes	Raw integers / strings	sv-cli core (same)
Output format	table, csv, json, markdown…	JSON envelope	Structured JSON to host
Underlying core	sv-cli library	N/A	sv-cli library (shared)

←SV CLI First endpoint →SEO GPT

SV API

Overview SV CLI SV MCP API Home GitHub seovendor.co