How the OpenSEO MCP Server Enables AI Agent Integration

The OpenSEO MCP server exposes the platform's SEO backend through the Model Context Protocol, allowing any AI client to call keyword research, SERP lookups, and site audits via a standard JSON-RPC interface at /mcp.

OpenSEO is an open-source SEO platform that ships with a built-in MCP (Model Context Protocol) server for AI agent integration. By implementing the official @modelcontextprotocol SDK, the repository transforms its backend into a discoverable toolset that Claude, Cursor, Codex, and other MCP-compatible agents can invoke without custom API integration.

How the MCP Server Processes Requests

The OpenSEO MCP server handles each request through a four-stage pipeline implemented across src/server/mcp/transport.ts and related modules.

1. Per-Request Server Instantiation

To support concurrent clients without memory exhaustion, src/server/mcp/transport.ts creates a fresh McpServer instance (~5 MiB) for every incoming request:

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

This isolation pattern prevents state leakage between AI agents.

2. Tool Registration

The registerOpenSeoMcpTools(server) function in src/server/mcp/server.ts attaches the full SEO tool library. Each tool follows the MCP contract by returning a mcpResponse and lives in src/server/mcp/tools/:

• Keyword research (research-keywords.ts) — volume, CPC, difficulty, related terms
• SERP data (search-console-tools.ts) — Google Search Console clicks, impressions, positions
• Backlink inspection (site-audit-tools.ts) — counts, domain authority, anchor text
• Saved keyword management (save-keywords.ts, list-saved-keywords.ts)

3. Handler Creation with Auth

The createMcpHandler(server, { … }) from the agents/mcp package builds an HTTP handler that:

• Validates MCP-protocol headers
• Performs authentication/authorization via src/server/mcp/context.ts
• Routes JSON-RPC calls to registered tools

4. Endpoint Exposure

The handler mounts to the Next.js API route in src/server.ts, making https://app.openseo.so/mcp the single entry point for all MCP clients.

Authentication and Project Scoping

Every request must include an Authorization header. The context code in src/server/mcp/context.ts extracts the user and project ID through buildProjectMeta and enforces the mcp scope.

The src/server/mcp/project-auth.ts helper wraps each tool to ensure agents can only access projects they own or collaborate on.

Why MCP Works for AI Agents

MCP defines a language-agnostic JSON-RPC protocol that agents treat as native function calls. OpenSEO's implementation eliminates hard-coded HTTP integrations—agents discover and invoke tools dynamically.

Available operations include:

• research-keywords — fetch keyword metrics from research-keywords.ts
• search-console.query — pull live GSC data via search-console-tools.ts
• site-audit.backlinks — inspect link profiles through site-audit-tools.ts
• keywords.save / keywords.list — manage custom keyword lists

All tools share the same endpoint, enabling complex SEO workflows through natural language orchestration.

Connecting an AI Client

Add the MCP server URL to any compatible client with OpenSEO authentication:

// 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);

Adding Custom MCP Tools

Extend the server by creating a tool function that receives the MCP context and returns mcpResponse:

// 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 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…
}

Agents call custom tools identically: await mcp.call("my-custom-tool", { … }).

Key Implementation Files

Purpose	File Path
Per-request server & HTTP handler	src/server/mcp/transport.ts
Tool registration	src/server/mcp/server.ts
Auth and project context	src/server/mcp/context.ts
Keyword research tool	src/server/mcp/tools/research-keywords.ts
Search Console tools	src/server/mcp/tools/search-console-tools.ts
Site audit tools	src/server/mcp/tools/site-audit-tools.ts
Response formatting	src/server/mcp/formatters.ts
URL construction	src/server/mcp/public-origin.ts
Project authorization wrapper	src/server/mcp/project-auth.ts

Summary

• OpenSEO MCP server runs at /mcp using the official @modelcontextprotocol SDK
• Per-request isolation via fresh McpServer instances prevents memory exhaustion
• Standardized tools for keyword research, SERP data, backlinks, and keyword management
• JWT-based auth with project scoping through context.ts and project-auth.ts
• Extensible architecture for adding custom SEO tools without protocol changes

Frequently Asked Questions

What is MCP in OpenSEO?

MCP (Model Context Protocol) is an open standard that OpenSEO implements to expose its SEO backend as callable tools. The protocol uses JSON-RPC over HTTP, allowing any compatible AI agent to discover and invoke OpenSEO operations without custom API code.

How do I authenticate with the OpenSEO MCP server?

Pass a valid OpenSEO JWT in the Authorization header. The server validates tokens through src/server/mcp/context.ts and enforces project-level access via src/server/mcp/project-auth.ts. Clients typically obtain tokens through OpenSEO's OAuth login flow.

Can I self-host the OpenSEO MCP server?

Yes. The MCP endpoint mounts to any Next.js deployment of the open-source repository. Update src/server/mcp/public-origin.ts to reflect your domain, and configure the /mcp route in src/server.ts for your infrastructure.

Which AI clients work with OpenSEO's MCP server?

Any MCP-compatible client works, including Claude Desktop, Cursor, GitHub Copilot (CodeX), and custom implementations using @modelcontextprotocol SDKs. The server uses standard tool discovery and JSON-RPC invocation patterns defined by the MCP specification.

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