How AI Agents Query SEO Data Using OpenSEO's MCP Server: A Complete Guide

AI agents query SEO data through OpenSEO's Model Context Protocol (MCP) server by sending authenticated JSON-RPC 2.0 requests to the /mcp endpoint, which exposes domain overviews, keyword research, backlink profiles, and Google Search Console metrics as callable tools.

OpenSEO's MCP server provides a standardized interface for AI systems to access live SEO intelligence. The implementation follows the Model Context Protocol specification, enabling any HTTP-capable client—from Claude Code to custom Python scripts—to retrieve structured search data programmatically.

Setting Up MCP Server Authentication

Before querying data, agents must authenticate with the MCP scope (MCP_SCOPE). OpenSEO supports two authentication methods:

• OAuth tokens with the MCP scope included
• Personal API keys passed via the Authorization: Bearer header or x-api-key header

Users generate API keys through the OpenSEO web interface. All subsequent requests must include valid credentials.

The transport layer enforces this in src/server/mcp/transport.ts (lines 49-62), where scope validation rejects unauthorized requests:

// src/server/mcp/transport.ts
if (!result.data[MCP_AUTH_CONTEXT_PROP].scopes.includes(MCP_SCOPE)) {
  return new Response("MCP scope required", { status: 403 });
}

MCP Server Architecture and Tool Registration

The server instance is created in src/server/mcp/server.ts (lines 28-45), where each SEO tool registers its input schema, output schema, and handler function:

// src/server/mcp/server.ts
export function createOpenSeoMcpServer(authProps: McpProps) {
  const server = new McpServer({ name: "OpenSEO MCP", … });
  const register = <Input extends ToolSchema>(tool: OpenSeoToolDefinition<Input>) =>
    registerOpenSeoTool(server, tool, authProps);
  register(getDomainOverviewTool);   // ← domain metrics
  register(getBacklinksProfileTool); // ← link analysis
  register(researchKeywordsTool);    // ← keyword discovery
  register(getSearchConsolePerformanceTool); // ← GSC data
  // … additional tools
  return server;
}

This pattern ensures type-safe tool definitions with automatic validation of request parameters against declared schemas.

Querying SEO Data: The JSON-RPC Flow

AI agents interact with the MCP server through stateless HTTP POST requests to https://app.openseo.so/mcp. Each request follows the JSON-RPC 2.0 specification with four required fields:

Field	Description	Example
jsonrpc	Protocol version	"2.0"
method	Tool name to invoke	"get_domain_overview"
params	Tool-specific arguments	{"domain": "example.com"}
id	Request correlation identifier	1

The transport handler in src/server/mcp/transport.ts routes validated requests to the appropriate tool handler, executes the underlying database or third-party API call, and returns the structured response.

Available MCP Tools

According to web/content/docs/mcp.md, the server exposes these primary tools:

• get_domain_overview – Aggregate authority, traffic estimates, and rank distribution
• get_backlinks_profile – Referring domains, anchor text distribution, link velocity
• research_keywords – Search volume, difficulty scores, SERP features, related keywords
• get_search_console_performance – Clicks, impressions, CTR, and position data from Google Search Console
• get_serp_analysis – Real-time search result page structure and competitor positioning

Code Examples: Querying from Different Environments

Direct HTTP with curl

curl -X POST https://app.openseo.so/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer oseo_YOUR_KEY" \
  -d '{
        "jsonrpc":"2.0",
        "method":"get_domain_overview",
        "params":{"domain":"example.com"},
        "id":1
      }'

Node.js with native fetch

const response = await fetch('https://app.openseo.so/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer oseo_YOUR_KEY',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'research_keywords',
    params: { keyword: 'cloud hosting', language: 'en' },
    id: 42,
  }),
});

const result = await response.json();
console.log(result.result); // → array of keyword metrics

Python with requests

import requests, json

payload = {
    "jsonrpc": "2.0",
    "method": "get_backlinks_profile",
    "params": {"domain": "example.com"},
    "id": 7,
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer oseo_YOUR_KEY",
}
r = requests.post("https://app.openseo.so/mcp", headers=headers, data=json.dumps(payload))
print(r.json()["result"])

Connecting AI Coding Assistants

Claude Code (built-in MCP client)

claude mcp add --transport http --scope user openseo https://app.openseo.so/mcp \
  --header "Authorization: Bearer oseo_YOUR_KEY"

See steps 24-26 in web/content/docs/mcp.md for additional configuration options.

Cursor (via mcp.json)

{
  "mcpServers": {
    "openseo": {
      "url": "https://app.openseo.so/mcp",
      "headers": {
        "Authorization": "Bearer oseo_YOUR_KEY"
      }
    }
  }
}

Lines 45-52 of web/content/docs/mcp.md document the full Cursor configuration schema.

Response Format and Error Handling

Successful tool invocations return a JSON-RPC response with the result field containing typed output data. Errors propagate through standard JSON-RPC error objects with descriptive messages:

{
  "jsonrpc": "2.0",
  "result": {
    "domain": "example.com",
    "authority_score": 67,
    "organic_traffic": 125000,
    "backlinks_total": 45000
  },
  "id": 1
}

Because the server is stateless, clients must include complete context in each request. No session cookies or connection state persist between calls.

Key Implementation Files

File	Purpose
src/server/mcp/server.ts	Server instantiation and tool registration
src/server/mcp/transport.ts	HTTP routing, CORS, authentication, request forwarding
web/content/docs/mcp.md	Integration guides for Claude, Cursor, Codex, and direct API usage

Summary

• OpenSEO's MCP server exposes SEO tools through a standardized JSON-RPC interface at https://app.openseo.so/mcp
• Authentication requires the MCP scope via OAuth tokens or personal API keys (oseo_ prefix)
• Tool registration in src/server/mcp/server.ts provides type-safe, schema-validated endpoints for domain analysis, keyword research, backlink data, and Search Console metrics
• Any HTTP client can query the server—no special SDK required—making it compatible with Claude Code, Cursor, custom scripts, and direct API integration
• Stateless architecture ensures predictable, reproducible behavior across AI agent sessions

Frequently Asked Questions

What is MCP and why does OpenSEO use it?

The Model Context Protocol (MCP) is an open standard for exposing contextual tools to AI systems. OpenSEO implements MCP to allow any compatible client—Claude Code, Cursor, or custom implementations—to discover and invoke SEO analysis tools without proprietary SDKs. This standardization reduces integration friction and enables composable AI workflows.

How do I obtain an API key for MCP access?

Navigate to the OpenSEO web interface, access your account settings, and generate a personal API key with MCP scope. The key begins with oseo_ and should be treated as a secret. Pass it in the Authorization: Bearer header for all MCP requests, or configure it in your AI assistant's MCP settings.

Can I use the MCP server without Claude or Cursor?

Yes. The MCP server is a standard HTTP JSON-RPC service. Any environment capable of POST requests—including Python scripts, Node.js applications, Bash with curl, or browser-based fetch calls—can query SEO data directly. The protocol intentionally avoids vendor-specific dependencies.

What happens if my MCP request fails scope validation?

The transport layer in src/server/mcp/transport.ts returns HTTP 403 Forbidden with the message "MCP scope required" when authentication is missing or insufficient. Verify your API key is active, includes the MCP scope, and is formatted correctly in the Authorization header.

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