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

Open SEO's MCP server exposes a Model Context Protocol (MCP) interface that Claude Code and other AI agents use to execute SEO tools through standardized JSON-RPC calls with OAuth-authenticated permissions.

The Open SEO repository implements a complete MCP server architecture that bridges AI agents with professional SEO capabilities. This integration enables Claude Code and similar systems to perform keyword research, SERP analysis, and backlink lookups without exposing internal API complexities to the agent.

MCP Server Architecture Overview

The integration relies on three coordinated layers: server construction, transport handling, and context propagation. Each layer isolates concerns to maintain clean separation between authentication, communication, and business logic.

Server Construction Layer

In src/server/mcp/server.ts, the createOpenSeoMcpServer function instantiates an McpServer object, registers the full catalog of SEO tools, and defines service metadata including name, version, icons, and usage instructions. This file serves as the central registry where all tool handlers are bound to their MCP-exposed names.

The server exports structured metadata that AI agents consume to discover available capabilities. When Claude Code initializes its MCP client, it retrieves this schema to understand which tools it can invoke and what parameters each requires.

Transport and Authentication Layer

The src/server/mcp/transport.ts file manages HTTP communication and security validation. It provides two distinct authentication paths depending on deployment mode:

Hosted Deployments: The handleAuthenticatedOpenSeoMcpRequest function validates OAuth tokens, enforces the required MCP scope, and constructs a request handler with CORS headers. This path targets the managed Open SEO cloud service at openseo.so.

Self-Hosted Deployments: The handleSelfHostedOpenSeoMcpRequest function resolves authentication through Cloudflare Access or allows local no-auth contexts for development. Both paths produce identical McpProps objects that downstream handlers consume consistently.

Both transport modes share the MCP_CORS_HEADERS constant and include legacy JSON-RPC fallback support for agents using older MCP SDK versions.

Tool Context Propagation Layer

The src/server/mcp/context.ts file defines the ToolAuthContext interface and provides utilities to build ToolContext objects for each invocation. The context contains:

• userId — authenticated user identifier
• userEmail — contact address for audit trails
• organizationId — multi-tenant isolation key
• scopes — granted permission set from OAuth token

This context flows into every tool handler, enabling fine-grained authorization within SEO operations.

Integration Flow for Claude Code

When Claude Code executes an Open SEO tool, the interaction follows this sequence:

1. Client Initialization — Claude's Agents SDK (agents/mcp/client) creates an MCP client pointing to https://openseo.so/mcp with a bearer token containing the MCP scope.

2. Request Formation — The SDK serializes tool calls into JSON-RPC payloads. For example, requesting domain metrics generates:

// Conceptual Claude-side implementation
import { createMcpClient } from "agents/mcp/client";

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

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

3. Transport Processing — The /mcp endpoint receives the request, validates the OAuth token through handleAuthenticatedOpenSeoMcpRequest, and constructs a ToolContext from token claims.

4. Tool Execution — The MCP server routes to getDomainOverviewTool in src/server/mcp/tools/get-domain-overview.ts, passing the populated context for authorization checks.

5. Response Return — Structured JSON results flow back through the transport layer, where the SDK surfaces them to Claude's LLM for interpretation and user presentation.

Security and Permission Model

The Open SEO MCP server enforces security through OAuth 2.0 scopes with specific design choices:

• Scope Isolation — The dedicated MCP scope separates AI agent access from other Open SEO API consumers, limiting blast radius if tokens leak.

• Context-Bound Authorization — Each tool handler receives complete auth context, allowing dynamic permission enforcement based on organization tiers or feature flags.

• Self-Host Flexibility — Cloudflare Access integration enables enterprise deployments to leverage existing identity providers while maintaining the same MCP protocol surface.

Instrumentation and Observability

The src/server/mcp/instrumentation.ts file wraps tool handlers to capture execution metrics and error traces. This enables operational monitoring of:

• Tool call frequency and latency distributions
• Authentication failure patterns
• Error rates by tool and user segment

Analytics flow through the same transport infrastructure without exposing instrumentation details to AI agent clients.

Key Implementation Files

Component	File Path	Responsibility
Server definition	src/server/mcp/server.ts	McpServer instantiation, tool registration, metadata supply
Transport layer	src/server/mcp/transport.ts	HTTP handling, CORS, OAuth validation, hosted/self-hosted routing
Context management	src/server/mcp/context.ts	ToolAuthContext definition, ToolContext construction
Tool implementations	src/server/mcp/tools/*.ts	Individual SEO utilities (domain overview, keyword research, etc.)
OAuth registration	src/server/mcp/oauth-registration.ts	MCP client registration with scope negotiation
Instrumentation	src/server/mcp/instrumentation.ts	Handler wrapping for analytics and error reporting

Summary

• Open SEO's MCP server exposes SEO tools through a standards-compliant Model Context Protocol interface that any MCP-compatible agent can consume.

• Three-layer architecture separates server construction (server.ts), transport handling (transport.ts), and context propagation (context.ts) for maintainable, secure integration.

• Dual deployment modes support both hosted OAuth flow and self-hosted Cloudflare Access configurations without protocol changes.

• OAuth scope isolation via the dedicated MCP scope protects against cross-service token misuse.

• Automatic context propagation ensures every tool handler receives authenticated user identity, organization membership, and granted permissions.

Frequently Asked Questions

What MCP version does Open SEO's server implement?

Open SEO targets the modern MCP specification with Server-Sent Events (SSE) streaming as the primary transport, while maintaining backward compatibility through legacy JSON-RPC fallbacks in src/server/mcp/transport.ts for agents using older SDK versions.

Can I run Open SEO's MCP server without OAuth for local development?

Yes. The handleSelfHostedOpenSeoMcpRequest path in transport.ts supports local no-auth contexts when NODE_ENV indicates development mode, enabling rapid iteration without token infrastructure.

How does Claude Code discover available Open SEO tools?

During MCP client initialization, Claude retrieves tool metadata from the McpServer instance created in server.ts. This schema includes tool names, parameter specifications, and human-readable descriptions that Claude's LLM uses to generate appropriate function calls.

What SEO operations can AI agents perform through this integration?

Agents can execute the full tool catalog registered in server.ts, which includes domain overview analysis, keyword research, SERP position tracking, backlink profiling, and technical SEO audits—each implemented as separate handlers in src/server/mcp/tools/.

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