How the OpenSEO MCP Server Exposes SEO Tools to AI Agents Like Claude Code

The OpenSEO MCP server exposes SEO tools to AI agents through a JSON-RPC API endpoint at /mcp, where authenticated requests trigger Zod-validated tool handlers that execute DataForSEO and Google Search Console operations.

The every-app/open-seo repository implements a Model Context Protocol (MCP) server that transforms SEO workflows into callable functions for AI agents. By registering tools with strict input/output schemas and handling OAuth-authenticated requests through a dedicated transport layer, the system allows Claude Code, Cursor, and other MCP clients to perform keyword research, backlink analysis, and search console operations programmatically.

MCP Server Architecture: Three-Layer Design

The OpenSEO MCP implementation follows a layered architecture that separates transport concerns from business logic. This structure ensures that AI agents interact with a stable, versioned API while the underlying SEO data sources remain abstracted.

Transport and Request Handling (transport.ts)

The entry point resides in src/server/mcp/transport.ts, where the handleAuthenticatedOpenSeoMcpRequest function validates incoming requests. This layer performs several critical functions:

• CORS validation: Ensures requests originate from approved hosts and origins
• Authentication: Parses the OAuth Bearer token and verifies the mcp scope is present in the token claims
• Request routing: Distinguishes between modern MCP protocol requests and legacy JSON-only clients via createRequestHandler
• Transport creation: Instantiates a WebStandardStreamableHTTPServerTransport to manage the HTTP stream

When a request arrives at the /mcp endpoint, the transport layer creates a ToolContext object (defined in src/server/mcp/context.ts) that encapsulates the authenticated user, target project, and request metadata, then forwards the request to the MCP server handler.

Server Initialization and Tool Registration (server.ts)

The core server logic lives in src/server/mcp/server.ts within the createOpenSeoMcpServer function. This module initializes an McpServer instance with metadata including the server name, version, description, and icon assets.

Tool registration occurs through a centralized register function:

// src/server/mcp/server.ts (excerpt)
const register = <Input extends ToolSchema>(tool: OpenSeoToolDefinition<Input>) =>
  registerOpenSeoTool(server, tool, authProps);

register(researchKeywordsTool);
register(getBacklinksOverviewTool);

Each tool definition includes:

• Input schema: Zod validation schemas that enforce type safety on incoming parameters
• Output schema: Structured response formats that AI agents can reliably parse
• Handler function: Async implementation that receives the validated arguments and ToolContext

Tool Implementations (tools/ directory)

Individual SEO capabilities reside as separate modules in src/server/mcp/tools/. For example, research-keywords.ts exports a complete tool definition:

// src/server/mcp/tools/research-keywords.ts
export const researchKeywordsTool: OpenSeoToolDefinition<{
  keyword: string;
  projectId: string;
}> = {
  name: "researchKeywords",
  config: {
    title: "Research Keywords",
    description: "Fetch keyword metrics from DataForSEO.",
    inputSchema: z.object({
      keyword: z.string(),
      projectId: z.string(),
    }),
    outputSchema: z.object({
      volume: z.number(),
      cpc: z.number(),
      difficulty: z.number(),
    }),
  },
  handler: async (args, ctx) => {
    const data = await fetchDataForSeo(args.keyword, ctx.projectId);
    return { result: data };
  },
};

Other tools like get-backlinks-overview.ts and modules in search-console-tools.ts follow this same pattern, ensuring consistent error handling and response formatting across the API surface.

Authentication and Security Flow

Before any tool executes, the transport layer enforces strict authentication requirements:

1. Token extraction: The Authorization: Bearer <token> header is parsed and validated
2. Scope verification: The OAuth token must explicitly include the mcp scope to proceed
3. Membership validation: The handler confirms the authenticated user belongs to the organization associated with the requested project
4. Context injection: Upon validation, a ToolContext object containing the user, project, and organization is injected into the tool handler

This security model ensures that AI agents can only access SEO data for projects they are explicitly authorized to view, even when the MCP server exposes potentially sensitive search console metrics.

Tool Invocation Workflow

When Claude Code or another MCP client invokes a tool, the request follows this execution path:

// Request payload sent to https://<host>/mcp
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "researchKeywords",
  "params": {
    "keyword": "organic coffee beans",
    "projectId": "proj_12345"
  }
}

The server processes this through the following steps:

• Method routing: The MCP server looks up the tool by the method name in its registry
• Schema validation: Input parameters are validated against the tool's Zod schema; failures return structured validation errors
• Business logic execution: The handler calls external APIs like DataForSEO or Google Search Console using credentials stored in the ToolContext
• Response wrapping: Results are wrapped with mcpResponse to conform to MCP protocol specifications before transmission

Preventing Tool Drift with Shared Definitions

A critical architectural decision in the OpenSEO codebase prevents divergence between the MCP server and the native web application. The tool definitions registered in src/server/mcp/server.ts are shared with the in-app SAM agent defined in src/server/features/sam/samChatTools.ts.

Because both interfaces import from the same tool definition modules, any modification to a tool's schema, description, or validation logic automatically propagates to both AI agents connecting via the MCP protocol and the internal chat interface. This eliminates "tool drift" where external APIs might behave differently than the web application's internal tools.

Summary

• Transport layer (src/server/mcp/transport.ts) validates OAuth tokens with the mcp scope and manages HTTP streaming via WebStandardStreamableHTTPServerTransport
• Server layer (src/server/mcp/server.ts) instantiates the MCP server and registers SEO tools using createOpenSeoMcpServer and the register helper
• Tool layer (src/server/mcp/tools/) contains individual implementations like researchKeywordsTool with Zod schemas and DataForSEO integration
• Authentication requires Bearer tokens with the mcp scope, validated against organization membership before context injection
• Shared definitions with src/server/features/sam/samChatTools.ts ensure consistency between external AI agents and the internal SAM chat interface

Frequently Asked Questions

What MCP protocol version does OpenSEO support?

OpenSEO supports the modern Model Context Protocol specification through the createMcpHandler function in transport.ts, while maintaining backward compatibility with legacy JSON-RPC clients via a fallback handler. The implementation uses the WebStandardStreamableHTTPServerTransport class to handle streaming responses as defined in the MCP specification.

How do I authenticate requests to the OpenSEO MCP server?

Include an Authorization: Bearer <token> header where the token is an OAuth 2.0 token containing the mcp scope. The server validates this token in handleAuthenticatedOpenSeoMcpRequest, verifies the user has access to the specified project, and constructs a ToolContext object containing the authenticated entities before executing any tool logic.

Can I use the same SEO tools outside of the MCP server?

Yes. The tool definitions in src/server/mcp/tools/ are imported by both the MCP server (src/server/mcp/server.ts) and the internal SAM agent (src/server/features/sam/samChatTools.ts). This shared architecture means any tool available to Claude Code via the MCP interface is also available within the OpenSEO web application's chat interface, with identical validation and business logic.

What SEO data sources does the MCP server integrate with?

The tool implementations integrate with DataForSEO for keyword research and competitive analysis, and Google Search Console for performance metrics and indexing data. Each tool handler manages its own external API connections, using project-specific credentials stored in the ToolContext to ensure data isolation between organizations.

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