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

> Learn to programmatically access SEO tools like keyword research and rank tracking with the OpenSEO MCP server. Integrate AI agents directly for powerful insights.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-09-10

---

**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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts))

The `createOpenSeoMcpServer` function in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts))

Before executing any tool, the server validates the request through `createWorkersOAuthMcpProps` in [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

```bash
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:

```typescript
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:

```typescript
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts)
- **Authentication** requires an OAuth token with the `MCP_SCOPE`, validated in [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts) and verified against [`AuthRepository.ts`](https://github.com/every-app/open-seo/blob/main/AuthRepository.ts)
- The **transport layer** ([`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts). The `createWorkersOAuthMcpProps` function validates this scope and extracts the user identity, while [`AuthRepository.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.