How OpenSEO MCP Server Integration Works with Claude Code and AI Agents

OpenSEO's MCP server exposes SEO capabilities as JSON-RPC tools that Claude Code and other MCP-compatible agents can call directly to retrieve live keyword metrics, SERP data, and Google Search Console stats without hard-coded API logic.

The every-app/open-seo repository ships with a built-in MCP (Model Context Protocol) server that transforms the platform's SEO toolkit into agent-callable functions. This integration allows AI systems to perform real-time keyword research, backlink analysis, and rank tracking by invoking structured tools rather than parsing raw HTML or managing multiple API credentials.

Core Architecture

The MCP server acts as a bridge between AI agents and OpenSEO's backend services, abstracting away third-party providers like DataForSEO and Google Search Console.

MCP Server Components

The implementation lives in src/server/mcp/server.ts, which orchestrates the server lifecycle and loads the complete tool set. This core module registers tool definitions, validates inputs against Zod schemas, and manages authentication flows.

The transport layer in src/server/mcp/transport.ts handles the JSON-RPC entry point. It parses incoming MCP requests from agents and dispatches them to the appropriate internal service handlers. Each SEO capability resides in its own file under src/server/mcp/tools/, including keyword.ts for keyword research, serp.ts for search results, and backlinks.ts for backlink data.

Response consistency is enforced through src/server/mcp/output-schemas.ts, which centralizes Zod definitions ensuring agents receive well-typed, predictable data structures.

Request Lifecycle

When Claude Code or another MCP client connects to OpenSEO, the interaction follows four steps:

1. Discovery – The client registers the MCP endpoint, typically hosted at https://mcp.openseo.com.
2. Authentication – The client authenticates via API key (handled in src/server/mcp/api-key-auth.ts) or OAuth for Google Search Console (handled in src/server/mcp/oauth-provider.ts).
3. Invocation – The agent calls a specific tool method (e.g., keywordResearch) with parameters.
4. Validation – The server executes the request against backend services, validates output using output-schemas.ts, and returns structured JSON.

Telemetry and usage tracking occur in src/server/mcp/instrumentation.ts, enabling billing and debugging without exposing sensitive data to the agent.

Claude Code Integration

Claude Code, built on the Opencode SDK, treats OpenSEO's MCP server as a native extension of its capabilities.

Opencode SDK Workflow

Under the hood, Claude Code initializes an MCP client that reads tool schemas directly from the server. The SDK auto-generates type-safe method signatures based on output-schemas.ts, eliminating manual payload construction.

import { OpenAI } from '@opencode-ai/sdk';

const client = new OpenAI({ mcpUrl: 'https://mcp.openseo.com' });
await client.authenticate({ apiKey: process.env.OPEN_SEO_API_KEY });

const kw = await client.mcp.call('keywordResearch', {
  query: 'best project management tools',
  country: 'US',
});

console.log('Keyword volume:', kw.searchVolume);

This approach decouples the AI model's reasoning chain from data source implementation details. Claude Code receives validated results and can immediately incorporate metrics like searchVolume or keywordDifficulty into its analysis.

Authentication Methods

OpenSEO supports multiple authentication strategies within the MCP layer:

• API Key Auth – Project-scoped keys defined in src/server/mcp/api-key-auth.ts suitable for automated agents.
• OAuth Provider – Google Search Console integration via src/server/mcp/oauth-provider.ts for accessing authenticated GSC data.

Tool Implementations and Capabilities

The MCP server exposes discrete SEO functions as individual tools, each wrapping specific backend logic.

Available SEO Tools

Located in src/server/mcp/tools/, the current toolset includes:

• keywordResearch – Retrieves search volume, CPC, and difficulty metrics from DataForSEO.
• serpLookup – Fetches real-time search engine results pages for any query and location.
• backlinks – Analyzes referring domains and anchor text distributions.
• rankTracking – Retrieves historical and current ranking positions for monitored keywords.
• googleSearchConsole – Pulls click, impression, and position data for verified properties.

Each tool implementation validates inputs, calls the appropriate internal service, and formats responses according to the centralized schemas.

Output Schema Validation

The src/server/mcp/output-schemas.ts file defines strict Zod schemas for every tool response. This guarantees that Claude Code receives consistent data shapes regardless of underlying third-party API changes. For example, a keyword research response always includes searchVolume, cpc, and keywordDifficulty as typed numeric fields.

Practical Usage Examples

Connect Claude Code to OpenSEO using three primary integration patterns.

Raw HTTP Request

For direct MCP JSON-RPC calls without an SDK:

curl -X POST https://mcp.openseo.com/jsonrpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPEN_SEO_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "keywordResearch",
    "params": { "query": "open source seo", "country": "US" }
}'

The response follows the Zod schema defined in output-schemas.ts:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "searchVolume": 1250,
    "cpc": 0.45,
    "keywordDifficulty": 32
  }
}

TypeScript SDK Implementation

For production applications using the Opencode SDK:

import { OpenAI } from '@opencode-ai/sdk';

const client = new OpenAI({ mcpUrl: 'https://mcp.openseo.com' });
await client.authenticate({ apiKey: process.env.OPEN_SEO_API_KEY });

const serp = await client.mcp.call('serpLookup', {
  query: 'open seo platform',
  location: 'us',
  page: 1,
});

console.log(serp.results.map(r => r.title));

Claude Code Prompt-Based Usage

Within a Claude Code session, reference the MCP endpoint directly:

You have access to an MCP server at https://mcp.openseo.com.
Run the tool `keywordResearch` with query "seo automation" and country "US".
Use the returned `searchVolume` to decide whether to recommend the keyword.

Claude Code automatically translates this instruction into an MCP JSON-RPC call, retrieves the validated data, and continues reasoning with the live metrics.

Summary

• OpenSEO's MCP server exposes SEO capabilities as JSON-RPC tools in src/server/mcp/server.ts, enabling AI agents to access live data without managing multiple API integrations.
• Claude Code integration relies on the Opencode SDK to discover and call tools with type-safe methods, authenticating via API keys or OAuth.
• Strict schema validation through src/server/mcp/output-schemas.ts ensures agents receive predictable, well-typed responses for keyword metrics, SERP data, and backlink analysis.
• Zero-setup connectivity allows any MCP-compatible client to connect to the hosted endpoint and immediately execute complex SEO workflows.

Frequently Asked Questions

What is MCP and why does OpenSEO use it?

MCP (Model Context Protocol) is a JSON-RPC-based standard that allows AI agents to discover and call external tools. OpenSEO implements MCP in src/server/mcp/server.ts to decouple AI reasoning from data retrieval, letting agents like Claude Code access live SEO metrics without hard-coding API logic or parsing HTML directly.

Do I need to write custom code to connect Claude Code to OpenSEO?

No. Claude Code, built on the Opencode SDK, automatically detects MCP endpoints and generates type-safe clients. You only need to provide the MCP URL (https://mcp.openseo.com) and authentication credentials. The SDK handles schema discovery and request formatting using the definitions in src/server/mcp/output-schemas.ts.

What authentication methods does the OpenSEO MCP server support?

The server supports API-key authentication via src/server/mcp/api-key-auth.ts for general access, and OAuth flows via src/server/mcp/oauth-provider.ts specifically for Google Search Console data. API keys are project-scoped and suitable for automated agent workflows.

Which SEO tools are available through the MCP server?

Available tools defined in src/server/mcp/tools/ include keyword research, SERP lookups, backlink analysis, rank tracking, and Google Search Console data access. Each tool wraps underlying providers like DataForSEO and exposes clean, schema-validated JSON-RPC methods that agents can invoke directly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}