How the OpenSEO MCP Server Enables AI Agent Integration

OpenSEO's MCP server exposes the platform's SEO backend as a standardized set of JSON-RPC tools that any AI agent can invoke via the /mcp endpoint, enabling real-time keyword research, SERP analysis, and backlink inspection without hard-coded HTTP calls.

The OpenSEO repository implements a Model Context Protocol (MCP) server that transforms its SEO backend into a language-agnostic interface for AI agents. By adhering to the official @modelcontextprotocol SDK, the platform allows compatible clients like Claude, Cursor, and Codex to execute complex SEO workflows through a single standardized endpoint.

Architecture of the OpenSEO MCP Server

The MCP server follows a request-scoped architecture to ensure concurrent client connections remain memory-efficient and isolated.

Request Lifecycle and Transport Layer

When a request hits the /mcp endpoint, src/server/mcp/transport.ts instantiates a fresh McpServer instance for that specific connection. This per-request instantiation (approximately 5 MiB per instance) prevents memory exhaustion when handling multiple concurrent AI agents.

const server = new McpServer({ /* …options… */ });

The transport layer then invokes createMcpHandler(server, { … }) from the agents/mcp package to construct an HTTP handler. This handler validates MCP-protocol headers, manages authentication via src/server/mcp/context.ts, and routes JSON-RPC style calls to the appropriate registered tools.

Tool Registration and Discovery

The function registerOpenSeoMcpTools(server), defined in src/server/mcp/server.ts, populates the server instance with SEO-specific capabilities. Each tool resides in src/server/mcp/tools/ and conforms to the MCP contract by returning a standardized mcpResponse object.

The registration process maps tool names to their implementations:

• Keyword research via research-keywords.ts
• Search Console queries via search-console-tools.ts
• Site audit utilities via site-audit-tools.ts
• Saved keyword management via save-keywords.ts and list-saved-keywords.ts

Authentication and Project Scoping

Every MCP request must include an Authorization header. The buildProjectMeta function in src/server/mcp/context.ts extracts the user and project ID, enforcing the mcp scope before execution. Additionally, src/server/mcp/project-auth.ts wraps each tool invocation to ensure agents can only access OpenSEO projects explicitly granted to their authentication token.

Core SEO Tools Available to AI Agents

The MCP server exposes the following SEO capabilities through standardized tool calls:

• Keyword Research (src/server/mcp/tools/research-keywords.ts): Retrieves search volume, CPC, keyword difficulty, and related terms for any query.
• SERP Analysis (src/server/mcp/tools/search-console-tools.ts): Pulls live Google Search Console data including clicks, impressions, and average positions.
• Backlink Inspection (src/server/mcp/tools/site-audit-tools.ts): Returns backlink counts, domain authority metrics, and anchor-text distributions.
• Keyword Management (src/server/mcp/tools/save-keywords.ts): Persists and retrieves custom keyword lists associated with specific projects.

All tools return formatted responses via helpers in src/server/mcp/formatters.ts, ensuring consistent JSON structures that AI agents can parse reliably.

Implementing AI Agent Connections

Connecting from Claude, Cursor, or Codex

AI clients connect to OpenSEO by configuring the MCP endpoint URL and implementing the platform's JWT authentication flow. The following pseudocode demonstrates the connection pattern:

// Pseudocode for any MCP-compatible client
const mcp = new McpClient({
  endpoint: "https://app.openseo.so/mcp",
  tokenProvider: async () => {
    // OpenSEO will pop a login window; return the issued JWT
    return await getOpenSeoJwt();
  },
});

// Example: ask the agent to research keywords for "budget travel"
const result = await mcp.call("research-keywords", {
  query: "budget travel",
  projectId: "proj_123",
});
console.log(result);

Creating Custom MCP Tools

Developers can extend the OpenSEO MCP server by adding new tools that follow the established contract. A custom tool receives the MCP context and input parameters, then returns a formatted response:

// src/server/mcp/tools/my-custom-tool.ts
import { mcpResponse } from "@/server/mcp/formatters";

export async function myCustomTool(ctx, input) {
  const data = await doSomethingSpecial(input);
  return mcpResponse({ data });
}

Register the new tool in src/server/mcp/server.ts:

import { myCustomTool } from "./tools/my-custom-tool";

export function registerOpenSeoMcpTools(server) {
  server.registerTool("my-custom-tool", myCustomTool);
  // …other tools…
}

Once registered, AI agents can invoke the custom tool using the same mcp.call() pattern as native OpenSEO tools.

Summary

• The OpenSEO MCP server converts SEO backend operations into standardized JSON-RPC tools accessible via the /mcp endpoint.
• src/server/mcp/transport.ts creates isolated McpServer instances per request (~5 MiB each) to support high concurrency.
• Tool registration occurs in src/server/mcp/server.ts, while src/server/mcp/context.ts and src/server/mcp/project-auth.ts handle authentication and project-level access control.
• AI agents can execute keyword research, SERP lookups, backlink analysis, and saved keyword management through a unified protocol without platform-specific HTTP integrations.
• Custom tools follow a simple contract—receiving context and input, returning mcpResponse—and integrate seamlessly into the existing tool registry.

Frequently Asked Questions

What is the Model Context Protocol (MCP) and why does OpenSEO use it?

The Model Context Protocol is a language-agnostic JSON-RPC standard that allows AI agents to discover and invoke external tools as if they were local functions. OpenSEO implements MCP to eliminate the need for agents to hard-code HTTP client logic, instead providing a standardized interface that works across Claude, Cursor, Codex, and other compatible clients.

How does OpenSEO handle authentication for MCP requests?

Every MCP request must include an Authorization header containing a valid JWT. The buildProjectMeta function in src/server/mcp/context.ts validates this token and extracts the user and project ID, while src/server/mcp/project-auth.ts ensures the requesting agent has explicit access to the targeted OpenSEO project before executing any tool.

Can I self-host the OpenSEO MCP server?

Yes. The MCP endpoint attaches to the standard Next.js API route defined in src/server.ts, meaning self-hosted instances can expose their own MCP URL (typically https://your-domain.com/mcp) by configuring the appropriate environment variables and authentication providers in src/server/mcp/context.ts.

What is the memory overhead of concurrent MCP connections?

According to the source code in src/server/mcp/transport.ts, each MCP request instantiates a fresh McpServer instance consuming approximately 5 MiB of memory. This per-request isolation prevents resource exhaustion when multiple AI agents connect simultaneously, though system administrators should capacity-plan based on expected concurrent connection volumes.

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