What Is the Model Context Protocol (MCP) Server in OpenSEO?

OpenSEO's Model Context Protocol (MCP) server is an HTTP endpoint at /mcp that exposes SEO-focused tools—keyword research, SERP inspection, backlink profiling, and more—to any MCP-compatible AI client such as Claude, Cursor, or Codex.

The OpenSEO MCP server bridges AI agents and production SEO data. Instead of building custom integrations, developers and AI systems can invoke OpenSEO's backend services as remote procedures through a standardized protocol. This article explains how the MCP server works, how to authenticate and call it, and where the implementation lives in the every-app/open-seo repository.

How the MCP Server Works

The MCP server operates as a layered HTTP pipeline. Each layer validates, authorizes, and routes requests to the correct SEO tool implementation.

Transport Layer: Receiving MCP Requests

The src/server/mcp/transport.ts file defines the entry point. It mounts on the path /mcp and performs three critical validations before handling any tool call:

• CORS validation for cross-origin browser requests
• MCP headers (Mcp-Method, Mcp-Name) identifying the requested tool
• Authentication via OAuth Bearer tokens or API keys

curl -X POST https://app.openseo.so/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Method: whoami" \
  -H "Mcp-Name: whoami" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -d '{}'

Handler Dispatch and Context Building

Once validated, the transport creates an MCP handler using createMcpHandler from the agents/mcp package. This handler builds execution context through src/server/mcp/context.ts, which constructs a ProjectMeta object containing:

• The authenticated user ID
• The target project ID
• Granted scopes (user, sam, mcp)

This context enforces that AI clients receive scoped access—they cannot operate outside their authorized projects.

Authorization and Tool Execution

Before any tool runs, two auth layers verify permissions:

• src/server/mcp/project-auth.ts – Ensures the caller owns or has access to the requested project
• src/server/mcp/api-key-auth.ts – Validates API key scope and rate limits

With authorization confirmed, the dispatcher routes to the appropriate tool in src/server/mcp/tools/*. Each tool implements specific SEO logic:

Tool File	Purpose
research-keywords.ts	Keyword volume, difficulty, and opportunity metrics
get-serp-results.ts	Live search engine results page inspection
list-projects.ts	Enumerate available projects for the authenticated user

Results are wrapped by mcpResponse() in src/server/mcp/formatters.ts to ensure MCP-compatible JSON structure.

Server Integration

The src/server/mcp/server.ts file wires all components together and registers the endpoint as part of the main Fastify server defined in src/server.ts.

Calling the OpenSEO MCP Server

Using Claude's MCP CLI

Claude Code provides native MCP client support. Add OpenSEO as a remote server, then invoke tools directly:

claude mcp add --transport http --scope user openseo https://app.openseo.so/mcp

claude mcp call openseo research-keywords '{"projectId":"proj_abc","keywords":["svelte","vite"]}'

The claude-code-plugin.md documentation (web/content/docs/claude-code-plugin.md) contains detailed setup instructions for this integration.

JavaScript/TypeScript Client

For programmatic access, use the agents/mcp/client package:

import { createMcpClient } from "agents/mcp/client";

const client = createMcpClient({
  url: "https://app.openseo.so/mcp",
  headers: { Authorization: `Bearer ${process.env.OPENSEO_API_KEY}` },
});

async function research() {
  const res = await client.call({
    method: "research-keywords",
    name: "research-keywords",
    args: { projectId: "proj_1", keywords: ["react hooks"] },
  });
  console.log(res);
}

research();

The call routes through src/server/mcp/tools/research-keywords.ts, which queries the keyword-metrics database and returns structured rankings data.

Implementing Custom MCP Tools

The modular architecture in src/server/mcp/tools/ makes it straightforward to extend the server's capabilities. A new tool requires:

1. An async function accepting ToolContext and typed input
2. Return value wrapped by mcpResponse() for consistent formatting
3. Registration in src/server/mcp/server.ts

// src/server/mcp/tools/example-tool.ts
import { mcpResponse } from "@/server/mcp/formatters";
import { type ToolContext } from "@/server/mcp/context";

export async function exampleTool(ctx: ToolContext, input: { msg: string }) {
  return mcpResponse({
    result: { echo: input.msg, user: ctx.auth.userId },
    meta: { source: "mcp" },
  });
}

Summary

• OpenSEO's MCP server exposes SEO tools through a standardized HTTP endpoint at /mcp, enabling AI agents to invoke keyword research, SERP analysis, and backlink profiling as remote functions.

• Request flow: Transport validation → context building → authorization → tool dispatch → formatted response.

• Key source files: src/server/mcp/transport.ts (entry), src/server/mcp/server.ts (orchestration), src/server/mcp/tools/* (implementations), src/server/mcp/formatters.ts (response wrapping).

• Authentication: OAuth Bearer tokens or scoped API keys, enforced by project-auth.ts and api-key-auth.ts.

• Documentation: web/content/docs/mcp.md covers endpoint configuration and available tools.

Frequently Asked Questions

What AI clients support the OpenSEO MCP server?

Any client implementing the Model Context Protocol can connect. Verified compatible clients include Claude Code, Cursor, and Codex. The protocol standardizes tool discovery, invocation, and response formatting so clients interact with OpenSEO without custom integration code.

How do I authenticate requests to the MCP endpoint?

Authentication uses OAuth 2.0 Bearer tokens or API keys passed in the Authorization: Bearer <token> header. The src/server/mcp/api-key-auth.ts module validates key scope and rate limits, while src/server/mcp/project-auth.ts verifies project-level permissions. Generate API keys from your OpenSEO project settings.

What SEO tools are available through the MCP server?

Available tools include keyword research (volume, difficulty, CPC), SERP inspection (live results for any query), domain overview (authority, backlink counts), backlink profiling (referring domains, anchor text), rank tracking (position history), and Google Search Console data (impressions, clicks, queries). The full list is documented in web/content/docs/mcp.md and discoverable via MCP's tool introspection.

Can I self-host or extend the MCP server?

Yes. The entire implementation is open-source in the every-app/open-seo repository. Fork the repository, modify tool implementations in src/server/mcp/tools/, or add new routes in src/server/mcp/server.ts. The agents/mcp package handles protocol compliance, so custom tools automatically work with standard MCP clients.

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