How the OpenSEO MCP Server Exposes SEO Functionality to AI Agents

The OpenSEO MCP server exposes SEO functionality through a standards-based JSON-RPC 2.0 interface that wraps internal services in Model Context Protocol (MCP) tools, secured via OAuth 2.0 scopes or first-party self-hosted authentication contexts.

The OpenSEO platform (available at every-app/open-seo) provides AI agents with programmatic access to keyword research, SERP analysis, and backlink data through an MCP-compliant server architecture. This implementation converts traditional SEO services into callable MCP tools that large language models and autonomous agents can invoke via structured JSON-RPC requests over HTTP.

MCP Protocol Architecture

The MCP server implementation relies on the @modelcontextprotocol/sdk/server/mcp package to create a standards-compliant interface. According to the source code in src/server/mcp/transport.ts (lines 17-42), the server handles incoming requests at the /mcp endpoint through a structured flow:

1. Transport Layer: The HTTP transport module receives POST requests and validates pre-flight OPTIONS requests (which bypass authentication to support browser-based agents).
2. Context Resolution: The system resolves authentication via handleAuthenticatedOpenSeoMcpRequest (lines 50-58) for OAuth tokens or handleSelfHostedOpenSeoMcpRequest (lines 68-90) for first-party deployments.
3. Server Instantiation: The createOpenSeoMcpServer function instantiates an McpServer with OpenSEO-specific metadata (name, version, icons) and registers available tools.
4. Tool Execution: Registered MCP tools delegate to existing service layers (e.g., src/serverFunctions/keywords.ts, src/serverFunctions/lighthouse.ts) and return validated JSON-RPC responses.

Authentication and Security Controls

Access to the MCP endpoint is strictly controlled through OAuth 2.0 scopes defined in src/lib/oauth-resource.ts. The MCP_SCOPE constant is required for all authenticated requests.

The transport layer implements dual authentication paths in src/server/mcp/transport.ts:

• Cloud/Hosted Mode: Validated via handleAuthenticatedOpenSeoMcpRequest, which extracts MCP_AUTH_CONTEXT_PROP from the OAuth payload and verifies MCP_SCOPE presence.
• Self-Hosted Mode: Resolved via handleSelfHostedOpenSeoMcpRequest, which constructs a "local_noauth" admin context or validates Cloudflare Access JWTs, allowing the same tool suite to function without external OAuth providers.

The authentication context schema is strictly defined in src/server/mcp/context.ts (lines 22-48), ensuring that MCP tools receive a standardized auth payload regardless of the deployment mode.

Tool Registration and Instrumentation

Individual SEO capabilities are exposed through the registerOpenSeoMcpTools function, which wires each internal service as a callable MCP tool. The registration process occurs within createOpenSeoMcpServer and connects tools to implementations in src/server/mcp/tools/*.ts (e.g., keyword-research.ts, get-backlinks-profile.ts).

Every tool invocation is wrapped by instrumentMcpTool (src/server/mcp/instrumentation.ts, lines 23-119), which performs three critical functions:

• Logging: Captures usage metrics and sends telemetry to PostHog.
• Output Validation: Validates structured outputs against JSON schemas, reporting failures with MCP_OUTPUT_VALIDATION errors (lines 101-115).
• Error Handling: Catches service exceptions and converts them to JSON-RPC error objects.

Practical Integration for AI Agents

AI agents interact with the server using JSON-RPC 2.0 over HTTP POST. A compliant request targets the /mcp endpoint with a Bearer token containing MCP_SCOPE:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "keyword_research",
  "params": {
    "keyword": "best project management tools",
    "language_code": "en"
  }
}

The following TypeScript example demonstrates how an AI agent can invoke the keyword research tool:

// Node.js AI agent invoking OpenSEO keyword research
import fetch from "node-fetch";

const MCP_ENDPOINT = "https://app.openseo.so/mcp";
const MCP_TOKEN = "YOUR_OAUTH_BEARER_TOKEN_WITH_MCP_SCOPE";

async function keywordResearch(keyword: string) {
  const payload = {
    jsonrpc: "2.0",
    id: "agent-123",
    method: "keyword_research",
    params: { keyword, language_code: "en" },
  };

  const response = await fetch(MCP_ENDPOINT, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${MCP_TOKEN}`,
    },
    body: JSON.stringify(payload),
  });

  const json = await response.json();
  if (json.error) {
    throw new Error(`MCP error: ${json.error.message}`);
  }
  return json.result; // Returns search volume, CPC, difficulty metrics
}

keywordResearch("open source SEO tools").then(console.log);

For self-hosted deployments, agents may omit the Bearer token and instead rely on the platform's automatic context resolution via X-OpenSEO-Auth-Context headers or IP-based admin context.

Key Source Files and Responsibilities

The MCP implementation spans several critical files in the repository:

• src/server/mcp/transport.ts: HTTP transport, scope validation, and request routing to authentication handlers (lines 17-42, 50-90).
• src/server/mcp/context.ts: Definition of MCP_AUTH_CONTEXT_PROP schema and route constants (lines 22-48).
• src/server/mcp/server.ts: Factory function createOpenSeoMcpServer and tool registration orchestration.
• src/server/mcp/instrumentation.ts: Usage tracking, output validation, and error instrumentation logic (lines 23-119).
• src/server/mcp/tools/*.ts: Individual tool implementations mapping to SEO services.
• src/lib/oauth-resource.ts: OAuth scope definitions including MCP_SCOPE.
• src/middleware/ensure-user/*: Cloudflare Access JWT and local admin context resolution helpers.

Summary

• The OpenSEO MCP server exposes SEO functionality through the Model Context Protocol, enabling AI agents to perform keyword research, SERP lookups, and backlink analysis via JSON-RPC 2.0.
• Authentication is enforced through OAuth 2.0 MCP_SCOPE tokens in hosted environments, while self-hosted deployments utilize first-party admin contexts resolved through Cloudflare Access or local authentication.
• The architecture separates transport concerns (src/server/mcp/transport.ts) from tool logic (src/server/mcp/tools/), with comprehensive instrumentation and output validation handled by instrumentMcpTool.
• All tool outputs are validated against JSON schemas, with structured error reporting for validation failures or authorization issues.
• The /mcp endpoint accepts standard JSON-RPC requests and returns structured SEO data that AI agents can process programmatically.

Frequently Asked Questions

What protocol does the OpenSEO MCP server use to communicate with AI agents?

The server implements the Model Context Protocol (MCP) over JSON-RPC 2.0 via HTTP POST requests. Agents send structured JSON payloads specifying the tool method (e.g., keyword_research) and parameters, receiving JSON-RPC responses containingeither result data or error objects. This standardization allows any MCP-compliant client to integrate with OpenSEO without custom SDKs.

How does authentication differ between hosted and self-hosted MCP deployments?

Hosted deployments require Bearer tokens with the MCP_SCOPE OAuth scope, validated by handleAuthenticatedOpenSeoMcpRequest in src/server/mcp/transport.ts. Self-hosted deployments bypass external OAuth and instead use handleSelfHostedOpenSeoMcpRequest, which constructs an admin context from Cloudflare Access JWTs or "local_noauth" mode, allowing internal agents to call tools without token management while maintaining security boundaries.

Which OpenSEO services are available as MCP tools?

The server exposes the full SEO service suite, including keyword research (wrapping src/serverFunctions/keywords.ts), Lighthouse audits (src/serverFunctions/lighthouse.ts), SERP lookups, domain analysis, backlink profiling, and rank tracking. Each service is registered via registerOpenSeoMcpTools in src/server/mcp/server.ts and implements specific input/output schemas for type-safe AI agent interactions.

How does the server ensure output reliability and validation?

Every tool invocation passes through instrumentMcpTool (src/server/mcp/instrumentation.ts), which validates outputs against predefined JSON schemas before returning them to the client. Validation failures trigger MCP_OUTPUT_VALIDATION errors with detailed diagnostic information. Additionally, the instrumentation layer sends usage metrics to PostHog, enabling monitoring of tool performance and error rates in production environments.

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