How OpenSEO's MCP Server Integrates with AI Agents like Claude Code

OpenSEO's MCP server exposes SEO-specific tools through the Model Context Protocol, allowing AI agents such as Claude Code to authenticate via OAuth and invoke keyword research, SERP lookup, and backlink analysis through standardized JSON-RPC requests.

OpenSEO is an open-source SEO platform that makes its capabilities available to AI agents through a dedicated MCP (Model Context Protocol) server. This integration enables tools like Claude Code to perform complex SEO operations without requiring direct API integration. According to the every-app/open-seo source code, the MCP server architecture follows a clean three-layer design: server construction, transport handling, and context propagation.

MCP Server Architecture Overview

The OpenSEO MCP server is built on three core components that handle everything from tool registration to authentication and request routing.

Server Construction in server.ts

The entry point for the MCP server is src/server/mcp/server.ts, which instantiates an McpServer and registers the complete catalog of SEO tools.

// src/server/mcp/server.ts (conceptual structure)
// Lines 1-34 initialize the server with metadata:
// - name: "OpenSEO"
// - version from package.json
// - icons and usage instructions
// - tool registration for all SEO utilities

This file defines the service metadata—name, version, icons, and usage instructions—that agents display to users when discovering available capabilities.

Transport and Authentication Layer

The src/server/mcp/transport.ts file handles all HTTP communication between AI agents and the OpenSEO server. It supports two deployment modes with different authentication strategies.

Hosted Deployments with OAuth

For cloud-hosted instances, handleAuthenticatedOpenSeoMcpRequest validates OAuth tokens and enforces scope-based permissions:

// src/server/mcp/transport.ts#L45-L63
// Validates OAuth token, checks for 'MCP' scope
// Builds request handler with CORS enforcement
// Routes to MCP server after authentication

Self-Hosted Deployments

For local or private installations, handleSelfHostedOpenSeoMcpRequest supports Cloudflare Access or no-authentication contexts:

// src/server/mcp/transport.ts#L64-L86
// Resolves Cloudflare Access headers OR local context
// Creates McpProps object
// Returns shared request handler

Both paths use identical CORS header sets (MCP_CORS_HEADERS) and maintain backward compatibility with legacy JSON-RPC fallbacks for older MCP SDK versions.

Tool Context Propagation

Authentication data flows through src/server/mcp/context.ts, which defines the ToolAuthContext interface:

// src/server/mcp/context.ts#L6-L13
interface ToolAuthContext {
  userId: string;
  userEmail: string;
  organizationId: string;
  scopes: string[]; // Must include 'MCP' scope
}

This context is attached to every tool invocation, allowing individual SEO utilities to enforce fine-grained permissions based on the authenticated user.

How Claude Code Connects to OpenSEO

When Claude Code—or any MCP-compatible agent—wants to execute an OpenSEO tool, it uses the Agents SDK (agents/mcp/client). The interaction follows this sequence:

1. Client initialization with endpoint and OAuth bearer token
2. Tool discovery from server metadata
3. JSON-RPC request (or SSE stream in modern mode)
4. Server validation of token and scope
5. Tool execution with populated context
6. Structured response returned to agent

Example Agent-Side Invocation

// Claude Code — using the Agents SDK
import { createMcpClient } from "agents/mcp/client";

const client = createMcpClient({
  endpoint: "https://openseo.so/mcp",
  auth: {
    // OAuth token with 'MCP' scope
    bearerToken: "<access-token>",
  },
});

const result = await client.callTool("get_domain_overview", {
  domain: "example.com",
});

The client transmits a JSON-RPC payload with method: "get_domain_overview" and params: { domain: "example.com" }. The OpenSEO server validates the request, constructs a ToolContext from the OAuth token, and dispatches to getDomainOverviewTool in src/server/mcp/tools/get-domain-overview.ts.

Key Implementation Files

Component	File Path	Primary Responsibility
Server definition	src/server/mcp/server.ts	McpServer instantiation, tool registration, metadata
Transport & auth	src/server/mcp/transport.ts	HTTP handling, CORS, OAuth validation, deployment modes
Auth context	src/server/mcp/context.ts	ToolAuthContext interface, context builders
OAuth registration	src/server/mcp/oauth-registration.ts	MCP client registration, scope enforcement
Instrumentation	src/server/mcp/instrumentation.ts	Analytics wrapping, error reporting
Tool implementations	src/server/mcp/tools/*.ts	Individual SEO utilities (keyword research, SERP lookup, backlink analysis, etc.)

Deployment Considerations

Hosted mode requires proper OAuth configuration with the MCP scope granted. The oauth-registration.ts file handles client registration and ensures tokens include necessary permissions.

Self-hosted mode offers flexibility for private deployments. Administrators can configure Cloudflare Access for team authentication or run without authentication for local development.

Both modes share identical tool handlers and response formats, ensuring consistent behavior regardless of deployment type.

Summary

• OpenSEO's MCP server exposes SEO capabilities through the standardized Model Context Protocol, making tools discoverable and invocable by any MCP-compatible agent.

• Three-layer architecture separates concerns: server construction (server.ts), transport/auth handling (transport.ts), and context propagation (context.ts).

• Dual deployment support accommodates both cloud-hosted OAuth flows and self-hosted configurations through unified request handlers.

• Claude Code integration uses the Agents SDK to authenticate, discover tools, and invoke SEO operations via JSON-RPC with automatic context injection.

• Tool implementations reside in src/server/mcp/tools/ and receive fully populated ToolContext objects containing user identity and permissions.

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 structured JSON-RPC communication. MCP servers expose metadata about available capabilities, authentication requirements, and usage patterns. OpenSEO implements this protocol to make its SEO utilities accessible without requiring custom API integrations for each agent.

Do I need OAuth credentials to use OpenSEO with Claude Code?

For hosted deployments at openseo.so, yes—you need an OAuth token with the MCP scope. The handleAuthenticatedOpenSeoMcpRequest function in transport.ts validates this token before allowing any tool execution. For self-hosted deployments, you can configure Cloudflare Access or disable authentication entirely using handleSelfHostedOpenSeoMcpRequest.

What SEO tools are available through the MCP server?

According to the server registration in src/server/mcp/server.ts, OpenSEO exposes tools for keyword research, SERP lookup, backlink analysis, domain overview, and other SEO operations. Each tool has a dedicated implementation file in src/server/mcp/tools/ (e.g., get-domain-overview.ts) that receives the authenticated ToolContext and returns structured JSON responses.

Can I build my own agent that connects to OpenSEO's MCP server?

Yes—any client that speaks the Model Context Protocol can connect. The official Agents SDK (agents/mcp/client) provides the easiest path, but you can also construct raw JSON-RPC requests to the /mcp endpoint. You'll need to handle OAuth token acquisition for hosted deployments or configure compatible authentication for self-hosted instances, matching the transport layer expectations defined in src/server/mcp/transport.ts.

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