# How the OpenSEO MCP Server Exposes SEO Functionality to AI Agents

> Discover how the OpenSEO MCP server exposes SEO functionality via JSON-RPC 2.0. Learn about secure OAuth 2.0 integration for AI agents.

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

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/keywords.ts), [`src/serverFunctions/lighthouse.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/keyword-research.ts), [`get-backlinks-profile.ts`](https://github.com/every-app/open-seo/blob/main/get-backlinks-profile.ts)).

Every tool invocation is wrapped by **`instrumentMcpTool`** ([`src/server/mcp/instrumentation.ts`](https://github.com/every-app/open-seo/blob/main/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`:

```json
{
  "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:

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts)**: Definition of `MCP_AUTH_CONTEXT_PROP` schema and route constants (lines 22-48).
- **[`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts)**: Factory function `createOpenSeoMcpServer` and tool registration orchestration.
- **[`src/server/mcp/instrumentation.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/keywords.ts)), Lighthouse audits ([`src/serverFunctions/lighthouse.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.