How to Use the OpenSEO MCP Server for Programmatic AI Agent Access

The OpenSEO MCP server exposes all SEO tools—including keyword research, SERP analysis, backlink profiles, and rank tracking—as JSON-RPC endpoints that AI agents can invoke directly using the Model Context Protocol.

The every-app/open-seo repository ships with a built-in MCP (Model Context Protocol) server that enables programmatic AI agent access to live SEO data. By integrating with agents like Claude Code, Codex, or Cursor, you can automate keyword research and site audits without hallucinated data, leveraging real-time information from DataForSEO, Google Analytics, and Search Console.

Architecture of the OpenSEO MCP Server

The MCP server implementation follows a modular architecture divided into four core layers. Each layer handles a specific concern, from tool registration to request transport.

Server Definition (src/server/mcp/server.ts)

The createOpenSeoMcpServer function in src/server/mcp/server.ts instantiates the main McpServer and registers the complete tool set. This includes defining input/output schemas using Zod and mapping each tool name to its handler. The server advertises zero subscriptions (maxSubscriptions: 0) to maintain statelessness and prevent memory exhaustion in long-running isolates.

Transport Layer (src/server/mcp/transport.ts)

The transport layer handles HTTP request routing and protocol negotiation. It supports two operational modes: Modern deployments use the agents SDK createMcpHandler for JSON-RPC over Server-Sent Events (SSE), while Legacy mode accepts plain JSON-RPC POST requests for broader client compatibility. The handleAuthenticatedOpenSeoMcpRequest and handleSelfHostedOpenSeoMcpRequest functions manage these paths, performing CORS validation and injecting authentication context before dispatching to the MCP server.

Authentication Context (src/server/mcp/context.ts)

Before executing any tool, the server validates the request through createWorkersOAuthMcpProps in src/server/mcp/context.ts. This function extracts the userId, organizationId, and role from the OAuth token and verifies the token includes the MCP_SCOPE. The AuthRepository.ts module then verifies user membership and organization roles, ensuring multi-tenant isolation. The resulting McpProps object is injected into the request context for authorization checks.

OAuth Registration (src/server/mcp/oauth-registration.ts)

For public MCP clients like Claude that require Dynamic Client Registration, normalizeClientRegistrationRequest in src/server/mcp/oauth-registration.ts normalizes registration payloads and sets the appropriate token_endpoint_auth_method, enabling secure client secret issuance for AI agents.

Tool Implementations (src/server/mcp/tools/)

Individual SEO tools reside in src/server/mcp/tools/. For example, research-keywords.ts exports researchKeywordsTool, which validates inputs with Zod, calls the DataForSEO API, and returns structured keyword data. Each tool follows this pattern: schema validation → business logic → typed response.

Request Flow and State Management

When an AI agent sends a request to the OpenSEO MCP endpoint, the server processes it through a strict pipeline:

1. Origin Validation: validateLegacyRequest checks CORS headers and rejects unauthorized domains
2. Token Verification: The system extracts the Bearer token and confirms it contains the MCP scope via the OAuth repository
3. Server Instantiation: The transport layer calls createOpenSeoMcpServer to build a fresh McpServer instance loaded with all registered tools
4. JSON-RPC Dispatch: The request payload routes to the appropriate tool handler (e.g., research_keywords), Zod validates parameters, and the handler executes the underlying service call

Because the server is stateless, each request builds a new server instance, ensuring no session persistence and horizontal scalability.

Implementation Examples

Direct API Calls with cURL

For simple integrations or testing, invoke tools directly via JSON-RPC:

curl -X POST https://<your-openseo-domain>/mcp \
  -H "Authorization: Bearer <OAuth-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"research_keywords",
    "params":{
      "project_id":"proj_123",
      "seed_keyword":"best coffee maker",
      "language_code":"en"
    },
    "id":1
  }'

The request hits handleAuthenticatedOpenSeoMcpRequest, which validates the OAuth token, constructs the transport, and dispatches to the research_keywords tool defined in createOpenSeoMcpServer.

Node.js Client Using the MCP SDK

For TypeScript applications, use the official MCP client SDK:

import { createMcpClient } from "@modelcontextprotocol/client";

const client = await createMcpClient({
  url: "https://<your-openseo-domain>/mcp",
  token: "<OAuth-access-token>",
});

const result = await client.call("research_keywords", {
  project_id: "proj_123",
  seed_keyword: "best coffee maker",
  language_code: "en",
});

console.log(result);
// → { rows: [{ keyword: "...", volume: 1200, ... }], meta: { … } }

The SDK creates an McpHandler internally, ensuring request formatting matches the server’s expectations exactly.

Integrating with Claude Code

Claude Code and similar MCP-compatible agents can discover and invoke OpenSEO tools automatically:

User: "Claude, find keyword ideas for 'organic garden tools'"

Claude (via MCP):
  - Calls research_keywords on the OpenSEO MCP server
  - Receives structured keyword data
  - Returns: "Here are 50 related keywords with search volumes..."

Configure the agent with your endpoint URL (https://<your-openseo-domain>/mcp) and OAuth token via codex mcp login or equivalent CLI commands.

Self-Hosted Deployment with Cloudflare Access

For self-hosted instances using Cloudflare Access, implement the entrypoint in your Workers script:

import { handleSelfHostedOpenSeoMcpRequest } from "./src/server/mcp/transport";

export async function onRequest(context) {
  return handleSelfHostedOpenSeoMcpRequest(
    context.request,
    "cloudflare_access",
    context.env,
    context.ctx,
  );
}

This pattern appears in src/server.ts and handles the same validation and dispatch logic as the hosted version, deriving McpProps from Cloudflare Access headers rather than OAuth tokens.

Summary

• The OpenSEO MCP server exposes SEO functionality through JSON-RPC endpoints defined in src/server/mcp/server.ts
• Authentication requires an OAuth token with the MCP_SCOPE, validated in src/server/mcp/context.ts and verified against AuthRepository.ts
• The transport layer (src/server/mcp/transport.ts) supports both hosted and self-hosted deployment modes with CORS and origin validation, plus modern SSE and legacy POST protocols
• Dynamic Client Registration for public AI agents is handled by normalizeClientRegistrationRequest in src/server/mcp/oauth-registration.ts
• Tool handlers in src/server/mcp/tools/ provide concrete implementations for keyword research, backlink analysis, and rank tracking
• The architecture is stateless (maxSubscriptions: 0), ensuring scalability and preventing memory issues in serverless environments

Frequently Asked Questions

What authentication scope is required to access the OpenSEO MCP server?

The MCP server requires an OAuth access token with the MCP_SCOPE as defined in src/server/mcp/context.ts. The createWorkersOAuthMcpProps function validates this scope and extracts the user identity, while AuthRepository.ts verifies organizational membership before allowing tool execution.

Can I deploy the OpenSEO MCP server on my own infrastructure?

Yes. The repository includes handleSelfHostedOpenSeoMcpRequest in src/server/mcp/transport.ts for self-hosted deployments. This handler supports Cloudflare Access authentication or local development modes, allowing you to run the MCP server in private environments while maintaining the same JSON-RPC interface.

Which AI agents are compatible with the OpenSEO MCP server?

Any agent supporting the Model Context Protocol can connect, including Claude Code, Codex, Cursor, and OpenClaw. These agents use the MCP client SDK to discover available tools and invoke them with typed parameters, receiving structured SEO data instead of generating synthetic responses.

What SEO operations can AI agents perform through the MCP server?

Agents can access the complete OpenSEO tool suite: research_keywords for keyword discovery, get_backlinks_profile for link analysis, rank tracking functions, Google Search Console data retrieval, and Google Analytics reporting. Each tool is registered in createOpenSeoMcpServer with strict Zod schemas for input validation.

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