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

> Discover how OpenSEO's MCP server integrates with AI agents like Claude Code. Authenticate via OAuth and access SEO tools through JSON-RPC for keyword research and backlink analysis.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: integration-guide
- Published: 2026-08-18

---

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

The entry point for the MCP server is [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts), which instantiates an `McpServer` and registers the complete catalog of SEO tools.

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/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:

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

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts), which defines the `ToolAuthContext` interface:

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

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

## Key Implementation Files

| Component | File Path | Primary Responsibility |
|-----------|-----------|----------------------|
| **Server definition** | [`src/server/mcp/server.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/server.ts) | `McpServer` instantiation, tool registration, metadata |
| **Transport & auth** | [`src/server/mcp/transport.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts) | HTTP handling, CORS, OAuth validation, deployment modes |
| **Auth context** | [`src/server/mcp/context.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/context.ts) | `ToolAuthContext` interface, context builders |
| **OAuth registration** | [`src/server/mcp/oauth-registration.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/oauth-registration.ts) | MCP client registration, scope enforcement |
| **Instrumentation** | [`src/server/mcp/instrumentation.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/server.ts)), transport/auth handling ([`transport.ts`](https://github.com/every-app/open-seo/blob/main/transport.ts)), and context propagation ([`context.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/transport.ts).