# How OpenSEO's MCP Server Facilitates AI Agent Integration

> OpenSEO's MCP server integrates AI agents like Claude and ChatGPT, offering direct access to SEO tools via JSON-RPC and OAuth for seamless keyword research and SERP retrieval.

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

---

**OpenSEO's MCP server exposes SEO-focused tools as JSON-RPC endpoints, allowing AI agents like Claude and ChatGPT to authenticate via OAuth and execute functions such as keyword research and SERP retrieval directly from their prompts.**

The `every-app/open-seo` repository implements a **Model Context Protocol (MCP)** server that transforms OpenSEO's backend services into a standardized interface for AI agent integration. This architecture enables any MCP-compatible agent to discover, authenticate, and invoke SEO tools programmatically while respecting user privacy and billing boundaries.

## Core Architecture Components

### Server Initialization in `createOpenSeoMcpServer`

The entry point for AI agent integration resides in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts). The `createOpenSeoMcpServer` function instantiates an `McpServer` from the `@modelcontextprotocol/server` package and registers all available SEO tools. This function exposes server metadata—including name, version, and tool descriptions—that AI agent SDKs consume during discovery.

The server aggregates tools across multiple domains: backlink analysis, SERP retrieval, Google Analytics integration, Search Console data, and rank tracking. Each tool registration uses a helper `register` function that wraps handlers with instrumentation and normalizes input/output schemas via **Zod** validation.

### Transport Layer and Request Routing

Incoming AI agent requests are handled by two primary transport functions in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts):

- **`handleAuthenticatedOpenSeoMcpRequest`** – Processes hosted deployments with Cloudflare OAuth validation
- **`handleSelfHostedOpenSeoMcpRequest`** – Handles self-hosted installations with alternative authentication flows

These functions validate the `Authorization` header, enforce the required `MCP` scope (defined in [`src/lib/oauth-resource.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/oauth-resource.ts)), apply CORS policies, and route valid requests to fresh `McpServer` instances. The transport supports both modern JSON-RPC via `createMcpHandler` and legacy JSON-RPC protocols.

### Context Builder (`createMcpToolContext`)

Before executing any tool, [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts) constructs a uniform `ToolContext` object. The `createMcpToolContext` function transforms Cloudflare OAuth context into an agent-visible context containing the authenticated user's ID, email, organization, and authorized scopes. This context injection ensures that tool handlers can access user-specific project memory and billing data securely.

### Tool Registration and Schema Validation

Each SEO tool is registered through the `register` helper in [`server.ts`](https://github.com/every-app/open-seo/blob/main/server.ts), which:

1. Associates the tool name with its handler function
2. Applies Zod schemas for input validation
3. Wraps execution with error handling and logging

Tools cover extensive SEO workflows including domain overview retrieval, backlink analysis, keyword research, and Google Search Console data access.

### OAuth Scope Enforcement

Security relies on the `hostedWorkersOAuthMcpPropsSchema` defined in [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts). Every incoming request must present an OAuth token containing the `MCP` scope. Missing or invalid scopes trigger an immediate **403 Forbidden** response, preventing unauthorized agent access to private SEO data.

## AI Agent Request Flow

The integration follows a strict seven-step sequence to ensure secure, isolated execution:

1. **Discovery** – The AI agent SDK queries the `/mcp` endpoint to retrieve server metadata, version, and the catalog of available tools from `createOpenSeoMcpServer`.
2. **Authentication** – The agent obtains an access token with the `MCP` scope through Cloudflare Workers OAuth, sending it in the `Authorization: Bearer <token>` header.
3. **Request Receipt** – The transport layer (`handleAuthenticatedOpenSeoMcpRequest` or `handleSelfHostedOpenSeoMcpRequest`) validates the token, checks the `MCP` scope, and applies CORS headers.
4. **Server Instantiation** – A fresh `McpServer` instance is created for the request, ensuring complete state isolation between concurrent agent sessions.
5. **JSON-RPC Dispatch** – The `WebStandardStreamableHTTPServerTransport` parses the JSON-RPC 2.0 payload, validates inputs against Zod schemas, and routes to the appropriate tool handler.
6. **Context Injection** – `createMcpToolContext` injects the authenticated user's profile into the handler, enabling secure access to personalized SEO data.
7. **Response Serialization** – The tool result is serialized into JSON-RPC format and returned to the agent SDK for presentation or further processing.

## Authenticated Tool Invocation Example

Below is a complete HTTP request that an AI agent generates to fetch domain overview data through the MCP interface:

```http
POST /mcp HTTP/1.1
Host: api.openseo.so
Authorization: Bearer <access-token-with-MCP-scope>
Content-Type: application/json
Accept: application/json

{
  "jsonrpc": "2.0",
  "method": "get_domain_overview",
  "params": {
    "domain": "example.com"
  },
  "id": 1
}

```

The `get_domain_overview` method corresponds to the `getDomainOverviewTool` registered in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) at line 63. The handler executes within a `ToolContext` containing the user's organizational data, returning a structured response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "domain": "example.com",
    "organicSearchTraffic": 1245,
    "backlinksCount": 342,
    "topKeywords": ["seo tools", "rank tracking", "backlink analysis"]
  },
  "id": 1
}

```

## Key Source Files for AI Integration

Implementing custom AI agent integrations requires familiarity with these specific source files:

- **[`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts)** – Defines `createOpenSeoMcpServer`, registers all SEO tools, and configures server metadata for agent discovery
- **[`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts)** – Implements `handleAuthenticatedOpenSeoMcpRequest` and authentication routing logic
- **[`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts)** – Contains `createMcpToolContext` for OAuth-to-context mapping and scope enforcement
- **`src/server/mcp/tools/`** – Directory containing individual tool implementations (e.g., [`get-domain-overview.ts`](https://github.com/every-app/open-seo/blob/main/get-domain-overview.ts), [`search-console-tools.ts`](https://github.com/every-app/open-seo/blob/main/search-console-tools.ts))
- **[`src/lib/oauth-resource.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/oauth-resource.ts)** – Defines the `MCP_SCOPE` constant used for permission validation
- **[`src/server/mcp/urls.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/urls.ts)** – Generates dashboard URLs included in tool responses for human-readable references

## Summary

- OpenSEO's MCP server exposes SEO functionality through standardized JSON-RPC endpoints defined in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts).
- AI agents authenticate via OAuth tokens containing the `MCP` scope, enforced by transport handlers in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts).
- The `createMcpToolContext` function in [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts) securely injects user identity into tool handlers, enabling personalized data access.
- Tool registration combines Zod schema validation with automatic instrumentation, supporting domains, backlinks, SERP data, and Google Search Console operations.
- Both hosted (`handleAuthenticatedOpenSeoMcpRequest`) and self-hosted (`handleSelfHostedOpenSeoMcpRequest`) deployment models are supported for flexible AI agent integration.

## Frequently Asked Questions

### What is the Model Context Protocol (MCP)?

The Model Context Protocol is a standardized interface that allows AI agents to discover and invoke external tools through JSON-RPC endpoints. OpenSEO implements an MCP server that translates agent requests into SEO-specific function calls, enabling Claude, ChatGPT, and custom agents to access real-time ranking data and analytics programmatically.

### How does OpenSEO authenticate AI agent requests?

Authentication uses OAuth 2.0 via Cloudflare Workers. The AI agent must obtain an access token that includes the `MCP` scope defined in [`src/lib/oauth-resource.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/oauth-resource.ts). The transport layer in [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) validates this token on every request, rejecting unauthorized calls with a 403 Forbidden status before they reach tool handlers.

### What SEO functions can AI agents access through the MCP server?

According to the tool registrations in [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts), AI agents can execute keyword research, retrieve SERP results, analyze backlink profiles, fetch Google Analytics data, access Google Search Console metrics, and track rank positions. Each function is available as a JSON-RPC method with validated input schemas.

### Can I self-host the OpenSEO MCP server?

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) specifically for self-hosted deployments. This handler bypasses Cloudflare-specific OAuth flows while maintaining the same JSON-RPC interface and tool availability, allowing you to run the MCP server on your own infrastructure for private AI agent integration.