How OpenSEO's MCP Server Facilitates AI Agent Integration

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. 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:

• 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), 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 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, 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. 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:

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 at line 63. The handler executes within a ToolContext containing the user's organizational data, returning a structured response:

{
  "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 – Defines createOpenSeoMcpServer, registers all SEO tools, and configures server metadata for agent discovery
• src/server/mcp/transport.ts – Implements handleAuthenticatedOpenSeoMcpRequest and authentication routing logic
• 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, search-console-tools.ts)
• src/lib/oauth-resource.ts – Defines the MCP_SCOPE constant used for permission validation
• 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.
• AI agents authenticate via OAuth tokens containing the MCP scope, enforced by transport handlers in src/server/mcp/transport.ts.
• The createMcpToolContext function in 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. The transport layer in 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, 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 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.

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