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

> Discover how OpenSEO's MCP server integration empowers AI agents like Claude Code to access real-time SEO data directly, eliminating hard-coded API logic.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: internals
- Published: 2026-08-19

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/keyword.ts) for keyword research, [`serp.ts`](https://github.com/every-app/open-seo/blob/main/serp.ts) for search results, and [`backlinks.ts`](https://github.com/every-app/open-seo/blob/main/backlinks.ts) for backlink data.

Response consistency is enforced through [`src/server/mcp/output-schemas.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/api-key-auth.ts)) or OAuth for Google Search Console (handled in [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/output-schemas.ts), and returns structured JSON.

Telemetry and usage tracking occur in [`src/server/mcp/instrumentation.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/output-schemas.ts), eliminating manual payload construction.

```typescript
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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/api-key-auth.ts) suitable for automated agents.
- **OAuth Provider** – Google Search Console integration via [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

```bash
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`](https://github.com/every-app/open-seo/blob/main/output-schemas.ts):

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

```

### TypeScript SDK Implementation

For production applications using the Opencode SDK:

```typescript
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/api-key-auth.ts) for general access, and OAuth flows via [`src/server/mcp/oauth-provider.ts`](https://github.com/every-app/open-seo/blob/main/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.